bug#75355: [PATCH 0/1] Improve comment cycling in log-edit

bug#75355: [PATCH 0/1] Improve comment cycling in log-edit

[Jonas Bernoulli via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Hello,

In https://lists.gnu.org/archive/html/emacs-devel/2025-01/msg00041.html
we are discussing adding git-commit.el to Emacs.  This change is triggered
by that discussion but what I suggest here is to first move some code out
of git-commit.el and into log-edit.el.

Previously git-commit.el wrapped around some commands from log-edit.el
to provide better variants.  The following patch instead modifies the
existing commands.  It also adds a new command and a new helper function.

     Cheers,
     Jonas


Jonas Bernoulli (1):
  Improve comment cycling in log-edit

 lisp/vc/log-edit.el | 62 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 59 insertions(+), 3 deletions(-)

-- 
2.47.1

bug#75355: [PATCH 1/1] Improve comment cycling in log-edit

[Jonas Bernoulli via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Save the current message before cycling to older messages, making it
possible to cycle back to that initial message.

* lisp/vc/log-edit.el (log-edit-buffer-comment): New function.
(log-edit-save-comment): New command, using new function.
(log-edit-mode-map, log-edit-menu): Bind new command.
(log-edit-previous-comment): Use new function.

Port log-edit-comment-ring improvements from git-commit.el
---
 lisp/vc/log-edit.el | 62 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 59 insertions(+), 3 deletions(-)

diff --git a/lisp/vc/log-edit.el b/lisp/vc/log-edit.el
index e23e7414a18..79ea89bc728 100644
--- a/lisp/vc/log-edit.el
+++ b/lisp/vc/log-edit.el
@@ -61,6 +61,7 @@ log-edit-mode-map
   "C-c C-d" #'log-edit-show-diff
   "C-c C-f" #'log-edit-show-files
   "C-c C-k" #'log-edit-kill-buffer
+  "C-c C-s" #'log-edit-save-comment
   "M-n"     #'log-edit-next-comment
   "M-p"     #'log-edit-previous-comment
   "M-r"     #'log-edit-comment-search-backward
@@ -86,6 +87,8 @@ log-edit-menu
     ["List files" log-edit-show-files
      :help "Show the list of relevant files."]
     "--"
+    ["Save comment"		log-edit-save-comment
+     :help "Save the current comment to comment history"]
     ["Previous comment"		log-edit-previous-comment
      :help "Cycle backwards through comment history"]
     ["Next comment"		log-edit-next-comment
@@ -280,15 +283,68 @@ log-edit-new-comment-index
 	(t stride))
        len))
 
