From: Junio C Hamano <gitster@pobox•com>
To: "Jean-Noël Avila" <jn.avila@free•fr>
Cc: Meet Soni <meetsoni3017@gmail•com>,
git@vger•kernel.org, ps@pks•im, shejialuo@gmail•com
Subject: Re: [PATCH] doc:git-for-each-ref: fix styling and typos
Date: Mon, 30 Jun 2025 08:48:05 -0700 [thread overview]
Message-ID: <xmqqjz4t44ei.fsf@gitster.g> (raw)
In-Reply-To: <20250629110652.123890-1-jn.avila@free.fr> ("Jean-Noël Avila"'s message of "Sun, 29 Jun 2025 13:05:31 +0200")
Jean-Noël Avila <jn.avila@free•fr> writes:
> This commit fixes the synopsis syntax writing and changes the wording of a few
> descriptions to be more consistent with the rest of the documentation.
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free•fr>
> ---
> Documentation/git-for-each-ref.adoc | 30 ++++++++++++++---------------
> 1 file changed, 14 insertions(+), 16 deletions(-)
It is not making anything worse and all the changes I see here
(except for a stray SP slipped in) are for the better, but it is
curious that this stops halfway. Things I noticed:
> diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc
> index 5ef89fc0fe..c2b2660771 100644
> --- a/Documentation/git-for-each-ref.adoc
> +++ b/Documentation/git-for-each-ref.adoc
> @@ -8,13 +8,13 @@ git-for-each-ref - Output information on each ref
> SYNOPSIS
> --------
> [verse]
Eventually we would switch to [synopsis] I presume?
> -'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
> - [(--sort=<key>)...] [--format=<format>]
> - [--include-root-refs] [ --stdin | <pattern>... ]
> +'git for-each-ref' [--count=<count>] [--shell | --perl | --python | --tcl]
> + [(--sort=<key>)...] [--format[=<format>]]
> + [--include-root-refs] [--stdin | <pattern>...]
> [--points-at=<object>]
> [--merged[=<object>]] [--no-merged[=<object>]]
> [--contains[=<object>]] [--no-contains[=<object>]]
> - [--exclude=<pattern> ...]
> + [(--exclude=<excluded-pattern>)...]
>
> DESCRIPTION
> -----------
> @@ -35,13 +35,11 @@ OPTIONS
> beginning up to a slash.
>
> --stdin::
> - If `--stdin` is supplied, then the list of patterns is read from
> - standard input instead of from the argument list.
> + The list of patterns is read from standard input instead of from
> + the argument list.
>
> --count=<count>::
> - By default the command shows all refs that match
> - `<pattern>`. This option makes it stop after showing
> - that many refs.
> + Stop after showing <count> refs.
This patch would have changed this to _<count>_, judging from what
it did elsewhere.
> @@ -50,7 +48,7 @@ OPTIONS
> multiple times, in which case the last key becomes the primary
> key.
>
> ---format=<format>::
> + --format[=<format>]::
Stray SP in the front?
> @@ -100,10 +98,10 @@ TAB %(refname)`.
> Do not print a newline after formatted refs where the format expands
> to the empty string.
>
> ---exclude=<pattern>::
> - If one or more patterns are given, only refs which do not match
> - any excluded pattern(s) are shown. Matching is done using the
> - same rules as `<pattern>` above.
> +--exclude=<excluded-pattern>::
> + If one or more --exclude options are given, only refs which do not
> + match any _<excluded-pattern>_ parameters are shown. Matching is done
> + using the same rules as _<pattern>_ above.
OK. Doing the literal `--exclude` for options in the description is
left for future patches would not make it any worse, and adopting
_<placeholder>_ convention makes it better.
> --include-root-refs::
> List root refs (HEAD and pseudorefs) apart from regular refs.
> @@ -131,8 +129,8 @@ refname::
> `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)`
> turns `refs/tags/foo` into `refs`). When the ref does not have
> enough components, the result becomes an empty string if
> - stripping with positive <N>, or it becomes the full refname if
> - stripping with negative <N>. Neither is an error.
> + stripping with positive _<N>_, or it becomes the full refname if
> + stripping with negative _<N>_. Neither is an error.
> +
> `strip` can be used as a synonym to `lstrip`.
next prev parent reply other threads:[~2025-06-30 15:48 UTC|newest]
Thread overview: 65+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-06-27 7:49 [GSoC][RFC PATCH 0/2] Add refs list subcommand Meet Soni
2025-06-27 7:49 ` [GSoC][RFC PATCH 1/2] builtin/refs: add " Meet Soni
2025-06-27 16:27 ` Jean-Noël Avila
2025-06-27 18:13 ` Junio C Hamano
2025-06-30 4:28 ` Meet Soni
2025-06-29 11:05 ` [PATCH] doc:git-for-each-ref: fix styling and typos Jean-Noël Avila
2025-06-30 15:48 ` Junio C Hamano [this message]
2025-06-30 18:55 ` Jean-Noël AVILA
2025-06-27 7:49 ` [GSoC][RFC PATCH 2/2] t: add test for git refs list subcommand Meet Soni
2025-06-27 18:03 ` [GSoC][RFC PATCH 0/2] Add " Junio C Hamano
2025-06-28 8:05 ` shejialuo
2025-06-30 14:05 ` Junio C Hamano
2025-07-06 12:58 ` shejialuo
2025-06-30 3:53 ` Meet Soni
2025-06-30 20:10 ` Junio C Hamano
2025-07-09 13:36 ` Patrick Steinhardt
2025-07-17 7:50 ` [GSoC][RFC PATCH v2 " Meet Soni
2025-07-17 7:50 ` [GSoC][RFC PATCH v2 1/2] builtin/refs: add " Meet Soni
2025-07-17 16:48 ` Eric Sunshine
2025-07-23 5:01 ` Meet Soni
2025-07-17 7:50 ` [GSoC][RFC PATCH v2 2/2] t: add test for git refs " Meet Soni
2025-07-17 21:01 ` Junio C Hamano
2025-07-23 5:17 ` Meet Soni
2025-07-23 15:03 ` Junio C Hamano
2025-07-23 6:43 ` [GSoC][RFC PATCH v3 0/3] Add " Meet Soni
2025-07-23 6:43 ` [GSoC][RFC PATCH v3 1/3] builtin/refs: add " Meet Soni
2025-07-24 5:58 ` Patrick Steinhardt
2025-07-24 16:01 ` Junio C Hamano
2025-07-25 11:10 ` Meet Soni
2025-07-23 6:43 ` [GSoC][RFC PATCH v3 2/3] t6300: refactor tests to be shareable Meet Soni
2025-07-23 6:43 ` [GSoC][RFC PATCH v3 3/3] t: add test for git refs list subcommand Meet Soni
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 0/5] Add " Meet Soni
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 1/5] doc: factor out common option Meet Soni
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 2/5] builtin/for-each-ref: factor out core logic into a helper Meet Soni
2025-08-01 5:54 ` Patrick Steinhardt
2025-08-04 6:34 ` Meet Soni
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 3/5] builtin/refs: add list subcommand Meet Soni
2025-08-01 13:27 ` Phillip Wood
2025-08-01 14:43 ` Junio C Hamano
2025-08-01 15:49 ` Phillip Wood
2025-08-01 17:14 ` Junio C Hamano
2025-08-04 9:28 ` Phillip Wood
2025-08-04 6:32 ` Meet Soni
2025-08-04 9:27 ` Phillip Wood
2025-08-04 15:35 ` Junio C Hamano
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 4/5] t6300: refactor tests to be shareable Meet Soni
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 5/5] t: add test for git refs list subcommand Meet Soni
2025-08-01 5:54 ` [GSoC][RFC PATCH v4 0/5] Add " Patrick Steinhardt
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 0/6] " Meet Soni
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 1/6] doc: factor out common option Meet Soni
2025-08-04 18:34 ` Junio C Hamano
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 2/6] builtin/for-each-ref: align usage string with the man page Meet Soni
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 3/6] builtin/for-each-ref: factor out core logic into a helper Meet Soni
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 4/6] builtin/refs: add list subcommand Meet Soni
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 5/6] t6300: refactor tests to be shareable Meet Soni
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 6/6] t: add test for git refs list subcommand Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 0/6] Add " Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 1/6] doc: factor out common option Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 2/6] builtin/for-each-ref: align usage string with the man page Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 3/6] builtin/for-each-ref: factor out core logic into a helper Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 4/6] builtin/refs: add list subcommand Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 5/6] t6300: refactor tests to be shareable Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 6/6] t: add test for git refs list subcommand Meet Soni
2025-08-05 13:07 ` [GSoC][PATCH v6 0/6] Add " Patrick Steinhardt
2025-08-05 16:12 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqjz4t44ei.fsf@gitster.g \
--to=gitster@pobox$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=jn.avila@free$(echo .)fr \
--cc=meetsoni3017@gmail$(echo .)com \
--cc=ps@pks$(echo .)im \
--cc=shejialuo@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox