On Sat, Jan 28, 2023 at 10:44:15PM +1100, Mark Jamsek wrote:
> On 23-01-28 12:28PM, Stefan Sperling wrote:
> > There will be edge cases where a cherrypick affects multiple paths
> > and the user chooses to only commit one of them. In that case, I would
> > expect the log message template to be used during this initial commit
> > of some affected path, and then removed. This would leave changes on
> > other affected paths without a log message template.
> 
> That's correct. We might be able to improve the logmsg ref removal
> heuristic so that the template remains; if you like I can look at doing
> that?

I think the current behaviour is good enough. Let's try not to
overcomplicate things...

> > This is a consequence of the design decisions we've made, where changes
> > are tracked per-path, rather than as content diffs. I think this is
> > acceptable as long as users are made aware of this limitation.
> > The man page should mention this somewhere. I will try to remember this
> > when I get a chance to look over the relevant bits of documentation again
> > and perhaps adjust them a bit.
> > 

Here is a diff that aims to make the documentation more clear.
Is there any important aspect of behaviour which is not mentioned here?

 clarify documentation of cherrypick/backout log message recording
 
diff 378a2540886d76e663ffc65125a68c08f8a38604 0eae0a4c5e8476122e48eb28709c789e692aeee3
commit - 378a2540886d76e663ffc65125a68c08f8a38604
commit + 0eae0a4c5e8476122e48eb28709c789e692aeee3
blob - a7f240fdbe0cd8fc14dc557ebfd851c1b0b51d58
blob + 5406a92f011218398c65d0d370c7c75302394168
--- got/got.1
+++ got/got.1
@@ -2005,12 +2005,28 @@ committed with
 .Cm got cherrypick
 commands,
 committed with
-.Cm got commit
-where the log message of the cherrypicked commit will appear in the editor,
-or discarded again with
-.Cm got revert .
+.Cm got commit .
 .Pp
+If invoked in a work tree where no
+.Cm rebase ,
+.Cm histedit ,
+or
+.Cm merge
+operation is taking place,
 .Cm got cherrypick
+creates a record of commits which have been merged into the work tree.
+When a file changed by
+.Cm got cherrypick
+is committed with
+.Cm got commit ,
+the log messages of relevant merged commits will then appear in the editor,
+where the messages can be further adjusted as needed.
+If all the changes in all files touched by a given commit are discarded,
+e.g. with
+.Cm got revert ,
+this commit's log message record will also disappear.
+.Pp
+.Cm got cherrypick
 will refuse to run if certain preconditions are not met.
 If the work tree contains multiple base commits, it must first be updated
 to a single base commit with
@@ -2037,7 +2053,7 @@ This option cannot be used with
 Otherwise, all commit log messages will be displayed irrespective of the
 work tree in which they were created.
 This option cannot be used with
-.Cm X .
+.Fl X .
 .It Fl X
 Delete log messages created by previous cherrypick operations, represented by
 references in the
@@ -2052,7 +2068,7 @@ This option cannot be used with
 Otherwise, all commit log messages will be deleted irrespective of the
 work tree in which they were created.
 This option cannot be used with
-.Cm l .
+.Fl l .
 .El
 .Pp
 .Tg bo
@@ -2091,12 +2107,28 @@ committed with
 .Cm got backout
 commands,
 committed with
-.Cm got commit
-where the log message of the backed-out commit will appear in the editor,
-or discarded again with
-.Cm got revert .
+.Cm got commit .
 .Pp
+If invoked in a work tree where no
+.Cm rebase ,
+.Cm histedit ,
+or
+.Cm merge
+operation is taking place,
 .Cm got backout
+creates a record of commits which have been reverse-merged into the work tree.
+When a file changed by
+.Cm got backout
+is committed with
+.Cm got commit ,
+the log messages of relevant reverse-merged commits will then appear in
+the editor, where the messages can be further adjusted as needed.
+If all the changes in all files touched by a given commit are discarded,
+e.g. with
+.Cm got revert ,
+this commit's log message record will also disappear.
+.Pp
+.Cm got backout
 will refuse to run if certain preconditions are not met.
 If the work tree contains multiple base commits, it must first be updated
 to a single base commit with
@@ -2123,7 +2155,7 @@ This option cannot be used with
 Otherwise, all commit log messages will be displayed irrespective of the
 work tree in which they were created.
 This option cannot be used with
-.Cm X .
+.Fl X .
 .It Fl X
 Delete log messages created by previous backout operations, represented by
 references in the
@@ -2138,7 +2170,7 @@ This option cannot be used with
 Otherwise, all commit log messages will be deleted irrespective of the
 work tree in which they were created.
 This option cannot be used with
-.Cm l .
+.Fl l .
 .El
 .Pp
 .Tg rb