+(defun log-edit-buffer-comment ()
+  "Return the comment in the current buffer.
+Remove lines after the scissors line (\"------- >8 ------\") and
+commented lines from the returned string.  Also remove leading and
+trailing whitespace.  If the comment consists solely of whitespace,
+return nil."
+  (let ((flush (concat "^" comment-start))
+        (str (buffer-substring-no-properties (point-min) (point-max))))
+    (with-temp-buffer
+      (insert str)
+      (goto-char (point-min))
+      (when (re-search-forward (concat flush " -+ >8 -+$") nil t)
+        (delete-region (line-beginning-position) (point-max)))
+      (goto-char (point-min))
+      (flush-lines flush)
+      (goto-char (point-max))
+      (unless (eq (char-before) ?\n)
+        (insert ?\n))
+      (setq str (buffer-string)))
+    (and (not (string-match "\\`[ \t\n\r]*\\'" str))
+         (progn
+           (when (string-match "\\`\n\\{2,\\}" str)
+             (setq str (replace-match "\n" t t str)))
+           (when (string-match "\n\\{2,\\}\\'" str)
+             (setq str (replace-match "\n" t t str)))
+           str))))
+
+(defun log-edit-save-comment ()
+  "Save current comment to `log-edit-comment-ring'."
+  (interactive)
+  (if-let* ((comment (log-edit-buffer-comment)))
+      (progn
+        (when-let* ((index (ring-member log-edit-comment-ring comment)))
+          (ring-remove log-edit-comment-ring index))
+        (ring-insert log-edit-comment-ring comment)
+        ;; This hook can be used, e.g., to store this in an alternative,
+        ;; repository-local ring.
+        (run-hooks 'log-edit-save-comment-hook)
+        (message "Comment saved"))
+    (message "Only whitespace and/or comments; message not saved")))
+
 (defun log-edit-previous-comment (arg)
   "Cycle backwards through VC commit comment history.
 With a numeric prefix ARG, go back ARG comments."
   (interactive "*p")
   (let ((len (ring-length log-edit-comment-ring)))
     (if (<= len 0)
-	(progn (message "Empty comment ring") (ding))
-      ;; Don't use `erase-buffer' because we don't want to `widen'.
-      (delete-region (point-min) (point-max))
+        (progn (message "Empty comment ring") (ding))
+      (when-let* ((comment (log-edit-buffer-comment))
+                  ((not (ring-member log-edit-comment-ring comment))))
+        (ring-insert log-edit-comment-ring comment)
+        (cl-incf arg)
+        (setq len (ring-length log-edit-comment-ring)))
+      ;; Delete the message but not the instructions at the end.
+      (save-restriction
+        (goto-char (point-min))
+        (narrow-to-region
+         (point)
+         (if (re-search-forward (concat "^" comment-start) nil t)
+             (max 1 (- (point) 2))
+           (point-max)))
+        (delete-region (point-min) (point)))
       (setq log-edit-comment-ring-index (log-edit-new-comment-index arg len))
       (message "Comment %d" (1+ log-edit-comment-ring-index))
       (insert (ring-ref log-edit-comment-ring log-edit-comment-ring-index)))))
-- 
2.47.1

bug#75355: [PATCH 1/1] Improve comment cycling in log-edit

[Eli Zaretskii]

> Date: Sat,  4 Jan 2025 18:11:08 +0100
> From:  Jonas Bernoulli via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> Save the current message before cycling to older messages, making it
> possible to cycle back to that initial message.

Thanks, but can you provide some rationale for this?  Is the
assumption that users need to make several commits that all share the
same comment or something?

bug#75355: [PATCH 1/1] Improve comment cycling in log-edit

[Jonas Bernoulli via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Sat,  4 Jan 2025 18:11:08 +0100
>> From:  Jonas Bernoulli via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> 
>> Save the current message before cycling to older messages, making it
>> possible to cycle back to that initial message.
>
> Thanks, but can you provide some rationale for this?  Is the
> assumption that users need to make several commits that all share the
> same comment or something?

That is one use-case for the feature as it exists now, yes.  Messages
are already automatically saved once the user either finished or aborts
the commit.

These changes don't really affect that.  I consider this additional
automatic saving a bugfix.  Without it, a user may start typing a new
message, decide to use a recent message instead, navigate to it but then
change their mind about that, and then they would not be able to go back
to the new message they had already started typing, because it was
discarded when they moved a way from it.  By saving the new message when
we move away from it, we make it possible to navigate back to it.

By additionally defining log-edit-save-comment as a command we gain the
ability to save the message at random point.  This could, for example,
be useful if we have to use very similar messages in different commits,
potentially across multiple repositories.  We could then write the
common part, save it as a "template", edit it some more, and finally
create a first commit.  Without the save command we could rely on the
automatic saving at the very end of that process, which would mean that
when creating the second commit we could not use the template as such,
but only template with the modifications for the first commit already
filled in.  More editing could be required to go from that to what we
actually want to use in the second commit.

bug#75355: [PATCH 1/1] Improve comment cycling in log-edit

[Eli Zaretskii]

> From: Jonas Bernoulli <jonas@bernoul.li>
> Cc: 75355@debbugs.gnu.org
> Date: Sat, 04 Jan 2025 23:29:34 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Date: Sat,  4 Jan 2025 18:11:08 +0100
> >> From:  Jonas Bernoulli via "Bug reports for GNU Emacs,
> >>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> >> 
> >> Save the current message before cycling to older messages, making it
> >> possible to cycle back to that initial message.
> >
> > Thanks, but can you provide some rationale for this?  Is the
> > assumption that users need to make several commits that all share the
> > same comment or something?
> 
> That is one use-case for the feature as it exists now, yes.  Messages
> are already automatically saved once the user either finished or aborts
> the commit.
> 
> These changes don't really affect that.  I consider this additional
> automatic saving a bugfix.  Without it, a user may start typing a new
> message, decide to use a recent message instead, navigate to it but then
> change their mind about that, and then they would not be able to go back
> to the new message they had already started typing, because it was
> discarded when they moved a way from it.  By saving the new message when
> we move away from it, we make it possible to navigate back to it.

What do you mean by "move away" and "navigate", in the context of
log-edit?

> By additionally defining log-edit-save-comment as a command we gain the
> ability to save the message at random point.  This could, for example,
> be useful if we have to use very similar messages in different commits,
> potentially across multiple repositories.

Is this a frequent use case?  Why would the same log message be used
for different commits?

bug#75355: [PATCH 1/1] Improve comment cycling in log-edit

[Jonas Bernoulli via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jonas Bernoulli <jonas@bernoul.li>
>> Cc: 75355@debbugs.gnu.org
>> Date: Sat, 04 Jan 2025 23:29:34 +0100
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> Date: Sat,  4 Jan 2025 18:11:08 +0100
>> >> From:  Jonas Bernoulli via "Bug reports for GNU Emacs,
>> >>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> >> 
>> >> Save the current message before cycling to older messages, making it
>> >> possible to cycle back to that initial message.
>> >
>> > Thanks, but can you provide some rationale for this?  Is the
>> > assumption that users need to make several commits that all share the
>> > same comment or something?
>> 
>> That is one use-case for the feature as it exists now, yes.  Messages
>> are already automatically saved once the user either finished or aborts
>> the commit.
>> 
>> These changes don't really affect that.  I consider this additional
>> automatic saving a bugfix.  Without it, a user may start typing a new
>> message, decide to use a recent message instead, navigate to it but then
>> change their mind about that, and then they would not be able to go back
>> to the new message they had already started typing, because it was
>> discarded when they moved a way from it.  By saving the new message when
>> we move away from it, we make it possible to navigate back to it.
>
> What do you mean by "move away" and "navigate", in the context of
> log-edit?

The buffer contains a draft to be used as the message for the commit
you are about to create.  "Moving away" from the message means using
the commands log-edit-previous/next-comment to "navigate" to another
message.  Doing so erased the contents of the buffer, and another
recently used message is inserted in its place.

>> By additionally defining log-edit-save-comment as a command we gain the
>> ability to save the message at random point.  This could, for example,
>> be useful if we have to use very similar messages in different commits,
>> potentially across multiple repositories.
>
> Is this a frequent use case?  Why would the same log message be used
> for different commits?

Using the same or very similar commit messages across different
repositories is a very frequent occurrence for me.  The last such
message was "Bump copyright years", but through out the year I also use
messages such as "Fix spelling errors", after running a spell-checker on
all my packages.

Granted, those two examples didn't need a "template".  I also frequently
fix some class of error across many third-party packages, as part of my
work on Melpa and the Emacsmirror.  In such cases I often write a long,
message explaining why something should be done a certain way.  The
message is almost the same for every repository/package but I try to use
the names of the files in each particular repository, to make things more
engaging and actionable for each individual package maintainer.

Note that the command log-edit-save-comment is also used in code twice,
so the cost of making it a command is just the line " (interactive)".
If you feel this command is not useful enough to receive a default key
bindings, we can drop that, but the interactive form should remain.