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, but you are not ready to send a pull request to the central repo. But you want to make a minor change quickly 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.

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

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

$ 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
  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/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 [email protected]:<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 [email protected]:<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.