Git Notes Topic Branches

This wiki discusses how to use topic branches to address user Issues.

Suppose you have pushed changes to the master branch of your forked repository that are not ready to be merged to the central repo. Then, for whatever reason, you need to make a quick minor change and have it merged with the central repo. You cannot simply make the fix in your master branch and merge a single file. The solution is to create a topic or feature branch.

Let's assume you have forked the firemodels/fds repo and set it up for remote tracking as "firemodels" (see Git Notes Getting Started).

First, create a topic branch from the upstream master branch. Call the topic branch whatever you want; in this case, issue2440 because this is the name of the GitHub issue you happen to be working on.

$ git checkout -b issue2440 firemodels/master
Branch issue2440 set up to track remote branch master from firemodels by rebasing.
Switched to a new branch 'issue2440'

Now look at your branches.

$ git branch -a
  master
* issue2440
  ...

Make your changes, add, and commit the changes. Now check your status.

$ git status -uno
# On branch issue2440
# Your branch is ahead of 'firemodels/master' by 1 commit.
#

Now you need to push your new topic branch up to your repo on GitHub.

$ git push -u origin issue2440
Counting objects: 9, done.
Delta compression using up to 12 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 657 bytes, done.
Total 5 (delta 4), reused 0 (delta 0)
To git@github.com:<username>/fds.git
 * [new branch]      issue2440 -> issue2440
Branch issue2440 set up to track remote branch issue2440 from origin by rebasing.

Now you can send a pull request to the master branch on firemodels/fds. If you are a developer, send the request and merge it yourself.

Once the topic branch has been merged with firemodels/master, GitHub will tell you it is OK to delete the topic branch from your forked repo. Go ahead and do this.

If you decide not to let GitHub delete your topic branch, you can do it manually as follows:

$ git push origin :issue2440
To git@github.com:<username>/fds.git
 - [deleted]         issue2440

Next, in your local repo, you need to switch branches back to development:

$ git checkout master
Switched to branch 'master'

Now do a remote update to fetch the changes from the central repo:

$ git remote update
Fetching origin
Fetching firemodels
remote: Counting objects:, etc.

Merge the changes from the central repo:

$ git merge firemodels/master
Updating 38b0e3a..8415e02
Fast-forward, etc.

Push to your forked repo:

$ git push origin master
Counting objects: etc.

Delete your local topic branch:

$ git branch -d issue2440
Deleted branch issue2440 (was 4b957f6).

Finally, prune your remote working tree, else your topic branch will show up under $ git branch -a:

$ git remote prune origin

Done.