All of Git's internal arrows are one-way, pointing backwards. There is therefore no short convenient syntax for moving forwards: it's just not possible.
It is possible to "move against the arrows", but the way to do it is surprising if you haven't seen it before, and then obvious afterward. Let's say we have:
A <-B <-C <-D <-E <-- last
^
|
\--------- middle
Using middle~2
follows the arrows twice from C
back to A
. So how do we move from C
to D
? The answer is: we start at E
, using the name last
, and work backwards until we get to middle
, recording the points we visit along the way. Then we just move as far as we want in the direction of last
: move one step to D
, or two to E
.
This is particularly important when we have branches:
D--E <-- feature1
/
...--B--C <-- master
\
F--G <-- feature2
Which commit is one step after C
? There's no correct answer until you add to the question: in the direction of feature___ (fill in the blank).
To enumerate the commits between C
(excluding C
) itself and, say, G
, we use:
git rev-list --topo-order --ancestry-path master..feature2
The --topo-order
makes sure that even in the presence of complex branching-and-merging, the commits come out in topologically-sorted order. This is only required if the chain isn't linear. The --ancestry-path
constraint means that when we work backwards from feature2
, we only list commits that have commit C
as one of their own ancestors. That is, if the graph—or the relevant chunk of it anyway—actually looks like this:
A--B--C <-- master
\ \
\ F--G--J <-- feature2
\ /
H-------I <-- feature3
Then a simple request of the form feature2..master
enumerates commits J
, G
and I
, and F
and H
in some order. With --ancestry-path
we knock out H
and I
: they are not descendants of C
, only of A
. With --topo-order
we make sure that the actual enumeration order is J
, then G
, then F
.
The git rev-list
command spills these hash IDs out on its standard output, one per line. To move one step forward in the direction of feature2
, then, we just want the last line.
It's possible (and tempting and can be useful) to add --reverse
so that git rev-list
prints the commits in reversed order after generating them. This does work, but if you use it in a pipeline like this:
git rev-list --topo-order --ancestry-path --reverse <id1>...<id2> | head -1
to just get the "next commit in the direction of id2", and there is a very long list of commits, the git rev-list
command can get a broken pipe when it tries to write to head
which has stopped reading its input and exited. Since broken-pipe errors are normally ignored by the shell, this mostly works. Just make sure they're ignored in your usage.
It's also tempting to add -n 1
to the git rev-list
command, along with --reverse
. Don't do it! That makes git rev-list
stop after walking one step back, and then reverse the (one-entry) list of commits visited. So this just produces <id2>
every time.
Important side note
Note that with "diamond" or "benzene ring" graph fragments:
I--J
/ \
...--H M--... <-- last
\ /
K--L
moving one commit "forward" from H
towards last
will get you either I
or K
. There is nothing you can do about that: both commits are one step forward! If you then start from the resulting commit and go another step, you're now committed to whichever path you started on.
The cure for this is to avoid moving one step at a time and getting locked into path-dependent chains. Instead, if you plan to visit an entire ancestry-path chain, before doing anything else, make a complete list of all commits in the chain:
git rev-list --topo-order --reverse --ancestry-path A..B > /tmp/list-of-commits
Then, visit each commit in this list, one at a time, and you'll get the entire chain. The --topo-order
will make sure you hit I
-and-J
in that order, and K
-and-L
in that order (though there's no easy way to predict whether you'll do the I-J pair before or after the K-L pair).
git children-of
"!