From: "Jakub Narębski" <jnareb@xxxxxxxxx>
Sent: Sunday, August 28, 2016 2:01 PM
W dniu 12.08.2016 o 09:07, Philip Oakley pisze:
[...]
History traversing commands such as `git log` operate on a set
-of commits, not just a single commit. To these commands,
-specifying a single revision with the notation described in the
-previous section means the set of commits reachable from that
-commit, following the commit ancestry chain.
+of commits, not just a single commit.
+
+For these commands,
+specifying a single revision, using the notation described in the
+previous section, means the set of commits `reachable` from the given
+commit.
Why such strange formatting? Is it to keep original contents
for better blame / word diff?
Strange as in 'not reflowed'? - yes that was the reason. It can be hard to
see the wood from the trees if there is a lot of reflow going on, as it can
hide the issue behind the key change.
I did slightly abuse notation by quoting `reachable` to indicate that it's a
term with a precise definition that can be confusing to those that don't
know. I also split out the reachability parts into their own paragraphs.
+
+A commit's reachable set is the commit itself and the commits in
+its ancestry chain.
+
It is all right, but perhaps it would be better to just repeat:
+Set of commits reachable from given commit is the commit itself
+and all the commits in its ancestry chain.
It's very easy to go around in circles here. The original issue was the A..B
notation for the case where A is a direct descendant of B, such that new
users, or users more familiar with range notations from elsewhere, would
expect that the A..B range is *inclusive*, rather than an open / closed
interval. It was the addressing of that problem that lead to the updating of
the 'reachability' definition.
The main part of my sentence formation was to make the 'reachable' part the
defining element, rather than being a feature of the set. Maybe it's using
the 'set' viewpoint that is distracting?
--
Jakub Narębski