On Tue, May 19, 2020 at 05:32:52PM -0400, Scott Bennett wrote:
> Hi,
> 
> Sometimes when creating a commit it's useful to use a prepared commit
> message from a separate file - for instance when applying errata patches
> to a locally maintained -stable tree.
> 
> As I understand it, a 'commit -F' analogue is undesirable since it can lead
> to more pain than good.

In particular, it can lead to commit messages coming from the wrong file,
such as a source code file. There have been some instances of this in
OpenBSD with CVS over the years. These could be corrected with 'cvsadmin'.

With Git repositories such a mistake becomes difficult to repair in a
non-destructive mannter once the commit has been published.

There are ways to mitigate the problem, e.g. Subversion won't accept the
argument given to -F if it is also one of the paths that are being committed.
However, Subversion also has an easy way out if a mistake slips through,
since log messages can be edited without altering history.

So 'got commit' intentionally steers the user into an editor, and 'commit -m'
is provided mainly for non-interactive use cases.

Not having -F at all avoids the issue entirely, with less code to maintain.
There is no real loss of functionality, as the examples below show.
It's just slightly less convenient for people who are used to commit -F.

> diff --git a/got/got.1 b/got/got.1
> index 37523a3..0053990 100644
> --- a/got/got.1
> +++ b/got/got.1
> @@ -1968,10 +1968,24 @@ Add new files and remove obsolete files in a
> work tree directory:
>  Create a new commit from local changes in a work tree directory
>  with a pre-defined log message.
>  .Pp
>  .Dl $ got commit -m 'unify the buffer cache'
>  .Pp
> +Create a new commit from local changes in a work tree directory
> +with a log message that has been prepared in the file
> +.Pa /tmp/msg .
> +If using
> +.Xr ksh 1 :
> +.Pp
> +.Dl $ got commit -m '`cat /tmp/msg`'

I would prefer showing the editor example first. I hope people will tend to
double-check their log message if they are about to save and exit an editor.

The backtick trick is a more risky option. It is essentially a hack which
emulates commit -F, with the same potential consequences.

> +.Pp
> +Or if using
> +.Xr vi 1 :

Could we explicitly state here that the user is expected to read a prepared
log message file into the editor's buffer? That might make this example easier
to follow for readers who don't already know what vi's :r command does.

> +.Pp
> +.Dl $ got commit
> +.Dl :r /tmp/msg
> +.Pp
>  Update any work tree checked out from the
>  .Dq unified-buffer-cache
>  branch to the latest commit on this branch:
>  .Pp
>  .Dl $ got update
> 
> 
> p.s. hopefully my webmail client didn't mangle the diff, despite its
> best efforts
> 
>