On Fri, Jan 03, 2025 at 01:47:24PM +0000, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@xxxxxxx>
>
> The documentation for git-commit has been updated to follow the new
> documentation guidelines. The following changes have been applied to
> the series of patches:
>
> - switching the synopsis to a synopsis block which will automatically
> format placeholders in italics and keywords in monospace
> - use _<placeholder>_ instead of <placeholder> in the description
> - use `backticks for keywords and more complex option
> descriptions`. The new rendering engine will apply synopsis rules to
> these spans.
>
> Additionally, some option descriptions have been turned into
> imperative mood to make them more consistent with the rest of the
> documentation.
Same comment here regarding the commit message as on the other two
series. We should use imperative mood for it, as well :)
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index c822113c111..b08a398e31d 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -58,139 +58,139 @@ summary of what is included by any of the above for the next
> --z::
> ---null::
> +`-z`::
> +`--null`::
> When showing `short` or `porcelain` status output, print the
> - filename verbatim and terminate the entries with NUL, instead of LF.
> + filename verbatim and terminate the entries with _NUL_, instead of _LF_.
> If no format is given, implies the `--porcelain` output format.
> Without the `-z` option, filenames with "unusual" characters are
> quoted as explained for the configuration variable `core.quotePath`
> (see linkgit:git-config[1]).
>
> --F <file>::
> ---file=<file>::
> - Take the commit message from the given file. Use '-' to
> +`-F <file>`::
> +`--file=<file>`::
> + Take the commit message from _<file>_. Use `-` to
I think it would make sense to move changes like this, where the actual
wording changes, into a separate commit. That'd make it way easier to
spot the non-mechanical changes from those that may require some
discussion.
> @@ -257,19 +256,18 @@ default::
> The default can be changed by the `commit.cleanup` configuration
> variable (see linkgit:git-config[1]).
>
> --e::
> ---edit::
> - The message taken from file with `-F`, command line with
> - `-m`, and from commit object with `-C` are usually used as
> - the commit log message unmodified. This option lets you
> - further edit the message taken from these sources.
> +`-e`::
> +`--edit`::
> + Let the user further edit the message taken from file
There's a double space here. I was also wondering whether this should
say _<file>_ here to further clarify that this refers to the same
placeholder as the placeholder in `-F`. Might be confusing though, I
dunno.
> diff --git a/builtin/commit.c b/builtin/commit.c
> index ef5e622c077..a7315ed67cc 100644
> --- a/builtin/commit.c
> +++ b/builtin/commit.c
> @@ -44,7 +44,7 @@
> #include "trailer.h"
>
> static const char * const builtin_commit_usage[] = {
> - N_("git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]\n"
> + N_("git commit [-a | --interactive | --patch] [-s] [-v] [-u[<mode>]] [--amend]\n"
> " [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>]\n"
> " [-F <file> | -m <msg>] [--reset-author] [--allow-empty]\n"
> " [--allow-empty-message] [--no-verify] [-e] [--author=<author>]\n"
I guess this change is required to make t0450 happy?
Patrick
