Meaning of Github Ahead/Behind Metrics

In plain language (hopefully with a simple example), what do the ahead/behind metrics on a Github repo's branch mean?

And what are the implications for that branch and the attention it's receiving? Is being "behind" a bad sign for a branch?

Ahead is the number of commits on this branch that do not exist on the base branch. Behind is the number of commits on the base branch that do not exist on this branch.

Ahead and behind are almost like a kind of "age" metric. The ahead number tells you roughly how much impact the branch will have on the base branch should it be merged. The behind number tells you how much work has happened on the base branch since this branch was started.

I find the behind number really useful for judging whether a branch is likely to merge cleanly. When a lot of work has happened on the base branch, it's more likely that the two branches have modified the same line(s). When behind is large, it's a sign that you should probably merge the base branch into this branch to sync up. Once you merge the base branch into this branch, behind will be 0.

If you're more of a visual type, take a look here:

◈ - ◈ - A - ◈ - B
      \
        ◈ - C

A is 2 commits behind and 0 commits ahead of B
B is 0 commits behind and 2 commits ahead of A
C is 1 commit behind and 2 commits ahead of A
C is 3 commits behind and 2 commits ahead of B

So "behind" means the other branch has commits this one doesn't, and "ahead" means this branch has commits the other does not.

The metrics like those you can see for this project describe, compare to a branch from the repo (like master):

• the number of new commits that the GitHub repo has done compared to another branch of another repo: those are the behind commits: the other repo is behind compared to the current repo (see those commits).
• the number of new commits another branch of another repo has done compared to the current repo: those are the ahead commits: the other repo is ahead compared to the current repo (see those commits).

The technical detail is illustrated by the script "determining which repos are ahead/behind origin":
It is about checking:

• what commits are reachable from another branch, but not from the local branch: ahead
  git rev-list "$localref..$anotherref"

• what commits are reachable from the local branch, but not from the other branch: behind
  git rev-list "$anotherref..$localref"

On thing to note is that github's "behind" also counts merge commits. You can check the "behind" stuff with: git log mybranch1 ^mybranch2 and it should show you the same number of commits. If you have merge commits you can exclude them with --no-merges in the last command.