JP's Wiki | Git / Branches

Branches are a way to perform experimental work on code without risking to after the regular flow of code development.

Consider the repository as a river system, which is growing as the project develops. From that river, the master branch, the water can be diverted into streams. These are branches, where new features are tested and ongoing development happens. From these branches, even more branches can spring.

Different streams can also be merged, where there water will mix. Similarly, branches can be merged to create code that contains the features of both. Beware of having multiple branches modifying the same thing, as that will result in conflicts which, even though they are not critical, can be a pain to solve. For this reason, it is better to have a specific, well defined idea of what a branch sets out to achieve and stay away from "mega-branches" that try to change everything, unless you don't intent to merge it or are ready to deal with the trouble.

A typical work stream, even if you are the only user of a repository, should look like:

M W1 W2
| |  |
|\|  /
| | /
| |/
| |
| /
|/
|
|

Where M represents the master branch. This is what the real program/code/document is, what you would share with someone else who would come into the project. W1 is the first branch created, to work on the project. In this case it has been merged back into the M branch once. W2 is itself a branch of W1, maybe for further developing a subfeature. Eventually, it will be merged back into W1, which itself will be merged back into M when the whole feature is completed.

To create a branch and move onto it, the commands are:

git branch NewBranchName
git checkout NewBranchName

Try to be explicit in the name of the branch, so you know what it is when you get back to the project after a break, or especially if someone else might look into it eventually. Alternatively, you can do both in one command with:

git checkout -b NewBranchName

Once working on a branch, you can commit, checkout old commits and everything as usual, all of it will stay on the branch you are working on. To "jump" branches, you need to use git checkout, but replace the NameOfNewBranch with the name of an existing branch.

Renaming branches

To rename a given branch:

git branch -m OldName NewName
git branch -m NewName

or the second one for the active branch.

Listing branches

To see all the branches in the repo:

git branch --list

Note that this will only show local branches. Use the -d option instead to see remote branches as well.

Updating branches

While working on a branch, you might want to update it with changes made in the master branch (ex.: Someone else just merged their branch into the master branch and you want the new feature in your branch too). In order to do so, you need to be the master branch on your repository, git pull to update your local master branch, in your working branch, then merge the master one into it. This will also help with merging your working branch into the master branch later, since they will be less different. Ideally, branches should be merged in the master branch only when they are based on the latest commit of master. If they were started in a precedent version of master, they need to be updated first.

Deleting branches

git branch -d BranchToBeDeleted

Adding Remote Branches

Branches may be created on remote repositories, which you want to track even though they are not in your current repo. A simple git pull will not do the trick, since that would simply update the current branch. In order to get the new branch, the command is:

git checkout --track RemoteRepo/NewBranch

You can also set a local branch to track a remote branch.