Re: [PATCH v3 1/4] doc: convert git-submodule to synopsis style

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Feb 3, 2026, 21:45 UTC
Message-ID: <bd07e62d-b185-4d1a-9bb5-7c075d6508c2@app.fastmail.com>
In-Reply-To: <8d22e6952a3c0e20d9cc797e2dcc216591b10e6b.1770138215.git.gitgitgadget@gmail.com>

On Tue, Feb 3, 2026, at 18:03, Jean-Noël Avila via GitGitGadget wrote:

Show 9 quoted lines

> 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. :)

Show 31 quoted lines

> ---
>  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.

Show 18 quoted lines

> +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?

Show 8 quoted lines

>  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.

Show 48 quoted lines

>  +
>  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.

Show 15 quoted lines

>  	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`. :(

Show 8 quoted lines

>[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: `/`.

Show 9 quoted lines

>[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.

Show 5 quoted lines

>  for details.
>
>  SEE ALSO
> --
> gitgitgadget