From: Derrick Stolee <derrickstolee@github.com>
Date: Wed, 29 Jun 2022 13:02:25 GMT
Subject: Re: [PATCH v3 3/8] rebase-interactive: update 'merge' description
Message-ID: <eb4345ce-8e1c-2f5f-7dfb-41979a89491a@github.com>
In-Reply-To: <xmqqletgijul.fsf@gitster.g>

On 6/28/22 5:00 PM, Junio C Hamano wrote:
> "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> From: Derrick Stolee <derrickstolee@github.com>
>>
>> The 'merge' command description for the todo list documentation in an
>> interactive rebase has multiple lines. The lines other than the first
>> one start with dots ('.') while the similar multi-line documentation for
>> 'fixup' does not.
>>
>> The 'merge' command was documented when interactive rebase was first
>> ported to C in 145e05ac44b (rebase -i: rewrite append_todo_help() in C,
>> 2018-08-10). These dots might have been carried over from the previous
>> shell implementation.
> 
> The text indeed does come literally from the block removed by that
> commit.  I wondered if the shell "gettext" in git-i18n.sh had some
> magic in it, but it does not seem to have anything, and po/git.pot
> around that time has these lines with leading dots, so I suspect
> that they were quite deliberately added, not for the reasons of
> formatting machinery (e.g. preventing somebody in the dataflow from
> losing leading indentation), but to show them to the end users.
> 
> Unfortunately, the offending commit 4c68e7dd (sequencer: introduce
> the `merge` command, 2018-04-25) does not justify them X-<.
> 
>> Looking at the output in an editor, my personal opinion is that the dots
>> are unnecessary and noisy. Remove them now before adding more commands
>> with multi-line documentation.
> 
> I personally do not mind having them in the UI, but I can also be
> happy to see them go.  It is unlikely that any program is consuming
> these strings, so I would say this is a fairly safe clean-up.

Perhaps I should be a bit clearer that these are appearing in the
comment section of the todo-file when presented to the user for editing:

# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
#                    commit's log message, unless -C is used, in which case
#                    keep only this commit's message; -c is same as -C but
#                    opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
# .       create a merge commit using the original merge commit's
# .       message (or the oneline, if no original merge commit was
# .       specified); use -c <commit> to reword the commit message
#
# These lines can be re-ordered; they are executed from top to bottom.
#

This does not appear to be used anywhere else.

Thanks,
-Stolee