git: programmatically know by how much the branch is ahead/behind a remote branch

Question

I would like to extract the information that is printed after a git status, which looks like:

# On branch master
# Your branch is ahead of 'origin/master' by 2 commits.

Of course I can parse the output of git status but this is not recommended since this human readable output is liable to change.

There are two problems:

1. How to know the remote tracked branch? It is often origin/branch but need not be.
2. How to get the numbers? How to know whether it is ahead/behind? By how many commits? And what about the diverged branch case?

Answer 1

In modern versions of git, @{u} points to the upstream of the current branch, if one is set.

So to count how many commits you are behind the remote tracking branch:

git rev-list --count HEAD..@{u}

And to see how far you are ahead of the remote, just switch the order:

git rev-list --count @{u}..HEAD

For a more human-readable summary, you could ask for a log instead:

git log --pretty=oneline @{u}..HEAD

For my own purposes, I am working on a script that will replace @{u} with an appropriate guess, if no upstream is yet set. Unfortunately there is at this time no @{d} to represent the downstream (where you would push to).

Answer 2

With recent versions of git you should use

git status --porcelain --branch

and check for ahead/behind:

## master...origin/master [behind 1]

--porcelain[=version]

Give the output in an easy-to-parse format for scripts. This is similar to the short output, but will remain stable across Git versions and regardless of user configuration. See below for details.

-b, --branch

Show the branch and tracking info even in short-format.

Answer 3

git status has a --porcelain option that is intended for parsing by scripts. It is based on the --short output - they are almost identical at the time of writing (see the "Porcelain Format" section of the git status man page for details). The main difference is that --short has colour output.

By default no branch information is shown, but if you add the --branch option you will get output like:

git status --short --branch
## master...origin/master [ahead 1]
?? untrackedfile.txt
...

If you are up to date (after a fetch), the branch line will just be:

## master

If you are ahead:

## master...origin/master [ahead 1]

If you are behind:

## master...origin/master [behind 58]

And for both:

## master...origin/master [ahead 1, behind 58]

Note that git status --porcelain --branch is only available in 1.7.10.3 or later (though git status --short --branch has been available since 1.7.2 ).

Answer 4

How to know the remote tracked branch? It is often origin/branch but need not be.

Git 2.5+ introduces a new shortcut which references the branch you are pushing to. @{push}: that would be the remote tracking branch which is of interest here.

That means you have another option to see ahead/behind for all branches which are configured to push to a branch.

git for-each-ref --format="%(push:track)" refs/heads

See more at "Viewing Unpushed Git Commits"

Answer 5

update

As pointed out by amalloy, recent versions of git support finding the matching tracking branch for a given branch by giving "branchname@{upstream}" (or "branchname@{u}", or "@{u}" for the tracking branch of HEAD). This effectively supercedes the script below. You can do:

git rev-list @{u}..
git rev-list --left-right --boundary @{u}...
gitk @{u}...

etc. For example, I have git q aliased to git log --pretty='...' @{u}.. to show me "queued" commits ready for pushing.

original answer

There doesn't seem to be an easy way to find the tracking branch in general, without parsing lots more git config than is practical in a few shell commands. But for many cases this will go a long way:

# work out the current branch name
currentbranch=$(expr $(git symbolic-ref HEAD) : 'refs/heads/\(.*\)')
[ -n "$currentbranch" ] || die "You don't seem to be on a branch"
# look up this branch in the configuration
remote=$(git config branch.$currentbranch.remote)
remote_ref=$(git config branch.$currentbranch.merge)
# convert the remote ref into the tracking ref... this is a hack
remote_branch=$(expr $remote_ref : 'refs/heads/\(.*\)')
tracking_branch=refs/remotes/$remote/$remote_branch
# now $tracking_branch should be the local ref tracking HEAD
git rev-list $tracking_branch..HEAD

Another, more brute-force, approach:

git rev-list HEAD --not --remotes

jamessan's answer explains how to find the relative differences between $tracking_branch and HEAD using git rev-list. One fun thing you can do:

git rev-list --left-right $tracking_branch...HEAD

(note three dots between $tracking_branch and HEAD). This will show commits on both "arms" with a distinguishing mark at the front: "<" for commits on $tracking_branch, and ">" for commits on HEAD.

Answer 6

Edit: My original answer was actually not very good because it relied on the user to have a remote called "origin". It also failed if the current branch was had a tracking branch besides origin-head. These flaws essentially made it useless. However, the answer by @araqnid is not the most efficient method and the way he arrives at $tracking_branch is less than strait forward. The most efficient (fastest) method I have found to get the same functionality is the following:

# get the tracking-branch name
tracking_branch=$(git for-each-ref --format='%(upstream:short)' $(git symbolic-ref -q HEAD))
# creates global variables $1 and $2 based on left vs. right tracking
# inspired by @adam_spiers
set -- $(git rev-list --left-right --count $tracking_branch...HEAD)
behind=$1
ahead=$2

---

original answer: (inferior, but given for clarity)

Perhaps the simplest method I could find (inspired by @insidepower)

# count the number of logs
behind=$(git log --oneline HEAD..origin | wc -l)
ahead=$( git log --oneline origin..HEAD | wc -l)

I had previously been using the method of @araqnid, but now I think I'll move some of my scripts to this method since it is much simpler. This should work on any unix system.

Answer 7

Why wouldn't this work:

#!/bin/sh
git diff origin/master..HEAD --quiet --exit-code
RETVAL=$?
if [ $RETVAL -gt 0 ]; then
    echo "You need to git push!"
else
    echo "No git push necessary!"
fi 

Answer 8

The top chunk of code in araqnid's answer doesn't work for me, so maybe something in git has changed since it was written 18 months ago. It works if I change:

tracking_branch=refs/remotes/$remote/$remote_branch

to

tracking_branch=$remote/$remote_branch

However there is still an issue when tracking a local branch, in which case you have to trim the remote part (which becomes '.'):

tracking_branch=${tracking_branch#./}

Then you can programmatically obtain the number of revisions behind and ahead as follows:

set -- `git rev-list --left-right --count $tracking_branch...HEAD`
behind="$1"
ahead="$2"

I've written scripts to do all that (and more - e.g. they can also attempt to spot remotes on the other side of a git-svn bridge), and published them in my git-config repository on github. For example, here's my git-compare-upstream. See the README for installation instructions and other handy related scripts.

Answer 9

You can try git branch -v -v. With -v flag given twice, it outputs names of upstream branches. Sample output:

* devel  7a5ff2c [origin/devel: ahead 1] smaller file status overlay icons
  master 37ca389 [origin/master] initial project check-in.

I think this format is more stable than git status output.

Answer 10

git rev-list origin..HEAD will show the commits that are in your current branch, but not origin -- i.e., whether you're ahead of origin and by which commits.

git rev-list HEAD..origin will show the opposite.

If both commands show commits, then you have diverged branches.