From: Scott Bennett <sbennett1990@gmail.com>
Subject: Re: got.1: commit examples
To: Stefan Sperling <stsp@stsp.name>
Cc: gameoftrees@openbsd.org
Date: Wed, 20 May 2020 12:23:05 -0400

On 5/20/20 3:32 AM, Stefan Sperling wrote:
> 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.
>
>> +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.

Sure, that sounds reasonable to me.

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

Indeed, it's very risky. I'm fine with omitting it entirely and leaving
it for the user to discover.

>> +.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.

Yes I think that would be a good hint. Perhaps something like below?


diff --git a/got/got.1 b/got/got.1
index 37523a3..15bd5b8 100644
--- a/got/got.1
+++ b/got/got.1
@@ -1968,10 +1968,23 @@ 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
+Alternatively, 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
+.Xr vi 1
+is set as the
+.Ev EDITOR ,
+.Pa /tmp/msg
+can be read into the buffer for review:
+.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