Adam Monsen [off-list ref] writes:
~~~
Use the contents of the given file as the initial version of the
commit message. Think of this initial version as a mandatory
fillable form. The editor is invoked so you can fill in the form. If
you do not fill in the form (if you make no changes), the message is
considered empty and the commit is aborted. If a message is
specified using the `-m` or `-F` options, this option has no effect.
This overrides the `commit.template` configuration variable.
~~~
Thoughts?
You still say "the message is considered empty and" but I think it
probably reads better without it. Strictly speaking, it is not a
"mandatory fillable form", but whatever text you put in the template is
advisory to the users. For example, if your project wants its contributor
to always refer to a bug id in its issue tracker, it may want to give a
customized "template", instead of the plain "template" we give to the
users that begins with:
~~~~~~~~
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
~~~~~~~~
to guide them what to write in the log and how to explain your change,
e.g. something like:
~~~~~~~~
<<one line summary your change here>>
# explain the problem your change tries to solve in the first
# paragraph
# describe the approach your solution takes to solve it in the
# second and subsequent paragraphs
# Please write issue tracker ID at the end, if available
Frotz-Bug-Id: XXXXXX
# Always sign-off your commit
Signed-off-by: XXXXXX
~~~~~~~~
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Junio C Hamano wrote:
You still say "the message is considered empty and" but I think it
probably reads better without it.
Do you like the patch without those words?
Strictly speaking, it is not a "mandatory fillable form", but
whatever text you put in the template is advisory to the users.
Ok, right on. I understand the template feature now since you've
patiently explained it to me (thank you!). I still want to plainly
convey that even if my template is the following:
~~~~
zip module: continue to expand transformer
This WIP will eventually provide expanded
transformer functionality.
~~~~
I *cannot* just save and quit my editor (unless I supply
- --allow-empty-message). That's the behavior I find confusing: git
telling me a non-empty commit message is an empty commit message. If I
save that text above (zip module... etc) in FILE and do `git commit -t
FILE`, save and quit my editor, git says "Aborting commit due to empty
commit message." Lies! A more precise message would be "Aborting
commit due to unmodified commit message template."
Based on the current documentation I misunderstood that -t could be
used to review a boilerplate commit message and save it verbatim.
...AHA! I just figured out a way to do exactly that:
git commit --edit --file=FILE
aka
git commit -eF FILE
Yay! No idea how I missed that before.
Anyway, it still seems like the documentation for "git commit -t"
could use improvement. I actually wouldn't mind seeing a short example
template like the one you provided, maybe in the EXAMPLES or
DISCUSSION section.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
iQEcBAEBAgAGBQJPdTw/AAoJEJtdmT+DbynAte4IALRx50yW5bEfzXskvSDewPuL
SgaU4CqUHRm8sWXHeFbd4I2rG4dEJuqYqzKKbfay3EMwEbIkThiwoC2pJ9xJoFpe
8O95GVp3ikYvsY3mn87ebiwA9FBhnTy1Fz+MREfuzETpJbdtJSHhbRXMxfJ9ZabU
FOPE/qeZDvQJA9b9QFY3QS/BcxsGHXhW9xCULZlAprDggMcchhHDEbqJCh/1wObw
cQvoONiqZSkXA17K3gxfs7NgafUVFIg3+N9vcq90eZXbT/s1MM+1zxj5ezTh9jbV
sOkzepfE5+NBK3PnewMDxDxhF0LD5lzHCwnfkTl1Om3okSE0nxVyRZKabuzc99s=
=NUN8
-----END PGP SIGNATURE-----