Git Notes Topic Branches

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

Suppose you are working in your development branch and things are in a pretty rough state, no way you are close to ready to send a pull request to the central repo. But now you get a minor request from a user via Issues that you want to deal with quickly and send out to the group. You cannot simply make the fix in your development branch and merge a single file. The solution is to create a topic or feature branch.

We will use Issue 2440 as an example and assume you have forked the firemodels/fds-smv repo and set it up for remote tracking as "firemodels" (see Git User Workflow).

First, create a topic branch from the upstream development branch.

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

Now look at your branches.

$ git branch -a
  development
  gh-pages
* 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/development' 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 [email protected]:<username>/fds-smv.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 development branch on firemodels/fds-smv. If you are a developer, send the request and merge it yourself.

Once the topic branch has been merged with firemodels/development, 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 [email protected]:<username>/fds-smv.git
 - [deleted]         issue2440

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

$ git checkout development
Switched to branch 'development'

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/development
Updating 38b0e3a..8415e02
Fast-forward, etc.

Push to your forked repo:

$ git push origin development
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.