{"thread":{"id":"16268","subject":"Re: [PATCH 2/2] Document \"git log --simplify-by-decoration\"","startedAt":"2008-11-11T09:47:00Z","lastAt":"2008-11-11T11:03:48Z","messageCount":2,"participants":["Nanako Shiraishi","Santi Béjar"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"95446","messageId":"20081111184700.6117@nanako3.lavabit.com","threadId":"16268","inReplyTo":null,"subject":"Re: [PATCH 2/2] Document \"git log --simplify-by-decoration\"","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2008-11-11T09:47:00Z","receivedAt":"2008-11-11T09:47:00Z","isPatch":true,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting \"Santi Béjar\" :\n\n>> +The '\\--simplify-by-decoration' option can be used to treat commits that\n>> +are not referenced by tags as TREESAME, and treat commits that are tagged\n>> +as !TREESAME (even when they have exactly the same tree as their parents).\n>> +This can be used when you are only interested in the big picture of the\n>> +topology of the history.\n>> +\n>> +\n>\n> I prefer the other way around, first what it does, and then how it\n> does it (but it is a general comment about the help in \"History\n> Simplification\", at least when viewing the help for \"git log\").\n\nThank you for your comments.\n\nIn 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\").\n\nI can swap them around. Let's see if you like this better:\n\n\tThe '\\--simplify-by-decoration' option allows you to view only the\n\tbig picture of the topology of the history, by omitting commits\n\tthat are not referenced by tags. Commits are marked as !TREESAME\n\t(in other words, kept after history simplification rules described\n\tabove) if (1) they are referenced by tags, or (2) they change the\n\tcontents of the paths given on the command line. All other\n\tcommits are marked as TREESAME (subject to be simplified away).\n\n> And you should rewrite the line 416:\n>\n> Finally, there is a fourth simplification mode available\n>\n> as it is no longer \"Finally\".\n\nYes, 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.\n\nThe 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.\n\nFor 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.\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"},{"id":"95452","messageId":"adf1fd3d0811110303x4a8be5f7vd91979858dcfba59@mail.gmail.com","threadId":"16268","inReplyTo":"20081111184700.6117@nanako3.lavabit.com","subject":"Re: [PATCH 2/2] Document \"git log --simplify-by-decoration\"","fromName":"Santi Béjar","fromEmail":"santi@agolina.net","sentAt":"2008-11-11T11:03:48Z","receivedAt":"2008-11-11T11:03:48Z","isPatch":true,"sender":{"key":"santi@agolina.net","avatar":null},"body":"On Tue, Nov 11, 2008 at 10:47 AM, Nanako Shiraishi wrote:\n> Quoting \"Santi Béjar\" :\n>\n>>> +The '\\--simplify-by-decoration' option can be used to treat commits that\n>>> +are not referenced by tags as TREESAME, and treat commits that are tagged\n>>> +as !TREESAME (even when they have exactly the same tree as their parents).\n>>> +This can be used when you are only interested in the big picture of the\n>>> +topology of the history.\n>>> +\n>>> +\n>>\n>> I prefer the other way around, first what it does, and then how it\n>> does it (but it is a general comment about the help in \"History\n>> Simplification\", at least when viewing the help for \"git log\").\n>\n> Thank you for your comments.\n>\n> 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\").\n>\n> I can swap them around. Let's see if you like this better:\n>\n> The '\\--simplify-by-decoration' option allows you to view only the\n> big picture of the topology of the history, by omitting commits\n> that are not referenced by tags. Commits are marked as !TREESAME\n> (in other words, kept after history simplification rules described\n> above) if (1) they are referenced by tags, or (2) they change the\n> contents of the paths given on the command line. All other\n> commits are marked as TREESAME (subject to be simplified away).\n>\n\nBetter. I think it also makes sense to present the options at the\nbeginning of the section, explain what they do, and then explain them\nin detail. I'll try to do it.\n\n>> And you should rewrite the line 416:\n>>\n>> Finally, there is a fourth simplification mode available\n>>\n>> as it is no longer \"Finally\".\n>\n> 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.\n\nI take \"Finally\" as the last thing is explained in the section.\n\n>\n> 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.\n\nMake sense.\n\nSanti\n"}]}