From: "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com>
To: "Jean-Noël Avila" <gitgitgadget@gmail•com>, git@vger•kernel.org
Cc: "Jean-Noël AVILA" <jn.avila@free•fr>
Subject: Re: [PATCH v3 1/4] doc: convert git-submodule to synopsis style
Date: Tue, 03 Feb 2026 22:45:12 +0100 [thread overview]
Message-ID: <bd07e62d-b185-4d1a-9bb5-7c075d6508c2@app.fastmail.com> (raw)
In-Reply-To: <8d22e6952a3c0e20d9cc797e2dcc216591b10e6b.1770138215.git.gitgitgadget@gmail.com>
On Tue, Feb 3, 2026, at 18:03, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free•fr>
>
> * convert commands to synopsis style
> * use _<placeholder>_ for arguments
> * convert inline lists into proper definition lists
> * minor formatting fixes
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free•fr>
> Reviewed-by: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail•com>
`Reviewed-by` is a special case. It’s the only trailer that has to be
given explicitly by the person.
(trailers that credit other people should also come before the signoff)
Thanks for the credit, of course. :)
> ---
> Documentation/git-submodule.adoc | 389 ++++++++++++++++---------------
> 1 file changed, 196 insertions(+), 193 deletions(-)
>
> diff --git a/Documentation/git-submodule.adoc b/Documentation/git-submodule.adoc
> index 95beaee561..e581b0c7aa 100644
> --- a/Documentation/git-submodule.adoc
> +++ b/Documentation/git-submodule.adoc
> @@ -8,19 +8,19 @@ git-submodule - Initialize, update or inspect submodules
>[snip]
> DESCRIPTION
> @@ -34,16 +34,16 @@ COMMANDS
> With no arguments, shows the status of existing submodules. Several
> subcommands are available to perform operations on the submodules.
>
> -add [-b <branch>] [-f|--force] [--name <name>] [--reference
> <repository>] [--ref-format <format>] [--depth <depth>] [--]
> <repository> [<path>]::
> +`add [-b <branch>] [-f | --force] [--name <name>] [--reference
> <repository>] [--ref-format <format>] [--depth <depth>] [--]
> <repository> [<path>]`::
> Add the given repository as a submodule at the given path
> to the changeset to be committed next to the current
> project: the current project is termed the "superproject".
> +
> -<repository> is the URL of the new submodule's origin repository.
> -This may be either an absolute URL, or (if it begins with ./
> -or ../), the location relative to the superproject's default remote
> -repository (Please note that to specify a repository 'foo.git'
> -which is located right next to a superproject 'bar.git', you'll
> +_<repository>_ is the URL of the new submodule's `origin` repository.
This (`origin`) is new. I have never used git-submodule(1). Is this
*code* or is it jargon for something like “original” repository? It came
in commit ec05df35 (git-submodule - make "submodule add" more strict,
and document it, 2008-07-09):
With this patch, the URL locating the submodule's origin repository can be
either an absolute URL, or (if it begins with ./ or ../) can express the
submodule's repository location relative to the superproject's origin.
The "origin" that I referred to in the previous round was this sentence
a little way down:
If no such remote-tracking branch exists or the HEAD is detached,
"origin" is assumed to be the default remote.
And here I read “origin” as a real, concrete name. Which is why I
thought `origin` would fit instead.
> +This may be either an absolute URL, or (if it begins with `./`
> +or `../`), the location relative to the superproject's default remote
> +repository (Please note that to specify a repository `foo.git`
> +which is located right next to a superproject `bar.git`, you'll
>[snip]
>
> -status [--cached] [--recursive] [--] [<path>...]::
> +`status [--cached] [--recursive] [--] [<path>...]`::
> Show the status of the submodules. This will print the SHA-1 of the
> currently checked out commit for each submodule, along with the
> - submodule path and the output of 'git describe' for the
> + submodule path and the output of linkgit:git-describe[1] for the
> SHA-1. Each SHA-1 will possibly be prefixed with `-` if the submodule
> is
> not initialized, `+` if the currently checked out submodule commit
> does not match the SHA-1 found in the index of the containing
> @@ -95,7 +95,7 @@ submodules with respect to the commit recorded in the
> index or the HEAD,
Nit: There are some remaining “HEAD” without backticks.
The phrasing “the HEAD” does also keep recurring. Might be worth
replacing with just `HEAD` at this point?
> linkgit:git-status[1] and linkgit:git-diff[1] will provide that
> information
> too (and can also report changes to a submodule's work tree).
>[snip]
> +
> `git submodule sync` synchronizes all submodules while
> -`git submodule sync -- A` synchronizes submodule "A" only.
> +`git submodule sync -- A` synchronizes submodule `A` only.
`A`, good.
> +
> If `--recursive` is specified, this command will recurse into the
> registered submodules, and sync any nested submodules within.
>
> -absorbgitdirs::
> +`absorbgitdirs`::
> If a git directory of a submodule is inside the submodule,
> move the git directory of the submodule into its superproject's
> `$GIT_DIR/modules` path and then connect the git directory and
> its working directory by setting the `core.worktree` and adding
> - a .git file pointing to the git directory embedded in the
> + a `.git` file pointing to the git directory embedded in the
> superprojects git directory.
> +
> A repository that was cloned independently and later added as a submodule or
> @@ -279,72 +283,70 @@ This command is recursive by default.
>
> OPTIONS
> -------
> --q::
> ---quiet::
> +`-q`::
> +`--quiet`::
> Only print error messages.
>
> ---progress::
> - This option is only valid for add and update commands.
> - Progress status is reported on the standard error stream
> - by default when it is attached to a terminal, unless -q
> +`--progress`::
> + Report progress status on the standard error stream
> + by default when it is attached to a terminal, unless `-q`
> is specified. This flag forces progress status even if the
> - standard error stream is not directed to a terminal.
> + standard error stream is not directed to a terminal. It is
> + only valid for `add` and `update` commands.
>
> ---all::
> - This option is only valid for the deinit command. Unregister all
> - submodules in the working tree.
> +`--all`::
> + Unregister all submodules in the working tree. This option is only
> + valid for the `deinit` command.
>
> --b <branch>::
> ---branch <branch>::
> +`-b<branch>`::
> +`--branch=<branch>`::
Stuck form, nice.
> Branch of repository to add as submodule.
> The name of the branch is recorded as `submodule.<name>.branch` in
> `.gitmodules` for `update --remote`. A special value of `.` is used to
> indicate that the name of the branch in the submodule should be the
> same name as the current branch in the current repository. If the
> - option is not specified, it defaults to the remote 'HEAD'.
>[snip]
> ---rebase::
> - This option is only valid for the update command.
> - Rebase the current branch onto the commit recorded in the
> - superproject. If this option is given, the submodule's HEAD will not
> +`--rebase`::
> + Rebase the current branch onto the commit recorded in the
> superproject.
> + This option is only valid for the update command. The submodule's HEAD will not
I’m sorry. I missed these two before: `update` and `HEAD`. :(
>[snip]
> ---name::
> - This option is only valid for the add command. It sets the submodule's
> - name to the given string instead of defaulting to its path. The name
> +`--name=<name>`::
> + Set the submodule's name to the given string instead of defaulting to
> its path. _<name>_
> must be valid as a directory name and may not end with a '/'.
nit: `/`.
>[snip]
> FILES
> -----
> When initializing submodules, a `.gitmodules` file in the top-level directory
> -of the containing repository is used to find the url of each submodule.
> +of the containing repository is used to find the URL of each submodule.
> This file should be formatted in the same way as `$GIT_DIR/config`. The key
> -to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5]
> +to each submodule URL is `submodule.<name>.url`. See linkgit:gitmodules[5]
Replacing `$name` with `<name>`. Nice.
> for details.
>
> SEE ALSO
> --
> gitgitgadget
next prev parent reply other threads:[~2026-02-03 21:45 UTC|newest]
Thread overview: 38+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-01-23 21:14 [PATCH 0/4] doc: some more synopsis conversions and fixes Jean-Noël Avila via GitGitGadget
2026-01-23 21:15 ` [PATCH 1/4] convert git-submodule doc to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-01 12:04 ` Kristoffer Haugsbakk
2026-01-23 21:15 ` [PATCH 2/4] doc: finalize git-clone documentation conversion " Jean-Noël Avila via GitGitGadget
2026-02-01 12:04 ` Kristoffer Haugsbakk
2026-02-01 13:14 ` Jean-Noël AVILA
2026-02-02 8:36 ` Kristoffer Haugsbakk
2026-01-23 21:15 ` [PATCH 3/4] doc: fix some style issues in git-clone and for-each-ref-options Jean-Noël Avila via GitGitGadget
2026-02-01 12:11 ` Kristoffer Haugsbakk
2026-01-23 21:15 ` [PATCH 4/4] doc: convert git-show to synopsis style Jean-Noël Avila via GitGitGadget
2026-01-25 19:27 ` Kristoffer Haugsbakk
2026-01-25 21:11 ` Jean-Noël AVILA
2026-01-26 5:58 ` Kristoffer Haugsbakk
2026-01-26 21:25 ` [PATCH v2 0/4] doc: some more synopsis conversions and fixes Jean-Noël Avila via GitGitGadget
2026-01-26 21:25 ` [PATCH v2 1/4] convert git-submodule doc to synopsis style Jean-Noël Avila via GitGitGadget
2026-01-26 21:25 ` [PATCH v2 2/4] doc: finalize git-clone documentation conversion " Jean-Noël Avila via GitGitGadget
2026-01-26 21:25 ` [PATCH v2 3/4] doc: fix some style issues in git-clone and for-each-ref-options Jean-Noël Avila via GitGitGadget
2026-01-26 21:25 ` [PATCH v2 4/4] doc: convert git-show to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-01 12:12 ` Kristoffer Haugsbakk
2026-02-01 16:39 ` Jean-Noël AVILA
2026-02-03 17:03 ` [PATCH v3 0/4] doc: some more synopsis conversions and fixes Jean-Noël Avila via GitGitGadget
2026-02-03 17:03 ` [PATCH v3 1/4] doc: convert git-submodule to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-03 21:45 ` Kristoffer Haugsbakk [this message]
2026-02-06 3:55 ` Jean-Noël Avila
2026-02-03 17:03 ` [PATCH v3 2/4] doc: finalize git-clone documentation conversion " Jean-Noël Avila via GitGitGadget
2026-02-03 21:45 ` Kristoffer Haugsbakk
2026-02-03 17:03 ` [PATCH v3 3/4] doc: fix some style issues in git-clone and for-each-ref-options Jean-Noël Avila via GitGitGadget
2026-02-03 21:46 ` Kristoffer Haugsbakk
2026-02-03 17:03 ` [PATCH v3 4/4] doc: convert git-show to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-03 21:44 ` Kristoffer Haugsbakk
2026-02-03 21:44 ` [PATCH v3 0/4] doc: some more synopsis conversions and fixes Kristoffer Haugsbakk
2026-02-04 16:24 ` Kristoffer Haugsbakk
2026-02-06 4:12 ` [PATCH v4 " Jean-Noël Avila via GitGitGadget
2026-02-06 4:12 ` [PATCH v4 1/4] doc: convert git-submodule to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-06 4:12 ` [PATCH v4 2/4] doc: finalize git-clone documentation conversion " Jean-Noël Avila via GitGitGadget
2026-02-06 4:12 ` [PATCH v4 3/4] doc: fix some style issues in git-clone and for-each-ref-options Jean-Noël Avila via GitGitGadget
2026-02-06 4:12 ` [PATCH v4 4/4] doc: convert git-show to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-07 14:24 ` [PATCH v4 0/4] doc: some more synopsis conversions and fixes Kristoffer Haugsbakk
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=bd07e62d-b185-4d1a-9bb5-7c075d6508c2@app.fastmail.com \
--to=kristofferhaugsbakk@fastmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=jn.avila@free$(echo .)fr \
/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