[PATCH 2/2] Document "git log --simplify-by-decoration"

[PATCH 2/2] Document "git log --simplify-by-decoration"

[Nanako Shiraishi]

Signed-off-by: Nanako Shiraishi <nanako3@lavabit.com>
---
 Documentation/rev-list-options.txt |    7 +++++++
 1 files changed, 7 insertions(+), 0 deletions(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 966276b..977290c 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -456,6 +456,13 @@ Note the major differences in `N` and `P` over '\--full-history':
   removed completely, because it had one parent and is TREESAME.
 --
 
+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.
+
+
 ifdef::git-rev-list[]
 Bisection Helpers
 ~~~~~~~~~~~~~~~~~
-- 
1.6.0.2

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: [PATCH 2/2] Document "git log --simplify-by-decoration"

[Santi Béjar]

On Mon, Nov 10, 2008 at 10:58 AM, Nanako Shiraishi <nanako3@lavabit.com> wrote:
> Signed-off-by: Nanako Shiraishi <nanako3@lavabit.com>
> ---
>  Documentation/rev-list-options.txt |    7 +++++++
>  1 files changed, 7 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index 966276b..977290c 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -456,6 +456,13 @@ Note the major differences in `N` and `P` over '\--full-history':
>   removed completely, because it had one parent and is TREESAME.
>  --
>
> +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"). And
you should rewrite the line 416:

Finally, there is a fourth simplification mode available

as it is no longer "Finally".

Santi

Re: [PATCH 2/2] Document "git log --simplify-by-decoration"

[Nanako Shiraishi]

Quoting "Santi Béjar" <santi@agolina.net>:

>> +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).

> 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/

Re: [PATCH 2/2] Document "git log --simplify-by-decoration"

[Santi Béjar]

On Tue, Nov 11, 2008 at 10:47 AM, Nanako Shiraishi <nanako3@lavabit.com> wrote:
> Quoting "Santi Béjar" <santi@agolina.net>:
>
>>> +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).
>

Better. I think it also makes sense to present the options at the
beginning of the section, explain what they do, and then explain them
in detail. I'll try to do it.

>> 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.

I take "Finally" as the last thing is explained in the section.

>
> 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.

Make sense.

Santi