Clarify some things in "A commit by any other name…"

[whxvd]

I assume that current https://jwiegley.github.io/git-from-the-bottom-up currently is generated from current master of https://github.com/jwiegley/git-from-the-bottom-up.

Let reach X be the set of commits reachable from X.

Subissue 1

name1..name2 — This and the following aliases indicate commit ranges, which are supremely useful with commands like log for seeing what’s happened during a particular span of time. The syntax to the left refers to all the commits reachable from name2 back to, but not including, name1. If either name1 or name2 is omitted, HEAD is used in its place.

As far as I know (and at least with the command git rev-list) X..Y means: reach Y \ reach X. However, the above means something like:

if X not in reach Y
then ???
else reach Y \ reach X

But that clearly is not the case.

Subissue 2

master.. — This usage is equivalent to master..HEAD. I’m adding it here, even though it’s been implied above, because I use this kind of alias constantly when reviewing changes made to the current branch.

..master — This, too, is especially useful after you’ve done a fetch and you want to see what changes have occurred since your last rebase or merge.

Until here the book seems to be written with the intention that it works for people who are completely new to Git. If this is the case, then it may not be clear enough at this point what a merge is and certainly not what a rebase is. It also may not be clear enough, that current HEAD is meant to be a reference to, e.g., a topic branch.

If the reader already knows some Git, then he knows that a fetch does not update master but something like origin/master. This probably makes the description for ..master especially confusing.

I think something like the following would be good: Before the bullets describing the .. construct, insert an image of a commit graph with something like

         o---o---o---B
        /
---o---1---o---o---o---A

(taken from man 1 git-merge-base) and additionally: a reference master pointing to A, a reference topic pointing to B, a symbolic reference HEAD pointing to topic. Then use the example as the central device for explanation.

If something like this is in fact already meant here, then with subissue 1 we reach ??? here.

Subissue 3

name1…name2 — A “triple-dot” range is quite different from the two-dot version above. For commands like log, it refers to all the commits referenced by name1 or name2, but not by both. The result is then a list of all the unique commits in both branches. For commands like diff, the range expressed is between name2 and the common ancestor of name1 and name2. This differs from the log case in that changes introduced by name1 are not shown.

"the common ancestor of name1 and name2" does not necessarily exist (at all, or uniquely). No idea what happens then.

It would be really nice if the book had a whole section on all relevant-to-git topological notions of the commit graph before. :-)