Re: [PATCH 1/3] doc: git-commit: apply new documentation guidelines
- From
Patrick Steinhardt <ps@pks.im>
- Date
- Jan 6, 2025, 07:38 UTC
- Message-ID
- <Z3uIZA0bIXzaUxlH@pks.im>
- In-Reply-To
- <dfd907fc3147b438222bbfad9b0a7ca61df642a5.1735912046.git.gitgitgadget@gmail.com>
On Fri, Jan 03, 2025 at 01:47:24PM +0000, Jean-Noël Avila via GitGitGadget wrote:
Show 16 quoted lines
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> > > 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 :)
Show 23 quoted lines
> 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.
Show 13 quoted lines
> @@ -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.
Show 13 quoted lines
> 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