How can I fast-forward a single git commit, programmatically?

Question

I periodically get message from git that look like this:

Your branch is behind the tracked remote branch 'local-master/master' 
by 3 commits, and can be fast-forwarded.

I would like to be able to write commands in a shell script that can do the following:

1. How can I tell if my current branch can be fast-forwarded from the remote branch it is tracking?

2. How can I tell how many commits "behind" my branch is?

3. How can I fast-forward by just one commit, so that for example, my local branch would go from "behind by 3 commits" to "behind by 2 commits"?

(For those who are interested, I am trying to put together a quality git/darcs mirror.)

Answer 1

Alternate Approaches

You mention that you are working on some sort of mirror for Git and Darcs. Instead of dragging a working tree through history, you might instead look at the git fast-import and git fast-export commands to see if they offer a better way to manage the data you need to extract/provide.

How to Tell Whether a Branch Can Fast-Forward to Its Upstream Branch

There are two parts to this. First, you have to either know or determine which branch is the current branch’s “upstream”. Then, once you know how to refer to the upstream, you check for the ability to fast-forward.

Finding the Upstream for a Branch

Git 1.7.0 has a convenient way to query which branch a branch tracks (its “upstream” branch). The @{upstream} object specification syntax can be used as a branch specifier. As a bare name, it refers to the upstream branch for the branch that is currently checked out. As a suffix, it can be used to find the upstream branch for branches that are not currently checked out.

For Gits earlier than 1.7.0, you will have to parse the branch configuration options yourself (branch.name.remote and branch.name.merge). Alternatively, if you have a standard naming convention, you can just use that to determine a name for the upstream branch.

In this answer I will write upstream to refer to the commit at the tip of the branch that is upstream of the current branch.

Checking for Ability to Fast-Forward

A branch at commit A can be fast-forwarded to commit B if and only if A is an ancestor of B.

gyim shows one way to check for this condition (list all the commits reachable from B and check for A in the list). Perhaps a simpler way to check for this condition is to check that A is the merge base of A and B.

can_ff() {
    a="$(git rev-parse "$1")" &&
    test "$(git merge-base "$a" "$2")" = "$a"
}
if can_ff HEAD local-master/master; then
    echo can ff to local-master/master
else
    echo CAN NOT ff to local-master/master
fi

Finding the Number of “Commits Behind”

git rev-list ^HEAD upstream | wc -l

This does not require that HEAD can fast-forward to upstream (it only counts how far HEAD is behind upstream, not how far upstream is behind HEAD).

Move Forward by One Commit

In general, a fast-forward-able history may not be linear. In the history DAG below, master could fast-forward to upstream, but both A and B are “one commit forward” from master on the way towards upstream.

---o---o                      master
       |\
       | A--o--o--o--o--o--o  upstream
        \                 /
         B---o---o---o---o

You can follow one side as if it was a linear history, but only up to the immediate ancestor of the merge commit.

The revision walking commands have a --first-parent option that makes it easy to follow only the commits that lead to the first parent of merge commits. Combine this with git reset and you can effectively drag a branch “forward, one commit at a time”.

git reset --hard "$(git rev-list --first-parent --topo-order --reverse ^HEAD upstream | head -1)"

_{In a comment on another answer, you express from fear of git reset. If you are worried about corrupting some branch, then you can either use a temporary branch or use a detached HEAD as an unnamed branch. As long as your working tree is clean and you do not mind moving a branch (or the detached HEAD), git reset --hard will not trash anything. If you are still worried, you should seriously look into using git fast-export where you do not have to touch the working tree at all.}

Following a different parent would be more difficult. You would probably have to write your own history walker so that you could give it advice as to “which direction” you wanted to go for each merge.

When you have moved forward to a point just short of the merge, the DAG will look like this (the topology is the same as before, it is only the master label that has moved):

---o---o--A--o--o--o--o--o    master
       |                  \
       |                   o  upstream
        \                 /
         B---o---o---o---o

At this point if you “move forward one commit”, you will move to the merge. This will also “bring in” (make reachable from master) all the commits from B up to the merge commit. If you assume that “moving forward one commit” will only add one commit to the history DAG, then this step will violate that assumption.

You will probably want to carefully consider what you really want to do in this case. It is OK to just drag in extra commits like this, or should there be some mechanism for “going back” to the parent of B and moving forward on that branch before you process the merge commit?