The Foursquare Blog

Git has the ability to specify ranges of commits, with flexible variations.

But with that flexibility comes complexity. Have you ever wondered what the difference was between "commit1..commit2" and "commit1...commit2"?

If so, then this mini howto is for you.

(If you want to follow along, use the sample setup commands at the end of this document)

1. What is a branch?

It is helpful to remember that git thinks of a branch as any name or tag that refers to a SHA1 commit ID. The branch represented by that commit includes that commit itself along with all the ancestors that make it up.

For example:

        git log master

will show you the master commit, with all the parent commits that belong to it. If you say:

        git log master desktop

it will list all the ancestor commits of both master and desktop.

2. Commit walking

The command git-rev-list takes a list of commits and prints the SHA1 commit IDs of all the ancestors for those commits. This is a low level git command and is the basis for specifying commit ranges.

For example, on a repository I have on my hard disk, I have the following branch structure:

               /---o---o master
              /
        o----o (base)
              \
               \---o---o desktop

The following command:

        git rev-list master | wc -l

shows 3 commits. If I include the desktop branch, which has 2 unrelated commits in it, and does not have the 2 commits from master:

        git rev-list master desktop | wc -l

it shows 5 commits.

This shows that specifying multiple branch names is inclusive. All commits from all branches are included in the resulting list of ancestors.

3. Limiting the list

If I want to see all commits that are in master but not in desktop, I can invert one of the branches:

        git rev-list master ^desktop | wc -l

This shows 2. The two commits on the master branch. I can verify this with:

        git log master ^desktop

which shows only the patches on the master branch.

I can reverse this as well, showing only the 2 commits on the desktop branch:

        git log ^master desktop

The shorthand for this is the 2 dot ellipsis. The following are identical:

        git log ^master desktop
        git log master..desktop

Again, reversing, the following are identical:

        git log master ^desktop
        git log desktop..master

4. Finding the branch point

Git does not store branch divergence points. This can be calculated on the fly by looking at the heads of two branches and finding the first common commit in the list of ancestors.

This job is done by git-merge-base. If we used it on the above branch structure, we would get a SHA1 commit ID of the point marked (base) above.

        git merge-base master desktop

This returns c79f6f286e720b39976531b7a5b713b87308b576 in my repo. It will be different in yours, since you have different author information.

5. Listing all changes

Using what we know, we can now list all the changes on both branches that are not in the main repo:

        git log master desktop ^c79f6f

This shows 4 commits, from both branches.

The shortcut to this, is the triple ellipsis:

        git log master...desktop

Basically, this means show all the commits from both branches that happened since they diverged.

6. Diff: turn the world upside down

This is all fine and good, but wait! The git-diff command turns this inside out.

Git-diff takes two branches and shows a unified diff patch between the _endpoints_ that they represent. The usual format of the command is as follows:

        git diff master desktop

This will create a patch which, if applied to master, will turn it into desktop. i.e. it removes the 2 changes done on master and adds the 2 changes done on desktop.

The reverse will do as expected:

        git diff desktop master

This is the same as having two trees checked out, and running a manual diff -ru on them from the command line.

The double ellipsis is used in git-diff as well, but has no special meaning. It is an alias for the above usage. The following are identical:

        git diff master desktop
        git diff master..desktop

The difference in git-diff is that the triple ellipsis uses the same logic as git-log does when finding the merge-base, but the result is the difference between the base and _one_ of the branches.

For example:

        git diff master...desktop

This will find the branch point of master and desktop, and then generate a diff between that base commit and the commit of desktop.

In other words, the diff will contain only the 2 changes on the desktop branch, and is effectively the same as:

        git diff c79f6f desktop
or
        git diff $(git merge-base master desktop) desktop

Reversing the options will do the same for master. The following commands are identical:

        git diff desktop...master
        git diff c79f6f master

Now, the diff will contain only the 2 changes on the master branch.

The parsing logic of the triple ellipsis range is the same, but the result is the opposite. With git-log, all 4 commits are shown, with git-diff, only 2 commits from one side of the branch are shown.

7. Play

Pasting the following commands into a shell will create a sample branch with which you can experiment with these range specifiers.

mkdir play
cd play
git init
echo data > file.txt
git add file.txt
git commit -m "Initial commit"
echo data > README
git add README
git commit -m "Added README"
echo data > license
git add license
git commit -m "Added license file"
git checkout -b desktop master^^
echo data > main.c
git add main.c
git commit -m "New source code"
echo data >> main.c
git commit -a -m "Bug fix"
git checkout master

Enjoy.

Thanks to Ilari on #git irc.freenode.net for the discussion that lead to enlightenment.

This is where the --onto switch comes in, with git-rebase.

For example:

git checkout -b staging master
[make changes]
git checkout -b base_url staging
[make changes]
git rebase --onto master staging

This does: finds all the commits between the current branch (base_url) and staging, switches base_url's HEAD to master, and then reapplies the above found commits. You end up with a base_url branch that looks like it was only branched from master originally.