From: Jean-Noël Avila via GitGitGadget Date: Fri, 06 Feb 2026 04:12:22 GMT Subject: [PATCH v4 0/4] doc: some more synopsis conversions and fixes Message-ID: In-Reply-To: This time, git-show and git-submodule are converted. Some mistakes on previous work were also spotted and fixed. Changes since V1: * fix mistakes spotted by Kristoffer Haugsbakk Changes since V2: * more fixes Changes since V3: * again more fixes, origin and HEAD Jean-Noël Avila (4): doc: convert git-submodule to synopsis style doc: finalize git-clone documentation conversion to synopsis style doc: fix some style issues in git-clone and for-each-ref-options doc: convert git-show to synopsis style Documentation/asciidoc.conf.in | 6 + Documentation/for-each-ref-options.adoc | 4 +- Documentation/git-clone.adoc | 54 ++-- Documentation/git-show.adoc | 16 +- Documentation/git-submodule.adoc | 395 ++++++++++++------------ Documentation/pretty-formats.adoc | 169 +++++----- Documentation/ref-storage-format.adoc | 4 +- 7 files changed, 341 insertions(+), 307 deletions(-) base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2036%2Fjnavila%2Fgit_submodule-v4 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2036/jnavila/git_submodule-v4 Pull-Request: https://github.com/gitgitgadget/git/pull/2036 Range-diff vs v3: 1: 8d22e6952a ! 1: 7798802b59 doc: convert git-submodule to synopsis style @@ Commit message * convert inline lists into proper definition lists * minor formatting fixes - Signed-off-by: Jean-Noël Avila Reviewed-by: Kristoffer Haugsbakk + Signed-off-by: Jean-Noël Avila ## Documentation/git-submodule.adoc ## @@ Documentation/git-submodule.adoc: git-submodule - Initialize, update or inspect submodules @@ Documentation/git-submodule.adoc: COMMANDS have to use `../foo.git` instead of `./foo.git` - as one might expect when following the rules for relative URLs - because the evaluation of relative URLs in Git is identical to that of relative directories). -@@ Documentation/git-submodule.adoc: If the superproject doesn't have a default remote configured + + + The default remote is the remote of the remote-tracking branch + of the current branch. If no such remote-tracking branch exists or +-the HEAD is detached, "origin" is assumed to be the default remote. ++the `HEAD` is detached, `origin` is assumed to be the default remote. + If the superproject doesn't have a default remote configured the superproject is its own authoritative upstream and the current working directory is used instead. + @@ Documentation/git-submodule.adoc: URL in `.gitmodules`. 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 -@@ Documentation/git-submodule.adoc: submodules with respect to the commit recorded in the index or the HEAD, +@@ Documentation/git-submodule.adoc: If `--recursive` is specified, this command will recurse into nested + submodules, and show their status as well. + + + If you are only interested in changes of the currently initialized +-submodules with respect to the commit recorded in the index or the HEAD, ++submodules with respect to the commit recorded in the index or the `HEAD`, 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). @@ Documentation/git-submodule.adoc: in submodules and updating the working tree of - checkout;; the commit recorded in the superproject will be - checked out in the submodule on a detached HEAD. +`checkout`;; the commit recorded in the superproject will be -+checked out in the submodule on a detached HEAD. ++checked out in the submodule on a detached `HEAD`. + If `--force` is specified, the submodule will be checked out (using `git checkout --force`), even if the commit specified @@ Documentation/git-submodule.adoc: to distribute the default upstream branch with - 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 ++ This option is only valid for the `update` command. The submodule's `HEAD` will not be detached. If a merge failure prevents this process, you will have to resolve these failures with linkgit:git-rebase[1]. - If the key `submodule.$name.update` is set to `rebase`, this option is @@ Documentation/git-submodule.adoc: to distribute the default upstream branch with ---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 +- must be valid as a directory name and may not end with a '/'. +`--name=`:: + Set the submodule's name to the given string instead of defaulting to its path. __ - must be valid as a directory name and may not end with a '/'. ++ must be valid as a directory name and may not end with a `/`. ---reference :: - This option is only valid for add and update commands. These 2: 5fd9f6d41a ! 2: 41aefe8147 doc: finalize git-clone documentation conversion to synopsis style @@ Commit message Use backticks where appropriate for command-line options - Signed-off-by: Jean-Noël Avila Reviewed-by: Kristoffer Haugsbakk + Signed-off-by: Jean-Noël Avila ## Documentation/git-clone.adoc ## @@ Documentation/git-clone.adoc: objects from the source repository into a pack in the cloned repository. 3: d097065303 ! 3: fe928fe0ed doc: fix some style issues in git-clone and for-each-ref-options @@ Commit message * Use asciidoc NOTE macro * fix markups - Signed-off-by: Jean-Noël Avila Reviewed-by: Kristoffer Haugsbakk + Signed-off-by: Jean-Noël Avila ## Documentation/for-each-ref-options.adoc ## @@ Documentation/for-each-ref-options.adoc: TAB %(refname)`. 4: d179137d81 ! 4: 6a2b94e720 doc: convert git-show to synopsis style @@ Commit message * use __ for arguments * minor formatting fixes - Signed-off-by: Jean-Noël Avila Reviewed-by: Kristoffer Haugsbakk + Signed-off-by: Jean-Noël Avila ## Documentation/asciidoc.conf.in ## @@ Documentation/asciidoc.conf.in: endif::backend-xhtml11[] -- gitgitgadget