From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 30 Mar 2012 03:52:51 GMT
Subject: Re: [PATCH v2] git-commit.txt: clarify -t requires editing message
Message-ID: <7vr4waoics.fsf@alter.siamese.dyndns.org>
In-Reply-To: <4F75236C.4050703@gmail.com>

Adam Monsen <haircut@gmail.com> 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
	~~~~~~~~