[RFC PATCH] Documentation: rev-list-options: clarify history simplification with paths

This is an attempt to rewrite the documentation for --full-history, --simplify-merges, and --sparse for clarity.

--prune-merges does not exist yet, but would be intended to restore the default behavior over possible earlier --full-history and --simplify-merges.

WARNING: Does not match current code behavior.

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
---

This is fallout from my investigation of rev-list during the filter-branch topic. I found the descriptions quite unhelpful, and investigated commit logs and empiric behavior a bit.

The problem is, rev-list behaves quite erratically if one mixes --sparse, --full-history and --parents in combinations.

With the history from the patch, i.e.

  $ git log --graph --pretty=oneline --abbrev-commit --decorate
  *-.   e0083e6... (refs/heads/master) Merge branches 'side' and 'unrelated'
  |\ \
  | | * b3127f4... (refs/heads/unrelated) d: unrelated
  | * | 984aa48... (refs/heads/side) C: dir=B
  | |/
  * | aad9982... B: dir
  |/
  * b60c459... A: dir
  * ad7052b... initial

where only commits with 'dir' touch the 'dir' subdirectory, and C=B in terms of diffs, a few unexpected things happen. (I manually applied --abbrev-commit to rev-list output to make it fit in less columns.)

As noted in the patch, I would expect the default pruning to simplify the history to 'o -- A -- B -- m' (drop parent 'd' because the entire sideline is non-touching; drop parent 'C' because it is the same as 'B'), and then have --dense decide to drop 'o' and 'm' because they are not touching. The output agrees:

  $ git rev-list --pretty=oneline HEAD -- dir
  aad9982... B: dir
  b60c459... A: dir

Also, --sparse tends to support this two-pass simplification theory:

  $ git rev-list --pretty=oneline --sparse HEAD -- dir
  e0083e6... Merge branches 'side' and 'unrelated'
  aad9982... B: dir
  b60c459... A: dir
  ad7052b... initial

Now according to current docs, --full-history should turn off removing "merges which didn't change anything at all at some child", but still "simplify away merges that didn't change anything at all into either child." How does being a merge have anything to do with it's _children_? So I read this as saying that a merge is removed iff it agrees with all _parents_. However, despite having a merge that is different relative to its third parent, it is dropped:

  $ g rev-list --pretty=oneline --full-history HEAD -- dir
  984aa48... C: dir=B
  aad9982... B: dir
  b60c459... A: dir

But --parents --full-history magically revives the merge:

  $ git rev-list --pretty=oneline --parents --full-history HEAD -- dir
  e0083e6... aad9982... 984aa48... b60c459... Merge branches 'side' and 'unrelated'
  984aa48... b60c459... C: dir=B
  aad9982... b60c459... B: dir
  b60c459... A: dir

One quickly verifies that --sparse --full-history shows everything, as it should.

More to the point, --simplify-merges actually shows the merge when --full-history does not, resulting in

  $ git rev-list --pretty=oneline --simplify-merges HEAD -- dir
  e0083e6... Merge branches 'side' and 'unrelated'
  984aa48... C: dir=B
  aad9982... B: dir
  b60c459... A: dir

despite the commit message (90818fdc) claiming that it is an additional simplification on top of --full-history, and should therefore output at most as many commits. --parents seems to agree that the simplification is working right:

  $ git rev-list --pretty=oneline --parents --simplify-merges HEAD -- dir
  e0083e6... aad9982... 984aa48... Merge branches 'side' and 'unrelated'
  984aa48... b60c459... C: dir=B
  aad9982... b60c459... B: dir
  b60c459... A: dir

(Note that it dropped the third unrelated parent.)

Furthermore, with --sparse the same turns into

  $ git rev-list --pretty=oneline --sparse --parents --simplify-merges HEAD -- dir
  e0083e6... aad9982... 984aa48... b3127f4... Merge branches 'side' and 'unrelated'
  b3127f4... b60c459... d: unrelated
  984aa48... b60c459... C: dir=B
  aad9982... b60c459... B: dir
  b60c459... ad7052b... A: dir
  ad7052b... initial

So it didn't simplify away the parent 'd' after all, even though 90818fdc (in the second * bullet) does not mention any criterion that would make 'd' its own replacement. (I would actually expect it to replace 'd' with 'initial' on that ancestor line, and subsequently prune that parent because it is redundant.)

So if anyone read this mail up to this point: Which of these are actual bugs? Which of them are a misunderstanding on my part?

Thanks for your time,

Thomas

 Documentation/rev-list-options.txt |   97 ++++++++++++++++++++++++++++-------
 1 files changed, 77 insertions(+), 20 deletions(-)