Note for all that follows: This may help you, but if it just confuses you, forget it. Just know that this exists, and that it might be useful. By the time you’re comfortable enough with the core concepts and tools, this may help. But you don’t have to know how to do branching to use version control. In fact, branching is fairly rare in most other version control systems.
A linear history is fine, but that is often not how science progresses.
Suppose that you’ve got your project working, but want to get tidy it up a bit in a way that requires major surgery and you want to be able to get back to where you were.
Alternatively, suppose that you want to try two different ways of implementing something.
In my case, I have a package that I mantain – sometimes I need to add bug fixes to the released version without wanting to publish the broken development code.
What if you wanted to go back to an old version and continue development from there?
In all of these scenarios, we might want to work on a “branch” of the project.
What do branches look like?
Suppose that we have a repository with three commits:
at the moment there is only one branch: “
master”. Now imagine that
we’re going to do some work starting at this point – we’ll create a
new branch that starts from our current point (
C2), in this case
iss53 (the diagrams come from the excellent
Pro Git book, and I’ve not redrawn them –
for an ecologist this might be “experiment” or “reorganise_data”).
We then continue to do work on this new branch:
At this point, we might be happy with the new work and just want to
merge the branches back together (moving the
master pointer up to
Alternatively, you might have to do some work on
your supervisor needs you to tweak a figure for a talk they are giving
right now, but your current state on
iss53 would break it). You
could then switch back to branch
master and do some more work there
(Note that the
iss53 branch has been renamed
Now you your history has diverged – both commits
C2 as a parent, but they consist of different work. You have a
choice of how you want to resolve the diverge this to get the work
C4 onto the same branch. First you can merge
the changes together:
this means that
C5 has two parents (
C4) and that it
includes the content of both.
Alternatively there is a strategy called rebase where we would
replay the changes on the
experiment branch on the
which gives a linear history:
What this does is to look at the difference between
then apply that difference to
C4 so that the new commit
contains the results of
C3. The old
C3 commit is then
Note that the contents of
C5 will likely be the same
at the end of these two operations – the difference is in the
interpretation of how they came into being.
Workflows that use branches
Branches most naturally appear in a project that is simultaneously being worked on by different people. It turns out the git will see branches in someone else’s repository essentially like branches in your own, and lots of cool ways of working with branches become possible.
They also are important for single-user workflows. I use them for testing ideas that I’m not sure about:
- Create a branch
- Commit a bunch of work to it
- Decide if I like the work and if so…
- Merge it back into the main branch
This idea is nicely formalised in this flow chart.
Much more complicated (but powerful in the right hands) workflows are possible, such as the so-called git-flow workflow.
git branch lists the branches git knows about. By
default, there is only one branch and it is called
The asterisk next to this indicates that this is the current branch.
If you pass in the
-v argument (for verbose), you get
which adds the shortened version of the SHA hash and the last commit message.
There are two ways of creating branches in git. The first is to use
git branch. The command
creates a new branch called
new_idea, but does not change to it.
git branch -v:
We now have two branches, both at the same point on the tree. The
asterisk indicates that we are on the branch
You can change to a branch by using
git checkout. So to switch to
new_idea branch, you would do:
which lets you know that it worked
You can switch back to master by doing
and can delete branches by passing
The other way of creating a branch and switching to it is to pass
as an argument to checkout:
git branch shows:
as we both created and switched to the new branch
How branches grow
New work is commited to the current active branch (the one with the
asterisk next to it in
git branch (at the moment this is the branch
new_idea. So if we edit a file and do
1 2 3
The history is now equivalent to this picture from before:
You can also see a picture of this with some arguments to
1 2 3 4
(which will even be in colour if you set that up)
Merging branches back together
Suppose that you are happy with the changes that you made and want to
merge them into your
To do the merge, you first check the
master branch back out:
which will output
which will output
1 2 3 4
telling you that
master was “fast-forwarded” from
37485b1, changing one file (
script.R) by inserting three lines and
The tree now has two branches that “point” at the last commit:
new_idea. We can delete the
new_idea branch with
-d argument stands for delete).
Merging when branches have diverged
If you have a history like this one:
as noted above you have two choices – you can merge or you can
rebase. Suppose for now that we have checked out
You would switch to to branch
master by running
and then merge the experiment in with
which gives a history like this:
The alternative would be to run
which results in a history like this:
In both cases, you could delete the experiment branch with
What you chose is often mostly a matter of taste (and there are a diversity of opinions on this). For a single-user workflow it often does not make much difference.
Sometimes, the change on a branch all falls in a logical chunk, and it
might make good sense to merge that in with
merge to reflect this in
your history. Other times, the different branches just reflect
working on different computers, or changes that make sense when
reordered linearly. In that case,
rebase is often the best bet.
Branches and old versions
Suppose that you want to look an old version (say,
C2 in the graphs
above). You can simply do to
which will produce the rather scary message:
1 2 3 4 5 6 7 8 9 10
What this means: - you can’t commit anything - any changes you make will be lost when you go back to a “proper” branch.
If you did want to start a branch here, you can do
which will start a new branch at the point
C2. You can then
continue adding to that branch with
git commit, or just easily
switch back to it.
You could also have done both things in one step, from
which would start a new branch called
revisit_old_analysis at the
point in history
Branching is git’s “killer feature” – the thing that it does better than most other version control systems. Branches are addictive, and once you get used to using them, you’ll find all sorts of use for them. Branches are very fast to create, to switch between, and to destroy. If they help you structure your work, you should use them!
There is an incredible Git branching demo that is useful to work through learning about git branches. It has a tutorial mode with lots of lessons, and a demo mode with a dizzying array of crazy history-altering moves.