{"thread":{"id":"30098","subject":"[PATCH] git-commit doc: say -t requires editing commit message","startedAt":"2012-03-29T17:57:56Z","lastAt":"2012-04-05T14:29:53Z","messageCount":19,"participants":["Adam Monsen","Ivan Heffner","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"188083","messageId":"1333043876-19966-1-git-send-email-haircut@gmail.com","threadId":"30098","inReplyTo":null,"subject":"[PATCH] git-commit doc: say -t requires editing commit message","fromName":"Adam Monsen","fromEmail":"haircut@gmail.com","sentAt":"2012-03-29T17:57:56Z","receivedAt":"2012-03-29T17:57:56Z","isPatch":true,"sender":{"key":"haircut@gmail.com","avatar":"https://avatars.githubusercontent.com/u/50639?v=4"},"body":"Make it clear that, when using a commit template, the message *must* be\nchanged or the commit will be aborted \"due to empty commit message\".\n\nSigned-off-by: Adam Monsen \n---\n\nI found it confusing that the commit template itself, even if\nnon-empty, must be edited. Hopefully this clears that up a bit.\n\n Documentation/git-commit.txt | 2 +-\n 1 files changed, 1 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 5cc84a1..44947ab 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -133,7 +133,7 @@ OPTIONS\n -t ::\n --template=::\n \tUse the contents of the given file as the initial version\n-\tof the commit message. The editor is invoked and you can\n+\tof the commit message. The editor is invoked and you must\n \tmake subsequent changes. If a message is specified using\n \tthe `-m` or `-F` options, this option has no effect. This\n \toverrides the `commit.template` configuration variable.\n-- \n1.7.5.4\n"},{"id":"188085","messageId":"CAF_oF=xGHdbkYw-ytvcZvJnqZ_jdckUCBiuUDzkqGDk=66+yMQ@mail.gmail.com","threadId":"30098","inReplyTo":"1333043876-19966-1-git-send-email-haircut@gmail.com","subject":"Re: [PATCH] git-commit doc: say -t requires editing commit message","fromName":"Ivan Heffner","fromEmail":"iheffner@gmail.com","sentAt":"2012-03-29T18:09:48Z","receivedAt":"2012-03-29T18:09:48Z","isPatch":true,"sender":{"key":"iheffner@gmail.com","avatar":"https://gravatar.com/avatar/1ead000fad98fe337916f06edfc94fd87207ffc81a3a5363589e51c4f2bfa602?d=mp&s=160"},"body":"I'd suggest being much more verbose about what's going on and why.\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 5cc84a1..e842916 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -133,10 +133,12 @@ OPTIONS\n -t ::\n --template=::\n Use the contents of the given file as the initial version\n- of the commit message. The editor is invoked and you can\n- make subsequent changes. If a message is specified using\n- the `-m` or `-F` options, this option has no effect. This\n- overrides the `commit.template` configuration variable.\n+ of the commit message. The editor is invoked so you can\n+ make changes. If a message is specified using the `-m` or `-F`\n+ options, this option has no effect. This overrides the\n+ `commit.template` configuration variable. If the message is\n+ unchanged, the message is considered to be empty and the commit is\n+ aborted\n\n -s::\n --signoff::\n--\n1.7.6.553.g917d7.dirty\n\nOn Thu, Mar 29, 2012 at 10:57 AM, Adam Monsen wrote:\n>\n> Make it clear that, when using a commit template, the message *must* be\n> changed or the commit will be aborted \"due to empty commit message\".\n>\n> Signed-off-by: Adam Monsen \n> ---\n>\n> I found it confusing that the commit template itself, even if\n> non-empty, must be edited. Hopefully this clears that up a bit.\n>\n>  Documentation/git-commit.txt |    2 +-\n>  1 files changed, 1 insertions(+), 1 deletions(-)\n>\n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index 5cc84a1..44947ab 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -133,7 +133,7 @@ OPTIONS\n>  -t ::\n>  --template=::\n>        Use the contents of the given file as the initial version\n> -       of the commit message. The editor is invoked and you can\n> +       of the commit message. The editor is invoked and you must\n>        make subsequent changes. If a message is specified using\n>        the `-m` or `-F` options, this option has no effect. This\n>        overrides the `commit.template` configuration variable.\n> --\n> 1.7.5.4\n>\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at  http://vger.kernel.org/majordomo-info.html\n"},{"id":"188106","messageId":"1333062296-27823-1-git-send-email-haircut@gmail.com","threadId":"30098","inReplyTo":"CAF_oF=xGHdbkYw-ytvcZvJnqZ_jdckUCBiuUDzkqGDk=66+yMQ@mail.gmail.com","subject":"[PATCH v2] git-commit.txt: clarify -t requires editing message","fromName":"Adam Monsen","fromEmail":"haircut@gmail.com","sentAt":"2012-03-29T23:04:56Z","receivedAt":"2012-03-29T23:04:56Z","isPatch":true,"sender":{"key":"haircut@gmail.com","avatar":"https://avatars.githubusercontent.com/u/50639?v=4"},"body":"Make it clear that, when using a commit template, the message *must* be\nchanged or the commit will be aborted \"due to empty commit message\".\n\nHelped-by: Ivan Heffner \nSigned-off-by: Adam Monsen \n---\nIncorporate feedback from Ivan Heffner.\n\nAnyone else agree/disagree with this patch? I would like to see the\nmanpage improved because I found the behavior of \"git commit -t\"\nconfusing as documented.\n\nI wrapped the text at 77 characters because that was the longest\nline in the file (according to wc -L).\n\nI used \":set noet nosta ts=8 sw=8 tw=77\" in Vim.\n\n Documentation/git-commit.txt | 10 ++++++----\n 1 files changed, 6 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 5cc84a1..c6df120 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -133,10 +133,12 @@ OPTIONS\n -t ::\n --template=::\n \tUse the contents of the given file as the initial version\n-\tof the commit message. The editor is invoked and you can\n-\tmake subsequent changes. If a message is specified using\n-\tthe `-m` or `-F` options, this option has no effect. This\n-\toverrides the `commit.template` configuration variable.\n+\tof the commit message. The editor is invoked so you can\n+\tmake subsequent changes. If you make no changes, the message\n+\tis considered empty and the commit is aborted. If a message\n+\tis specified using the `-m` or `-F` options, this option has\n+\tno effect. This overrides the `commit.template`\n+\tconfiguration variable.\n \n -s::\n --signoff::\n-- \n1.7.5.4\n"},{"id":"188114","messageId":"7vboneq1vs.fsf@alter.siamese.dyndns.org","threadId":"30098","inReplyTo":"1333062296-27823-1-git-send-email-haircut@gmail.com","subject":"Re: [PATCH v2] git-commit.txt: clarify -t requires editing message","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-03-30T02:05:43Z","receivedAt":"2012-03-30T02:05:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Adam Monsen writes:\n\n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index 5cc84a1..c6df120 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -133,10 +133,12 @@ OPTIONS\n> -t ::\n> --template=::\n> \tUse the contents of the given file as the initial version\n> +\tof the commit message. The editor is invoked so you can\n> +\tmake subsequent changes. If you make no changes, the message\n> +\tis considered empty and the commit is aborted. If a message\n> +\tis specified using the `-m` or `-F` options, this option has\n> +\tno effect. This overrides the `commit.template`\n> +\tconfiguration variable.\n\nFirst, think of template not as the \"initial version\" but as \"a form that\nneeds to be filled\", and imagine that you are explaining to a beginner how\nto create a commit.\n\nThe word you would choose to use would be very different if you rephrase\nthe above after doing that mental exercise, and I suspect that it would\nbecome much easier to read.\n\nFor example:\n\n - subsequent changes --> fill in the form\n - If ... considerede empty and --> If you did not fill the form\n"},{"id":"188120","messageId":"4F75236C.4050703@gmail.com","threadId":"30098","inReplyTo":"7vboneq1vs.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2] git-commit.txt: clarify -t requires editing message","fromName":"Adam Monsen","fromEmail":"haircut@gmail.com","sentAt":"2012-03-30T03:07:24Z","receivedAt":"2012-03-30T03:07:24Z","isPatch":true,"sender":{"key":"haircut@gmail.com","avatar":"https://avatars.githubusercontent.com/u/50639?v=4"},"body":"Junio C. Hamano wrote:\n> First, think of template not as the \"initial version\" but as \"a form\n> that needs to be filled\"\n\nAh, that clarifies for me what the authors had in mind when\nimplementing this feature.\n\nI was hoping to use this feature to pre-populate the commit message\nin my editor and have the option to edit it or leave it as-is. This\nis what the word \"template\" means for me. For example: if I open a\n\"template\" in LibreOffice, I can make changes or not, and\nLibreOffice still lets me print or save at any point.\n\nNow that I know it's not that at all, but rather something more like\na mandatory fillable form, I'll find another way to achieve my need.\nSince git really wants me to enter *something* for a commit message,\nI understand why git \"templates\" work differently than LibreOffice\n\"templates\".\n\nIt's getting a little wordy, but here's an attempt to work in the\n\"form\" concept:\n\n~~~\nUse the contents of the given file as the initial version of the\ncommit message. Think of this initial version as a mandatory\nfillable form. The editor is invoked so you can fill in the form. If\nyou do not fill in the form (if you make no changes), the message is\nconsidered empty and the commit is aborted. If a message is\nspecified using the `-m` or `-F` options, this option has no effect.\nThis overrides the `commit.template` configuration variable.\n~~~\n\nThoughts?\n\n"},{"id":"188122","messageId":"7vr4waoics.fsf@alter.siamese.dyndns.org","threadId":"30098","inReplyTo":"4F75236C.4050703@gmail.com","subject":"Re: [PATCH v2] git-commit.txt: clarify -t requires editing message","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-03-30T03:52:51Z","receivedAt":"2012-03-30T03:52:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Adam Monsen writes:\n\n> ~~~\n> Use the contents of the given file as the initial version of the\n> commit message. Think of this initial version as a mandatory\n> fillable form. The editor is invoked so you can fill in the form. If\n> you do not fill in the form (if you make no changes), the message is\n> considered empty and the commit is aborted. If a message is\n> specified using the `-m` or `-F` options, this option has no effect.\n> This overrides the `commit.template` configuration variable.\n> ~~~\n>\n> Thoughts?\n\nYou still say \"the message is considered empty and\" but I think it\nprobably reads better without it. Strictly speaking, it is not a\n\"mandatory fillable form\", but whatever text you put in the template is\nadvisory to the users. For example, if your project wants its contributor\nto always refer to a bug id in its issue tracker, it may want to give a\ncustomized \"template\", instead of the plain \"template\" we give to the\nusers that begins with:\n\n\t~~~~~~~~\n\n # Please enter the commit message for your changes. Lines starting\n # with '#' will be ignored, and an empty message aborts the commit.\n\t~~~~~~~~\n\nto guide them what to write in the log and how to explain your change,\ne.g. something like:\n\n\t~~~~~~~~\n\t<>\n\n\t# explain the problem your change tries to solve in the first\n # paragraph\n\n\t# describe the approach your solution takes to solve it in the\n # second and subsequent paragraphs\n\n\t# Please write issue tracker ID at the end, if available\n\tFrotz-Bug-Id: XXXXXX\n\n # Always sign-off your commit\n Signed-off-by: XXXXXX\n\t~~~~~~~~\n"},{"id":"188124","messageId":"4F753C3F.7010805@gmail.com","threadId":"30098","inReplyTo":"7vr4waoics.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2] git-commit.txt: clarify -t requires editing message","fromName":"Adam Monsen","fromEmail":"haircut@gmail.com","sentAt":"2012-03-30T04:53:19Z","receivedAt":"2012-03-30T04:53:19Z","isPatch":true,"sender":{"key":"haircut@gmail.com","avatar":"https://avatars.githubusercontent.com/u/50639?v=4"},"body":"-----BEGIN PGP SIGNED MESSAGE-----\nHash: SHA1\n\nJunio C Hamano wrote:\n> You still say \"the message is considered empty and\" but I think it\n> probably reads better without it.\n\nDo you like the patch without those words?\n\n> Strictly speaking, it is not a \"mandatory fillable form\", but \n> whatever text you put in the template is advisory to the users.\n\nOk, right on. I understand the template feature now since you've\npatiently explained it to me (thank you!). I still want to plainly\nconvey that even if my template is the following:\n\n\t~~~~\n\tzip module: continue to expand transformer\n\t\n\tThis WIP will eventually provide expanded\n\ttransformer functionality.\n\t~~~~\n\nI *cannot* just save and quit my editor (unless I supply\n- --allow-empty-message). That's the behavior I find confusing: git\ntelling me a non-empty commit message is an empty commit message. If I\nsave that text above (zip module... etc) in FILE and do `git commit -t\nFILE`, save and quit my editor, git says \"Aborting commit due to empty\ncommit message.\" Lies! A more precise message would be \"Aborting\ncommit due to unmodified commit message template.\"\n\nBased on the current documentation I misunderstood that -t could be\nused to review a boilerplate commit message and save it verbatim.\n\n...AHA! I just figured out a way to do exactly that:\n\n\tgit commit --edit --file=FILE\n\naka\n\n\tgit commit -eF FILE\n\nYay! No idea how I missed that before.\n\nAnyway, it still seems like the documentation for \"git commit -t\"\ncould use improvement. I actually wouldn't mind seeing a short example\ntemplate like the one you provided, maybe in the EXAMPLES or\nDISCUSSION section.\n-----BEGIN PGP SIGNATURE-----\nVersion: GnuPG v1.4.11 (GNU/Linux)\n\niQEcBAEBAgAGBQJPdTw/AAoJEJtdmT+DbynAte4IALRx50yW5bEfzXskvSDewPuL\nSgaU4CqUHRm8sWXHeFbd4I2rG4dEJuqYqzKKbfay3EMwEbIkThiwoC2pJ9xJoFpe\n8O95GVp3ikYvsY3mn87ebiwA9FBhnTy1Fz+MREfuzETpJbdtJSHhbRXMxfJ9ZabU\nFOPE/qeZDvQJA9b9QFY3QS/BcxsGHXhW9xCULZlAprDggMcchhHDEbqJCh/1wObw\ncQvoONiqZSkXA17K3gxfs7NgafUVFIg3+N9vcq90eZXbT/s1MM+1zxj5ezTh9jbV\nsOkzepfE5+NBK3PnewMDxDxhF0LD5lzHCwnfkTl1Om3okSE0nxVyRZKabuzc99s=\n=NUN8\n-----END PGP SIGNATURE-----\n"},{"id":"188125","messageId":"7vehsaoev5.fsf@alter.siamese.dyndns.org","threadId":"30098","inReplyTo":"4F753C3F.7010805@gmail.com","subject":"Re: [PATCH v2] git-commit.txt: clarify -t requires editing message","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-03-30T05:08:14Z","receivedAt":"2012-03-30T05:08:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Adam Monsen writes:\n\n> I *cannot* just save and quit my editor (unless I supply\n> --allow-empty-message). That's the behavior I find confusing...\n\nThe root cause of the confusion is that the entire \"--template\" code piggy\nbacks on the non-templated case, where we would want to error out if the\nuser leaves the editor without explaining the commit. And an appropriate\ndiagnosis message for the \"normal\" case is \"you gave me an empty message\",\nbut \"--template\" code did not bother updating that to suit what it tries\nto do better, e.g. \"you did not edit the template I gave you\".\n\nThe check to see if the message the user left matches that came from the\ntemplate was tacked into a wrong function message_is_empty(); it should be\nmade into its own helper function and called from the same caller where\nit calls message_is_empty() only when template_file is not NULL. Also its\nhonoring \"--allow-empty\" needs to be reconsidered.\n\nIn other words, I think that is something that needs fixing the broken\ncode to behave less confusingly, not documenting its wrong behaviour.\n"},{"id":"188128","messageId":"4F7547EA.9050609@gmail.com","threadId":"30098","inReplyTo":"7vehsaoev5.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2] git-commit.txt: clarify -t requires editing message","fromName":"Adam Monsen","fromEmail":"haircut@gmail.com","sentAt":"2012-03-30T05:43:06Z","receivedAt":"2012-03-30T05:43:06Z","isPatch":true,"sender":{"key":"haircut@gmail.com","avatar":"https://avatars.githubusercontent.com/u/50639?v=4"},"body":"Junio C Hamano wrote:\n> I think that is something that needs fixing the broken code to behave\n> less confusingly, not documenting its wrong behaviour.\n\nExcellent! I concur.\n\nI wish I wanted to do this enough to make time to work on it. Ivan, how\nare your C chops? :)\n\n"},{"id":"188182","messageId":"7vaa2ylzrm.fsf@alter.siamese.dyndns.org","threadId":"30098","inReplyTo":"4F7547EA.9050609@gmail.com","subject":"Re: [PATCH v2] git-commit.txt: clarify -t requires editing message","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-03-30T18:17:17Z","receivedAt":"2012-03-30T18:17:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Adam Monsen writes:\n\n> Junio C Hamano wrote:\n>> I think that is something that needs fixing the broken code to behave\n>> less confusingly, not documenting its wrong behaviour.\n>\n> Excellent! I concur.\n>\n> I wish I wanted to do this enough to make time to work on it. Ivan, how\n> are your C chops? :)\n\nDon't worry. While looking around the vicinity of the codepath, I noticed\na few more bugs there, so I'll post something today.\n"},{"id":"188187","messageId":"1333136719-12657-1-git-send-email-gitster@pobox.com","threadId":"30098","inReplyTo":"7vaa2ylzrm.fsf@alter.siamese.dyndns.org","subject":"[PATCH 0/3] \"commit --template\" fixes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-03-30T19:45:16Z","receivedAt":"2012-03-30T19:45:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"When the user exited editor without editing the commit log template given\nby \"git commit -t