On Thu, Dec 19, 2013 at 06:36:45PM +0000, Adam Spiers wrote:
> I wanted to be able to experiment with the TREESAME example given in
> the git-log(1) man page, so I built this script which recreates it:
[snipped]
> Would it be worth including this in (say) contrib/, and then referring
> to it from the man page, in case anyone else feels a similar urge?
Hmm, another related option would be to add a new test case which
tests that git log behaves in the way the man page says it does, in
this case. Although to some extent this would duplicate what
t6012-rev-list-simplify.sh already tests.
I still don't understand a few things about history simplification:
1. The "--full-history without parent rewriting" correctly asserts
that commit Q will be shown. But AFAICS this contradicts the
documented behaviour "Commits are included if they are not TREESAME
to any parent" which is implied by "This mode differs from the
default in one point:", because Q is TREESAME to P.
2. What difference does --dense ever make? In all three of the modes
described above it ("Default", "--full-history without parent
rewriting", and "--full-history with parent rewriting"), walked
commits are already included if they are not TREESAME to any
parent.
3. Why is --sparse so called, given that it increases rather than
decreases the number of commits shown?
I have to say I find this section of the man page really quite hard to
grok, partially due to the choice of "TREESAME" word. I'm guessing
that this was used because it reflects the name of the constant used
in the code, but it does not help legibility of the man page at all.
I think it could help to add descriptions of the behaviour which are
less formal and more intuitive from a pragmatic real world point of
view. For example:
"Each commit walked will only be shown in the default output mode
if it changed the given path(s) relative to *all* its parents.
When walking the commit graph, if a merge didn't change the given
path relative to at least one of its parents, then only one of
those parents would be walked. This reduces the number of
commits shown, but pruning commit chains whose changes
effectively died out during merges."
This sort of text could then be followed by the examples, for those
who want to check they understood it fully.
Hope this feedback is useful,
Adam
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html