Terminology
For the purposes of this tutorial I'll use some abbreviations short names to refer to particular git repositories.
local - your local repository that exists on your machine
origin - your forked version of the Sage Bionetworks repository (you did fork the repo on github right?)
upstream - the "official" repository that is owned by Sage Bionetworks on github.
Bringing in Upstream Changes
There are two basic paths for the git workflow:
- You have local changes committed to your local develop branch
- You have local changes committed to a local "feature" branch
Now, you see that the upstream repository has changes in it from one of your teammates checking in code (via code review!). In order for your changes to make it into upstream with a minimum of fuss, you need to bring in those changes before you can submit a pull request.
Changes to local develop branch
This is probably basically what your branch history looks like in this scenario:
A---B---C develop
\
D---E upstream/develop
The problem here, is that if you simply do a git pull to merge in the upstream changes, you'll get an extra commit, and if git resolves merge conflicts the wrong way you could potentially end up committing changes that undo whatever work occurred upstream. So instead what you want to do is this:
git fetch upstream # make sure you have all the latest info on your upstream repo
git checkout develop # be on your develop branch
git rebase upstream/develop
This should result in your history looking like this:
A---B---D---E upstream/develop
\
C' develop
Now move on to Sharing Your Changes
Changes to local "feature" branch
This is a little simpler. For it to work smoothly though, your local develop branch must be able to fast-forward to where upstream develop is. Put another way, your local develop branch must point at a commit that is a direct or indirect parent of the commit that upstream develop is pointing at.
That is if we have commits:
A---B---C---D---E---F
and upstream/master points to F, then develop points to any of A through E. Similarly, your feature branch can be based off of any commit on the develop branch (before or after your local develop).
Now you do
# You can skip this if you're already no the develop branch
git checkout develop
git pull upstream develop
Now assuming that you are done with the feature you're working on and want to bring your changes into the main develop branch so that you can issue a pull request. Now:
git merge my-feature
git branch -d myfeature # remove the now useless branch
Git should ask you to enter a commit message. Now you're ready to Share Your Changes
Sharing Your Changes
Now to share your changes with the rest of the team (starting from your local develop branch)
git push origin develop
Now go to your GitHub repository page and click the "Pull Request" button, mark the changeset as
Sage-Bionetworks/<repo-name>@develop to <your-name>/<repo-name>@develop
Then send someone an email, and schedule your code review!