Quoting "Santi Béjar" <santi@agolina.net>:
Show 11 quoted lines
>> +The '\--simplify-by-decoration' option can be used to treat commits that
>> +are not referenced by tags as TREESAME, and treat commits that are tagged
>> +as !TREESAME (even when they have exactly the same tree as their parents).
>> +This can be used when you are only interested in the big picture of the
>> +topology of the history.
>> +
>> +
>
> I prefer the other way around, first what it does, and then how it
> does it (but it is a general comment about the help in "History
> Simplification", at least when viewing the help for "git log").
Thank you for your comments.
In the earlier part of the description, TREESAME (or !TREESAME) is explained as a prerequisite concept for understanding how the history simplification works. I think my description first talks about what it does using the concept that was already explained (in other words, "which commits are marked as TREESAME"), and then talks about what the consequence of what it does is (in other words, "only shows the big picture").
I can swap them around. Let's see if you like this better:
The '\--simplify-by-decoration' option allows you to view only the
big picture of the topology of the history, by omitting commits
that are not referenced by tags. Commits are marked as !TREESAME
(in other words, kept after history simplification rules described
above) if (1) they are referenced by tags, or (2) they change the
contents of the paths given on the command line. All other
commits are marked as TREESAME (subject to be simplified away).
Show 5 quoted lines
> And you should rewrite the line 416:
>
> Finally, there is a fourth simplification mode available
>
> as it is no longer "Finally".
Yes, I thought about it, but describing the new option at the end does not change the fact that the fourth simplification mode is the final one.
The new option is not about a "simplification mode". Given a set of commits marked as TREESAME and !TREESAME, simplification modes decide how the history is simplified. The new option does not add any new mode. Instead, it affects which commits are marked as TREESAME/!TREESAME.
For this reason, I also thought about moving the description of the new option before the existing text begins to talk about the simplification modes, but decided against it. This new option is rarely useful for everyday life (useful only once in a release cycle, maybe) and I do not think it deserves to be in the early part of the section. The readers are first taught how the basic concept TREESAME works in the usual case, and after learning that concept, they are shown how that concept is used in the history simplification mechanism. It will only complicate and confuse the readers if we talk about this new option that changes the way TREESAME mark is given to commits before showing how the simplification modes work for basic cases.
--
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/
Nanako Shiraishi