1. Bio3D Project Avatar Bio3D Project
  2. Bio3D
  3. bio3d

Wiki

Clone wiki

bio3d / How to use Git and Bitbucket

View History

Motivation

Using Git and Bitbucket makes it easy to:

  • incorporate contributions from multiple developers working on the code at the same time
  • rewind time to undo mistakes or see what has changed between working code and broken code

Here we aim to provide a few basic pointers on using Git and Bitbucket with the bio3d package. We will also provide links to places were you can learn more advanced techniques.

Basic commands

Getting started (Note. the clone command may require your bitbucket passwd. Alternatively, you can add the public-key of your local computer to Bitbucket. See details in Manage account -> SSH keys):

$ git clone git@bitbucket.org:Grantlab/bio3d  # Download Bio3D source code for first time
$ git remote -v                               # Show remote servers (where you fetch from and push to)
$ git help foo                                # Get help for command foo

To update your local version with those on the server:

$ git pull                       # Automatically fetch and merge remote server

To push your local changes to the server so others can access:

$ git push                       # Push your master branch to server origin

Working with Git:

$ git status                     # Check status
$ git add foo                    # Stage file foo
$ git commit -a -m "Message..."  # Commit both staged and unstaged changes
$ git commit --amend -m "..."    # Change your last commit message to correct message errors
$ git log                        # Check commit history
$ git rm foo                     # Delete file foo
$ git mv foo bar                 # Change file name foo to bar

Branches

$ git branch                      # List branches
$ git checkout foo                # Switch to branch foo
$ git checkout -b foo             # Create a new branch foo and switch to it
$ git merge foo                   # Merge branch foo into the current branch
$ git merge foo --no-ff           # No-fast-farward merge; this command should always be used  
                                  #   when working on multiple brances such as master, feature, etc
$ git reset --merge ORIG_HEAD     # To UNDO a merge that you just committed but haven't pushed yet
$ git branch -d foo               # Delete local branch foo
$ git push origin develop         # Push branch develop to server origin
$ git push origin :develop        # Delete branch develop on server origin

$ git fetch                               # To get a copy of remote branch "feature": First fetch data,
$ git checkout -b feature origin/feature  # and then check the branch out

To add a tag for a release

$ git tag -a vXXX -m "Message here..."       # Tag current commit
$ git tag -a vXXX -m "Message here..." xxx   # Tag commit xxx
$ git push origin vXXX                       # Upload tag to remote repo
$ git tag -d vXXX                            # Delete tag
$ git push origin :refs/tags/vXXX            # Delete remote tag

To checkout a specific release version

$ git tag
$ git checkout -b oldver vXXX

Fixing conflicts

  1. Identify which files are in conflict (Git should tell you this, or use "git diff")
  2. Open each file and examine the diffs (Git demarcates them and hopefully it will be obvious which version of each block to keep - you may need to discuss with fellow developers)
  3. Once you've resolved the conflict in a file "git add the_file"
  4. When all the conflicts are handled and their files have been "git add"-ed, "git commit" will complete your merge

For conflicts that involve more than a few lines, it's easier to see what's going on in an external gui tool. I like opendiff -- git also supports vimdiff, gvimdiff, kdiff3, tkdiff, meld, xxdiff, and emerge.

$ git mergetool

Other useful commands include:

# Show common base version of the file.
$ git show :1:some_file

# Show 'ours' version of the file (which is non local).
$ git show :2:some_file

# Show 'theirs' version of the file (which is your local version).
$ git show :3:some_file.cpp

Remember that each time you edit a file to resolve a conflict "git add filename" will update the index and your diff will no longer show it. When all the conflicts are handled and their files have been git add-ed, git commit will complete your merge. See also this post

Common practices

An important note about Git commit messages. Please use a Capitalized, short (50 chars or less) summary. This can be followed, if necessary, by two return characters and a more detailed explanatory paragraph that is wrapped to about 72 characters (see link for details).

$ git commit -m "Rd Doc File Imporvments

Some fixes for the 'notrun' sections to aid online statidocs html doc 
generation with full examples being run - there are still some errors
in:
  - rmsip.Rd
  - bio3d.package.Rd
  - pca.xyz.Rd
  - pdb2aln.Rd
  - plot.core.Rd
  - print.core.Rd
  - read.all.Rd
  - read.mol2.Rd
  - seqaln.Rd
  - core.find.Rd

These will be easer to fix once we decide on a decent example dataset"

See also

IntroGit.pdf for a quick learning

Updated