{"thread":{"id":"39156","subject":"[PATCH] Clarify documentation on commit message strip","startedAt":"2015-04-24T20:06:38Z","lastAt":"2015-04-27T18:13:50Z","messageCount":5,"participants":["Fredrik Gustafsson","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"259960","messageId":"1429905998-9089-1-git-send-email-iveqy@iveqy.com","threadId":"39156","inReplyTo":null,"subject":"[PATCH] Clarify documentation on commit message strip","fromName":"Fredrik Gustafsson","fromEmail":"iveqy@iveqy.com","sentAt":"2015-04-24T20:06:38Z","receivedAt":"2015-04-24T20:06:38Z","isPatch":true,"sender":{"key":"iveqy@iveqy.com","avatar":"https://avatars.githubusercontent.com/u/761743?v=4"},"body":"When using `-v` to add a unified diff to the commit message, this is\nstripped and not a part of the commit message. This is not mentioned.\n\nAdd a note about this with the `-v` description as well as description\nfor the default `--cleanup` mode.\n\nSigned-off-by: Fredrik Gustafsson <iveqy@iveqy.com>\n---\n Documentation/git-commit.txt | 8 +++++---\n 1 file changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 617e29b..e31d828 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -180,8 +180,9 @@ OPTIONS\n +\n --\n strip::\n-\tStrip leading and trailing empty lines, trailing whitespace, and\n-\t#commentary and collapse consecutive empty lines.\n+\tStrip leading and trailing empty lines, trailing whitespace,\n+\t#commentary, unified diff added with `-v` and collapse\n+\tconsecutive empty lines.\n whitespace::\n \tSame as `strip` except #commentary is not removed.\n verbatim::\n@@ -283,7 +284,8 @@ configuration variable documented in linkgit:git-config[1].\n \tShow unified diff between the HEAD commit and what\n \twould be committed at the bottom of the commit message\n \ttemplate.  Note that this diff output doesn't have its\n-\tlines prefixed with '#'.\n+\tlines prefixed with '#'. This diff will not be a part\n+\tof the commit message.\n +\n If specified twice, show in addition the unified diff between\n what would be committed and the worktree files, i.e. the unstaged\n-- \n2.1.4\n"},{"id":"259978","messageId":"xmqqmw1w259r.fsf@gitster.dls.corp.google.com","threadId":"39156","inReplyTo":"1429905998-9089-1-git-send-email-iveqy@iveqy.com","subject":"Re: [PATCH] Clarify documentation on commit message strip","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-04-25T04:36:32Z","receivedAt":"2015-04-25T04:36:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Fredrik Gustafsson <iveqy@iveqy.com> writes:\n\n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index 617e29b..e31d828 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -180,8 +180,9 @@ OPTIONS\n>  +\n>  --\n>  strip::\n> -\tStrip leading and trailing empty lines, trailing whitespace, and\n> -\t#commentary and collapse consecutive empty lines.\n> +\tStrip leading and trailing empty lines, trailing whitespace,\n> +\t#commentary, unified diff added with `-v` and collapse\n> +\tconsecutive empty lines.\n\nI'd prefer the description not to be _too_ explicit e.g. by\nmentioning \"unified diff\", etc.\n\nPersonally I think it is sufficient to do s/#comment/comment/ to the\nexisting text, without doing anything else.  What is \"commentary\" to\nbe removed is fairly clear in the contents given to the user in the\neditor.\n"},{"id":"259981","messageId":"1429940565-14947-1-git-send-email-iveqy@iveqy.com","threadId":"39156","inReplyTo":"xmqqmw1w259r.fsf@gitster.dls.corp.google.com","subject":"[PATCH] Clarify documentation on commit message strip","fromName":"Fredrik Gustafsson","fromEmail":"iveqy@iveqy.com","sentAt":"2015-04-25T05:42:45Z","receivedAt":"2015-04-25T05:42:45Z","isPatch":true,"sender":{"key":"iveqy@iveqy.com","avatar":"https://avatars.githubusercontent.com/u/761743?v=4"},"body":"When using `-v` to add a unified diff to the commit message, this is\nstripped and not a part of the commit message. This is not mentioned.\n\nAdd a note about this with the `-v` description and slightly modify\nthe description for the default `--cleanup` mode.\n\nSigned-off-by: Fredrik Gustafsson <iveqy@iveqy.com>\n---\n\n>I'd prefer the description not to be _too_ explicit e.g. by\n>mentioning \"unified diff\", etc.\n>\n>Personally I think it is sufficient to do s/#comment/comment/ to the\n>existing text, without doing anything else.  What is \"commentary\" to\n>be removed is fairly clear in the contents given to the user in the\n>editor.\n\nI agree that it is very clear once you do edit the commit message. My main\npoint with this patch was to clarify -v, since it's not obvious from the\ndocumentation that it will be removed.\n\nI've no objections about your suggestions about the `strip` part. I hope I've\nunderstood you correctly and that this patch is correct.\n\n Documentation/git-commit.txt | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 617e29b..1db4c7f 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -180,8 +180,8 @@ OPTIONS\n +\n --\n strip::\n-\tStrip leading and trailing empty lines, trailing whitespace, and\n-\t#commentary and collapse consecutive empty lines.\n+\tStrip leading and trailing empty lines, trailing whitespace,\n+\tcommentary and collapse consecutive empty lines.\n whitespace::\n \tSame as `strip` except #commentary is not removed.\n verbatim::\n@@ -283,7 +283,8 @@ configuration variable documented in linkgit:git-config[1].\n \tShow unified diff between the HEAD commit and what\n \twould be committed at the bottom of the commit message\n \ttemplate.  Note that this diff output doesn't have its\n-\tlines prefixed with '#'.\n+\tlines prefixed with '#'. This diff will not be a part\n+\tof the commit message.\n +\n If specified twice, show in addition the unified diff between\n what would be committed and the worktree files, i.e. the unstaged\n-- \n2.1.4\n"},{"id":"260060","messageId":"xmqqh9s1xytr.fsf@gitster.dls.corp.google.com","threadId":"39156","inReplyTo":"1429940565-14947-1-git-send-email-iveqy@iveqy.com","subject":"Re: [PATCH] Clarify documentation on commit message strip","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-04-27T17:31:28Z","receivedAt":"2015-04-27T17:31:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Fredrik Gustafsson <iveqy@iveqy.com> writes:\n\n> I agree that it is very clear once you do edit the commit message. My main\n> point with this patch was to clarify -v, since it's not obvious from the\n> documentation that it will be removed.\n\nWhile I agree with you that the documentation should make it clear\nthat the patch will not be part of the commit, I think the root\ncause of the current \"unclear-ness\" is because the documentation\ndoes not make it clear *WHY* the \"-v\" option gives the patch text\nthere.\n\nDoing something like this on top of your patch may clarify the\nreason what \"-v\" is used for, and I suspect that it may even make it\nunnecessary to explicitly say that the patch text will not be part\nof the log message (but I didn't remove that with this \"how about\nthis\" follow-up).\n\n Documentation/git-commit.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 1db4c7f..617dea0 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -282,7 +282,9 @@ configuration variable documented in linkgit:git-config[1].\n --verbose::\n \tShow unified diff between the HEAD commit and what\n \twould be committed at the bottom of the commit message\n-\ttemplate.  Note that this diff output doesn't have its\n+\ttemplate to help the user describe the commit by reminding\n+\twhat changes the commit has.\n+\tNote that this diff output doesn't have its\n \tlines prefixed with '#'. This diff will not be a part\n \tof the commit message.\n +\n"},{"id":"260066","messageId":"20150427181350.GB15518@paksenarrion.iveqy.com","threadId":"39156","inReplyTo":"xmqqh9s1xytr.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Clarify documentation on commit message strip","fromName":"Fredrik Gustafsson","fromEmail":"iveqy@iveqy.com","sentAt":"2015-04-27T18:13:50Z","receivedAt":"2015-04-27T18:13:50Z","isPatch":true,"sender":{"key":"iveqy@iveqy.com","avatar":"https://avatars.githubusercontent.com/u/761743?v=4"},"body":"On Mon, Apr 27, 2015 at 10:31:28AM -0700, Junio C Hamano wrote:\n> Fredrik Gustafsson <iveqy@iveqy.com> writes:\n> \n> > I agree that it is very clear once you do edit the commit message. My main\n> > point with this patch was to clarify -v, since it's not obvious from the\n> > documentation that it will be removed.\n> \n> While I agree with you that the documentation should make it clear\n> that the patch will not be part of the commit, I think the root\n> cause of the current \"unclear-ness\" is because the documentation\n> does not make it clear *WHY* the \"-v\" option gives the patch text\n> there.\n\nI agree.\n\n> \n> Doing something like this on top of your patch may clarify the\n> reason what \"-v\" is used for, and I suspect that it may even make it\n> unnecessary to explicitly say that the patch text will not be part\n> of the log message (but I didn't remove that with this \"how about\n> this\" follow-up).\n\nEven better. I would be glad if this could make it into a release.\nThanks for the feedback, to make this a good patch.\n\n-- \nFredrik Gustafsson\n\nphone: +46 733-608274\ne-mail: iveqy@iveqy.com\nwebsite: http://www.iveqy.com\n"}]}