Leniel Maccaferri's blog: branch

Today I sent a small pull-request to the awesome Font-Awesome project at GitHub. To do that I had to learn some bits along the way that diverted from the common path when working with GitHub.

Font-Awesome has a separate branch called gh-pages which hosts the GitHub Pages (site) for Font-Awesome. The change I was about to do should go inside that branch and not on the common master branch.

Generally when cloning a forked repo from GitHub it will bring/checkout only the master branch.

Problem: how can I do work on that gh-pages branch?

This is the solution that worked just fine in my case…

Take a look at the following screenshot:

Figure 1 - Checkout remote branch (not master) named gh-pages to a local branch with upstream tracking

Above I have Git bash (you can get it here) opened in the cloned repo folder. I used GitHub for Windows to clone the repo I forked from Font-Awesome.

When you open Git bash it has the (master) branch already checked out as you see in “yellow” above.

Executing the command:

git remote show origin

we see that the repo has 3 Remote branches, namely:

4.1.0-wip
gh-pages
master

however only the master branch is configured for git pull and git push on my local computer. That’s ok if I would do some work on the master branch. If that was the case I already had everything correctly setup but remember that I need to do work on the gh-pages branch. To do so, the following command must be executed:

git checkout –b gh-pages –-track origin/gh-pages

What this command does is:

With git checkout we create a new local branch called gh-pages and immediately switch to it with the –b parameter. See that the branch name matches the one from the remote origin, in this case, gh-pages.

The –-track parameter means that this new local branch has its upstream set to a remote branch, in this case origin/gh-pages.

This is the result I wanted.

As a visual clue, in the following screenshot you see that the branch now shows in Visual Studio 2013 Team Explorer window as the selected one. This means it made it to my local computer. Now I can work on it and when done I can click on that Changes link and push my changes to the remote origin.

Figure 2 - gh-pages branch appears in Published Branches in Visual Studio 2013 Team Explorer window

By the way, here’s the official doc reference for the checkout command. It depicts exactly what I wanted to do but had no idea how to do it Don't tell anyone smile :

git checkout <branch>

To prepare for working on <branch>, switch to it by updating the index and the files in the working tree, and by pointing HEAD at the branch. Local modifications to the files in the working tree are kept, so that they can be committed to the <branch>.

If <branch> is not found but there does exist a tracking branch in exactly one remote (call it <remote>) with a matching name, treat as equivalent to

$ git checkout -b <branch> --track <remote>/<branch>

You could omit <branch>, in which case the command degenerates to "check out the current branch", which is a glorified no-op with a rather expensive side-effects to show only the tracking information, if exists, for the current branch.

Hope it helps!

Update

Ops… hehehe. Just know I read the guideline to contribute to Font-Awesome… too late!

I should have submitted the pull request against the 4.1.0-wip branch where wip means (work in progress).

OK… I went further and did all the process again (a brand new pull request) but this time targeting the correct branch. I even learned a new thing using Git Gui (installed with Git tools):

Figure 3 - Creating a tracking branch with Git Gui with the same name [ 4.1.0-wip ] as defined in origin