{"thread":{"id":"63916","subject":"[PATCH 0/6] Introduce more doc linting","startedAt":"2025-08-05T13:03:57Z","lastAt":"2025-08-14T17:23:10Z","messageCount":28,"participants":["Jean-Noël Avila via GitGitGadget","Junio C Hamano","Ramsay Jones","Collin Funk","Jean-Noël AVILA"],"isPatch":true,"patchVersion":1,"patchTotal":6},"messages":[{"id":"523537","messageId":"pull.1945.git.1754399033.gitgitgadget@gmail.com","threadId":"63916","inReplyTo":null,"subject":"[PATCH 0/6] Introduce more doc linting","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-05T13:03:47Z","receivedAt":"2025-08-05T13:03:57Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Reviewing the documentation part of the last patches, it turns out that the\nmajority of my comments are related to the latest documentation guidelines\nwhich are both easy to forget and almost trivial to automatically check.\n\nThis series implements the automatic tests for basic doc rules. At the\nmoment it conflicts with \"[GSoC][PATCH v6 0/6] Add refs list subcommand\" and\npossibly with \"[PATCH v4 0/9] refs: fix migration of reflog entries\"\n\nJean-Noël Avila (6):\n doc: test linkgit macros for well-formedness\n doc: check well-formedness of delimited sections\n doc: check for absence of multiple terms in each entry of desc list\n doc: check for absence of the form --[no-]parameter\n doc:git-for-each-ref: fix styling and typos\n doc lint: check that synopsis manpages have synopsis inlines\n\n Documentation/Makefile | 21 +-\n Documentation/RelNotes/1.6.2.4.adoc | 1 +\n Documentation/blame-options.adoc | 3 +-\n Documentation/diff-format.adoc | 1 +\n Documentation/diff-options.adoc | 3 +-\n Documentation/fetch-options.adoc | 15 +-\n Documentation/git-am.adoc | 3 +-\n Documentation/git-backfill.adoc | 3 +-\n Documentation/git-cat-file.adoc | 6 +-\n Documentation/git-check-attr.adoc | 3 +-\n Documentation/git-check-ignore.adoc | 9 +-\n Documentation/git-check-ref-format.adoc | 3 +-\n Documentation/git-clone.adoc | 12 +-\n Documentation/git-commit-graph.adoc | 3 +-\n Documentation/git-commit.adoc | 4 +-\n Documentation/git-config.adoc | 3 +-\n Documentation/git-difftool.adoc | 9 +-\n Documentation/git-fast-import.adoc | 5 +-\n Documentation/git-fmt-merge-msg.adoc | 3 +-\n Documentation/git-for-each-ref.adoc | 264 +++++++++---------\n Documentation/git-format-patch.adoc | 12 +-\n Documentation/git-fsck.adoc | 9 +-\n Documentation/git-gc.adoc | 6 +-\n Documentation/git-http-fetch.adoc | 4 +-\n Documentation/git-index-pack.adoc | 3 +-\n Documentation/git-log.adoc | 6 +-\n Documentation/git-merge-tree.adoc | 3 +-\n Documentation/git-multi-pack-index.adoc | 3 +-\n Documentation/git-p4.adoc | 1 +\n Documentation/git-pack-objects.adoc | 3 +-\n Documentation/git-pull.adoc | 3 +-\n Documentation/git-push.adoc | 18 +-\n Documentation/git-range-diff.adoc | 3 +-\n Documentation/git-read-tree.adoc | 3 +-\n Documentation/git-rebase.adoc | 2 +-\n Documentation/git-refs.adoc | 20 +-\n Documentation/git-reset.adoc | 3 +-\n Documentation/git-send-email.adoc | 30 +-\n Documentation/git-send-pack.adoc | 3 +-\n Documentation/git-submodule.adoc | 6 +-\n Documentation/git-svn.adoc | 2 +\n Documentation/git-update-index.adoc | 12 +-\n Documentation/git-upload-pack.adoc | 3 +-\n Documentation/git-worktree.adoc | 12 +-\n Documentation/gitprotocol-http.adoc | 2 +-\n Documentation/gitsubmodules.adoc | 3 +-\n Documentation/gitweb.conf.adoc | 2 +-\n Documentation/lint-delimited-sections.perl | 48 ++++\n Documentation/lint-documentation-style.perl | 33 +++\n Documentation/lint-gitlink.perl | 7 +\n Documentation/merge-options.adoc | 3 +-\n Documentation/mergetools/vimdiff.adoc | 8 +\n Documentation/scalar.adoc | 18 +-\n Documentation/technical/api-path-walk.adoc | 5 +-\n .../long-running-process-protocol.adoc | 1 +\n shared.mak | 2 +\n 56 files changed, 445 insertions(+), 231 deletions(-)\n create mode 100755 Documentation/lint-delimited-sections.perl\n create mode 100755 Documentation/lint-documentation-style.perl\n\n\nbase-commit: 112648dd6bdd8e4f485cd0ae11636807959d48be\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1945%2Fjnavila%2Fdoc_linting-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1945/jnavila/doc_linting-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1945\n-- \ngitgitgadget\n"},{"id":"523538","messageId":"e79bd6a67ef2ea7247359b2449c7c313c7fa9922.1754399033.git.gitgitgadget@gmail.com","threadId":"63916","inReplyTo":"pull.1945.git.1754399033.gitgitgadget@gmail.com","subject":"[PATCH 1/6] doc: test linkgit macros for well-formedness","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-05T13:03:48Z","receivedAt":"2025-08-05T13:03:58Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nSome readers of man pages have reported that they found\nmalformed linkgit macros in the documentation (absence or bad\nspelling).\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/gitweb.conf.adoc | 2 +-\n Documentation/lint-gitlink.perl | 7 +++++++\n 2 files changed, 8 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/gitweb.conf.adoc b/Documentation/gitweb.conf.adoc\nindex 1348e9b12504..64bebb811c97 100644\n--- a/Documentation/gitweb.conf.adoc\n+++ b/Documentation/gitweb.conf.adoc\n@@ -178,7 +178,7 @@ $export_ok::\n \tShow repository only if this file exists (in repository). Only\n \teffective if this variable evaluates to true. Can be set when\n \tbuilding gitweb by setting `GITWEB_EXPORT_OK`. This path is\n-\trelative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok',\n+\trelative to `GIT_DIR`. linkgit:git-daemon[1] uses 'git-daemon-export-ok',\n \tunless started with `--export-all`. By default this variable is\n \tnot set, which means that this feature is turned off.\n \ndiff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\nindex aea564dad7ed..f183a18df284 100755\n--- a/Documentation/lint-gitlink.perl\n+++ b/Documentation/lint-gitlink.perl\n@@ -41,6 +41,13 @@ die \"BUG: No list of valid linkgit:* files given\" unless @ARGV;\n @ARGV = $to_check;\n while (<>) {\n \tmy $line = $_;\n+\twhile ($line =~ m/(.{,8})((git[-a-z]+|scalar)\\[(\\d)*\\])/g) {\n+\t my $pos = pos $line;\n+\t my ($macro, $target, $page, $section) = ($1, $2, $3, $4);\n+\t\tif ( $macro ne \"linkgit:\" && $macro !~ \"ifn?def::\" && $macro ne \"endif::\" ) {\n+\t\t\treport($pos, $line, $target, \"linkgit: macro expected\");\n+\t\t}\n+\t}\n \twhile ($line =~ m/linkgit:((.*?)\\[(\\d)\\])/g) {\n \t\tmy $pos = pos $line;\n \t\tmy ($target, $page, $section) = ($1, $2, $3);\n-- \ngitgitgadget\n\n"},{"id":"523539","messageId":"322df2d8dde35916f91601029c4db89837776b5d.1754399033.git.gitgitgadget@gmail.com","threadId":"63916","inReplyTo":"pull.1945.git.1754399033.gitgitgadget@gmail.com","subject":"[PATCH 2/6] doc: check well-formedness of delimited sections","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-05T13:03:49Z","receivedAt":"2025-08-05T13:04:00Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nHaving an empty line before each delimited sections is not required by\nasciidoc, but it is a safety measure that prevents generating malformed\nasciidoc when generating translated documentation.\n\nWhen a delimited section appears just after a paragraph, the asciidoc\nprocessor checks that the length of the delimited section header is\ndifferent from the length of the paragraph. If it is not, the asciidoc\nprocessor will generate a title. In the original English documentation, this\nis not a problem because the authors always check the output of the asciidoc\nprocessor and fix the length of the delimited section header if it turns out\nto be the same as the paragraph length. However, this is not the case for\ntranslations, where the authors have no way to check the length of the\ndelimited section header or the output of the asciidoc processor. This can\nlead to a section title that is not intended.\n\nIndeed, this test also checks that titles are correctly formed, that is,\nthe length of the underline is equal to the length of the title (otherwise\nit would not be a title but a section header).\n\nFinally, this test checks that the delimited section are terminated within\nthe same file.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/Makefile | 11 ++++-\n Documentation/RelNotes/1.6.2.4.adoc | 1 +\n Documentation/diff-format.adoc | 1 +\n Documentation/git-commit.adoc | 1 +\n Documentation/git-fast-import.adoc | 2 +\n Documentation/git-p4.adoc | 1 +\n Documentation/git-rebase.adoc | 2 +-\n Documentation/git-svn.adoc | 2 +\n Documentation/gitprotocol-http.adoc | 2 +-\n Documentation/gitsubmodules.adoc | 3 +-\n Documentation/lint-delimited-sections.perl | 48 +++++++++++++++++++\n Documentation/mergetools/vimdiff.adoc | 8 ++++\n .../long-running-process-protocol.adoc | 1 +\n shared.mak | 1 +\n 14 files changed, 80 insertions(+), 4 deletions(-)\n create mode 100755 Documentation/lint-delimited-sections.perl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex df2ce187eb84..76a9e1d02b26 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -497,9 +497,17 @@ $(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.adoc\n \t$(call mkdir_p_parent_template)\n \t$(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \\\n \t\t../fsck.h fsck-msgids.adoc $@\n-\n lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)\n \n+## Lint: delimited sections\n+LINT_DOCS_DELIMITED_SECTIONS = $(patsubst %.adoc,.build/lint-docs/delimited-sections/%.ok,$(MAN_TXT))\n+$(LINT_DOCS_DELIMITED_SECTIONS): lint-delimited-sections.perl\n+$(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.adoc\n+\t$(call mkdir_p_parent_template)\n+\t$(QUIET_LINT_DELIMSEC)$(PERL_PATH) lint-delimited-sections.perl $< >$@\n+.PHONY: lint-docs-delimited-sections\n+lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS)\n+\n lint-docs-manpages:\n \t$(QUIET_GEN)./lint-manpages.sh\n \n@@ -528,6 +536,7 @@ lint-docs: lint-docs-fsck-msgids\n lint-docs: lint-docs-gitlink\n lint-docs: lint-docs-man-end-blurb\n lint-docs: lint-docs-man-section-order\n+lint-docs: lint-docs-delimited-sections\n lint-docs: lint-docs-manpages\n lint-docs: lint-docs-meson\n \ndiff --git a/Documentation/RelNotes/1.6.2.4.adoc b/Documentation/RelNotes/1.6.2.4.adoc\nindex f4bf1d09863c..053dbb604de6 100644\n--- a/Documentation/RelNotes/1.6.2.4.adoc\n+++ b/Documentation/RelNotes/1.6.2.4.adoc\n@@ -37,3 +37,4 @@ exec >/var/tmp/1\n echo O=$(git describe maint)\n O=v1.6.2.3-38-g318b847\n git shortlog --no-merges $O..maint\n+---\ndiff --git a/Documentation/diff-format.adoc b/Documentation/diff-format.adoc\nindex 80e36e153dac..9f7e98824183 100644\n--- a/Documentation/diff-format.adoc\n+++ b/Documentation/diff-format.adoc\n@@ -103,6 +103,7 @@ if the file was renamed on any side of history. With\n followed by the name of the path in the merge commit.\n \n Examples for `-c` and `--cc` without `--combined-all-paths`:\n+\n ------------------------------------------------\n ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM\tdesc.c\n ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM\tbar.sh\ndiff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc\nindex ae988a883b5b..d4d576ce665f 100644\n--- a/Documentation/git-commit.adoc\n+++ b/Documentation/git-commit.adoc\n@@ -281,6 +281,7 @@ variable (see linkgit:git-config[1]).\n +\n --\n It is a rough equivalent for:\n+\n ------\n \t$ git reset --soft HEAD^\n \t$ ... do something else to come up with the right tree ...\ndiff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc\nindex 6f9763c11b3c..6490d67fab56 100644\n--- a/Documentation/git-fast-import.adoc\n+++ b/Documentation/git-fast-import.adoc\n@@ -605,9 +605,11 @@ Marks must be declared (via `mark`) before they can be used.\n \n The special case of restarting an incremental import from the\n current branch value should be written as:\n+\n ----\n \tfrom refs/heads/branch^0\n ----\n+\n The `^0` suffix is necessary as fast-import does not permit a branch to\n start from itself, and the branch is created in memory before the\n `from` command is even read from the input. Adding `^0` will force\ndiff --git a/Documentation/git-p4.adoc b/Documentation/git-p4.adoc\nindex f97b786bf98a..59edd241341e 100644\n--- a/Documentation/git-p4.adoc\n+++ b/Documentation/git-p4.adoc\n@@ -66,6 +66,7 @@ Clone\n ~~~~~\n Generally, 'git p4 clone' is used to create a new Git directory\n from an existing p4 repository:\n+\n ------------\n $ git p4 clone //depot/path/project\n ------------\ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex 956d3048f5a6..727160c6db77 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -687,7 +687,7 @@ In addition, the following pairs of options are incompatible:\n * --fork-point and --root\n \n BEHAVIORAL DIFFERENCES\n------------------------\n+----------------------\n \n `git rebase` has two primary backends: 'apply' and 'merge'. (The 'apply'\n backend used to be known as the 'am' backend, but the name led to\ndiff --git a/Documentation/git-svn.adoc b/Documentation/git-svn.adoc\nindex bcf7d84a87d1..c26c12bab37a 100644\n--- a/Documentation/git-svn.adoc\n+++ b/Documentation/git-svn.adoc\n@@ -1012,9 +1012,11 @@ branch.\n \n If you do merge, note the following rule: 'git svn dcommit' will\n attempt to commit on top of the SVN commit named in\n+\n ------------------------------------------------------------------------\n git log --grep=^git-svn-id: --first-parent -1\n ------------------------------------------------------------------------\n+\n You 'must' therefore ensure that the most recent commit of the branch\n you want to dcommit to is the 'first' parent of the merge. Chaos will\n ensue otherwise, especially if the first parent is an older commit on\ndiff --git a/Documentation/gitprotocol-http.adoc b/Documentation/gitprotocol-http.adoc\nindex ec40a550ccab..d024010414aa 100644\n--- a/Documentation/gitprotocol-http.adoc\n+++ b/Documentation/gitprotocol-http.adoc\n@@ -318,7 +318,7 @@ Extra Parameter.\n \n \n Smart Service git-upload-pack\n-------------------------------\n+-----------------------------\n This service reads from the repository pointed to by `$GIT_URL`.\n \n Clients MUST first perform ref discovery with\ndiff --git a/Documentation/gitsubmodules.adoc b/Documentation/gitsubmodules.adoc\nindex f7b5a25a0caa..20822961999a 100644\n--- a/Documentation/gitsubmodules.adoc\n+++ b/Documentation/gitsubmodules.adoc\n@@ -8,6 +8,7 @@ gitsubmodules - Mounting one repository inside another\n SYNOPSIS\n --------\n .gitmodules, $GIT_DIR/config\n+\n ------------------\n git submodule\n git --recurse-submodules\n@@ -240,7 +241,7 @@ Workflow for a third party library\n \n \n Workflow for an artificially split repo\n---------------------------------------\n+---------------------------------------\n \n # Enable recursion for relevant commands, such that\n # regular commands recurse into submodules by default\ndiff --git a/Documentation/lint-delimited-sections.perl b/Documentation/lint-delimited-sections.perl\nnew file mode 100755\nindex 000000000000..140b852e5d46\n--- /dev/null\n+++ b/Documentation/lint-delimited-sections.perl\n@@ -0,0 +1,48 @@\n+#!/usr/bin/perl\n+\n+use strict;\n+use warnings;\n+\n+my $exit_code = 0;\n+sub report {\n+\tmy ($msg) = @_;\n+\tprint STDERR \"$ARGV:$.: $msg\\n\";\n+\t$exit_code = 1;\n+}\n+\n+my $line_length = 0;\n+my $in_section = 0;\n+my $section_header = \"\";\n+\n+\n+while (my $line = <>) {\n+\tif (($line =~ /^\\+?$/) ||\n+\t ($line =~ /^\\[.*\\]$/) ||\n+\t ($line =~ /^ifdef::/)) {\n+\t\t$line_length = 0;\n+\t} elsif ($line =~ /^[^-.]/) {\n+\t\t$line_length = length($line);\n+\t} elsif (($line =~ /^-{3,}$/) || ($line =~ /^\\.{3,}$/)) {\n+\t\tif ($in_section) {\n+\t\t\tif ($line eq $section_header) {\n+\t\t\t\t$in_section = 0;\n+\t\t\t}\n+\t\tnext;\n+\t\t}\n+\t\tif ($line_length == 0) {\n+\t\t\t$in_section = 1;\n+\t\t\t$section_header = $line;\n+\t\t\tnext;\n+\t\t}\n+\t\tif (($line_length != 0) && (length($line) != $line_length)) {\n+\t\t\treport(\"section delimiter not preceded by an empty line\");\n+\t\t}\n+\t\t$line_length = 0;\n+\t}\n+}\n+\n+if ($in_section) {\n+\treport(\"section not finished\");\n+}\n+\n+exit $exit_code;\ndiff --git a/Documentation/mergetools/vimdiff.adoc b/Documentation/mergetools/vimdiff.adoc\nindex abfd426f74a0..b4ab83a510e0 100644\n--- a/Documentation/mergetools/vimdiff.adoc\n+++ b/Documentation/mergetools/vimdiff.adoc\n@@ -3,6 +3,7 @@ Description\n \n When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4\n windows layout distributed in the following way:\n+\n ....\n ------------------------------------------\n | | | |\n@@ -56,6 +57,7 @@ needed in this case. The next layout definition is equivalent:\n +\n --\n If, for some reason, we are not interested in the `BASE` buffer.\n+\n ....\n ------------------------------------------\n | | | |\n@@ -72,6 +74,7 @@ If, for some reason, we are not interested in the `BASE` buffer.\n Only the `MERGED` buffer will be shown. Note, however, that all the other\n ones are still loaded in vim, and you can access them with the \"buffers\"\n command.\n+\n ....\n ------------------------------------------\n | |\n@@ -88,6 +91,7 @@ command.\n When `MERGED` is not present in the layout, you must \"mark\" one of the\n buffers with an arobase (`@`). That will become the buffer you need to edit and\n save after resolving the conflicts.\n+\n ....\n ------------------------------------------\n | | |\n@@ -106,6 +110,7 @@ save after resolving the conflicts.\n Three tabs will open: the first one is a copy of the default layout, while\n the other two only show the differences between (`BASE` and `LOCAL`) and\n (`BASE` and `REMOTE`) respectively.\n+\n ....\n ------------------------------------------\n | | TAB #2 | TAB #3 | |\n@@ -119,6 +124,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and\n | |\n ------------------------------------------\n ....\n+\n ....\n ------------------------------------------\n | TAB #1 | | TAB #3 | |\n@@ -132,6 +138,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and\n | | |\n ------------------------------------------\n ....\n+\n ....\n ------------------------------------------\n | TAB #1 | TAB #2 | | |\n@@ -151,6 +158,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and\n --\n Same as the previous example, but adds a fourth tab with the same\n information as the first tab, with a different layout.\n+\n ....\n ---------------------------------------------\n | TAB #1 | TAB #2 | TAB #3 | |\ndiff --git a/Documentation/technical/long-running-process-protocol.adoc b/Documentation/technical/long-running-process-protocol.adoc\nindex 6f33654b4288..39bd89d467d6 100644\n--- a/Documentation/technical/long-running-process-protocol.adoc\n+++ b/Documentation/technical/long-running-process-protocol.adoc\n@@ -24,6 +24,7 @@ After the version negotiation Git sends a list of all capabilities that\n it supports and a flush packet. Git expects to read a list of desired\n capabilities, which must be a subset of the supported capabilities list,\n and a flush packet as response:\n+\n ------------------------\n packet: git> git-filter-client\n packet: git> version=2\ndiff --git a/shared.mak b/shared.mak\nindex 1a99848a9517..57095d6cf96c 100644\n--- a/shared.mak\n+++ b/shared.mak\n@@ -88,6 +88,7 @@ ifndef V\n \n \tQUIET_LINT_GITLINK\t= @echo ' ' LINT GITLINK $<;\n \tQUIET_LINT_MANSEC\t= @echo ' ' LINT MAN SEC $<;\n+\tQUIET_LINT_DELIMSEC\t= @echo ' ' LINT DEL SEC $<;\n \tQUIET_LINT_MANEND\t= @echo ' ' LINT MAN END $<;\n \n \texport V\n-- \ngitgitgadget\n\n"},{"id":"523540","messageId":"5806390052b7a7cbdb8dc843bfcc24102604e2f6.1754399033.git.gitgitgadget@gmail.com","threadId":"63916","inReplyTo":"pull.1945.git.1754399033.gitgitgadget@gmail.com","subject":"[PATCH 3/6] doc: check for absence of multiple terms in each entry of desc list","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-05T13:03:50Z","receivedAt":"2025-08-05T13:04:00Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nDue to portability issues, the script generate-configlist.sh was fixed to\nnot use carriage returns in the output. However, the result is that it no\nlonger correctly handles multiple terms in a single entry of the definition\nlist.\n\nWe now check that these entries do not exist in the documentation.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/Makefile | 10 +++++++++\n Documentation/git-check-attr.adoc | 3 ++-\n Documentation/git-check-ignore.adoc | 9 +++++---\n Documentation/git-http-fetch.adoc | 4 +++-\n Documentation/lint-documentation-style.perl | 24 +++++++++++++++++++++\n Documentation/technical/api-path-walk.adoc | 5 ++++-\n shared.mak | 1 +\n 7 files changed, 50 insertions(+), 6 deletions(-)\n create mode 100755 Documentation/lint-documentation-style.perl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 76a9e1d02b26..ac8a21e3015c 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -508,6 +508,15 @@ $(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.ado\n .PHONY: lint-docs-delimited-sections\n lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS)\n \n+## Lint: Documentation style\n+LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(MAN_TXT))\n+$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl\n+$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc\n+\t$(call mkdir_p_parent_template)\n+\t$(QUIET_LINT_DOCSTYLE)$(PERL_PATH) lint-documentation-style.perl $< >$@\n+.PHONY: lint-docs-doc-style\n+lint-docs-doc-style: $(LINT_DOCS_DOC_STYLE)\n+\n lint-docs-manpages:\n \t$(QUIET_GEN)./lint-manpages.sh\n \n@@ -537,6 +546,7 @@ lint-docs: lint-docs-gitlink\n lint-docs: lint-docs-man-end-blurb\n lint-docs: lint-docs-man-section-order\n lint-docs: lint-docs-delimited-sections\n+lint-docs: lint-docs-doc-style\n lint-docs: lint-docs-manpages\n lint-docs: lint-docs-meson\n \ndiff --git a/Documentation/git-check-attr.adoc b/Documentation/git-check-attr.adoc\nindex 503b6446574d..15a37a38e3f7 100644\n--- a/Documentation/git-check-attr.adoc\n+++ b/Documentation/git-check-attr.adoc\n@@ -19,7 +19,8 @@ For every pathname, this command will list if each attribute is 'unspecified',\n \n OPTIONS\n -------\n--a, --all::\n+-a::\n+--all::\n \tList all attributes that are associated with the specified\n \tpaths. If this option is used, then 'unspecified' attributes\n \twill not be included in the output.\ndiff --git a/Documentation/git-check-ignore.adoc b/Documentation/git-check-ignore.adoc\nindex 3e3b4e344629..a6c6c1b6e5be 100644\n--- a/Documentation/git-check-ignore.adoc\n+++ b/Documentation/git-check-ignore.adoc\n@@ -25,11 +25,13 @@ subject to exclude rules; but see `--no-index'.\n \n OPTIONS\n -------\n--q, --quiet::\n+-q::\n+--quiet::\n \tDon't output anything, just set exit status. This is only\n \tvalid with a single pathname.\n \n--v, --verbose::\n+-v::\n+--verbose::\n \tInstead of printing the paths that are excluded, for each path\n \tthat matches an exclude pattern, print the exclude pattern\n \ttogether with the path. (Matching an exclude pattern usually\n@@ -49,7 +51,8 @@ linkgit:gitignore[5].\n \tbelow). If `--stdin` is also given, input paths are separated\n \twith a NUL character instead of a linefeed character.\n \n--n, --non-matching::\n+-n::\n+--non-matching::\n \tShow given paths which don't match any pattern. This only\n \tmakes sense when `--verbose` is enabled, otherwise it would\n \tnot be possible to distinguish between paths which match a\ndiff --git a/Documentation/git-http-fetch.adoc b/Documentation/git-http-fetch.adoc\nindex 4ec7c68d3b9e..dcb05890aefd 100644\n--- a/Documentation/git-http-fetch.adoc\n+++ b/Documentation/git-http-fetch.adoc\n@@ -25,8 +25,10 @@ commit-id::\n Either the hash or the filename under [URL]/refs/ to\n pull.\n \n--a, -c, -t::\n+-a::-c::\n+-t::\n \tThese options are ignored for historical reasons.\n+\n -v::\n \tReport what is downloaded.\n \ndiff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl\nnew file mode 100755\nindex 000000000000..1f35a6a116da\n--- /dev/null\n+++ b/Documentation/lint-documentation-style.perl\n@@ -0,0 +1,24 @@\n+#!/usr/bin/perl\n+\n+use strict;\n+use warnings;\n+\n+my $exit_code = 0;\n+sub report {\n+\tmy ($line, $msg) = @_;\n+\tchomp $line;\n+\tprint STDERR \"$ARGV:$.: '$line' $msg\\n\";\n+\t$exit_code = 1;\n+}\n+\n+my $synopsis_style = 0;\n+\n+while (my $line = <>) {\n+\tif ($line =~ /^[ \\t]*`?[-a-z0-9.]+`?(, `?[-a-z0-9.]+`?)+(::|;;)$/) {\n+\n+\t\treport($line, \"multiple parameters in a definition list item\");\n+\t}\n+}\n+\n+\n+exit $exit_code;\ndiff --git a/Documentation/technical/api-path-walk.adoc b/Documentation/technical/api-path-walk.adoc\nindex 34c905eb9c31..a67de1b143ab 100644\n--- a/Documentation/technical/api-path-walk.adoc\n+++ b/Documentation/technical/api-path-walk.adoc\n@@ -39,7 +39,10 @@ It is also important that you do not specify the `--objects` flag for the\n the objects will be walked in a separate way based on those starting\n commits.\n \n-`commits`, `blobs`, `trees`, `tags`::\n+`commits`::\n+`blobs`::\n+`trees`::\n+`tags`::\n \tBy default, these members are enabled and signal that the path-walk\n \tAPI should call the `path_fn` on objects of these types. Specialized\n \tapplications could disable some options to make it simpler to walk\ndiff --git a/shared.mak b/shared.mak\nindex 57095d6cf96c..5c7bc9478544 100644\n--- a/shared.mak\n+++ b/shared.mak\n@@ -89,6 +89,7 @@ ifndef V\n \tQUIET_LINT_GITLINK\t= @echo ' ' LINT GITLINK $<;\n \tQUIET_LINT_MANSEC\t= @echo ' ' LINT MAN SEC $<;\n \tQUIET_LINT_DELIMSEC\t= @echo ' ' LINT DEL SEC $<;\n+\tQUIET_LINT_DOCSTYLE\t= @echo ' ' LINT DOCSTYLE $<;\n \tQUIET_LINT_MANEND\t= @echo ' ' LINT MAN END $<;\n \n \texport V\n-- \ngitgitgadget\n\n"},{"id":"523541","messageId":"03a8428849f9a464d6480eae5ea182b95bd61027.1754399033.git.gitgitgadget@gmail.com","threadId":"63916","inReplyTo":"pull.1945.git.1754399033.gitgitgadget@gmail.com","subject":"[PATCH 4/6] doc: check for absence of the form --[no-]parameter","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-05T13:03:51Z","receivedAt":"2025-08-05T13:04:02Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nFor better searchability, this commit adds a check to ensure that parameters\nexpressed in the form of `--[no-]parameter` are not used in the\ndocumentation. In the place of such parameters, the documentation should\nlist two separate parameters: `--parameter` and `--no-parameter`.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/blame-options.adoc | 3 ++-\n Documentation/diff-options.adoc | 3 ++-\n Documentation/fetch-options.adoc | 15 +++++++----\n Documentation/git-am.adoc | 3 ++-\n Documentation/git-backfill.adoc | 3 ++-\n Documentation/git-cat-file.adoc | 6 +++--\n Documentation/git-check-ref-format.adoc | 3 ++-\n Documentation/git-clone.adoc | 12 ++++++---\n Documentation/git-commit-graph.adoc | 3 ++-\n Documentation/git-commit.adoc | 3 ++-\n Documentation/git-config.adoc | 3 ++-\n Documentation/git-difftool.adoc | 9 ++++---\n Documentation/git-fast-import.adoc | 3 ++-\n Documentation/git-fmt-merge-msg.adoc | 3 ++-\n Documentation/git-format-patch.adoc | 12 ++++++---\n Documentation/git-fsck.adoc | 9 ++++---\n Documentation/git-gc.adoc | 6 +++--\n Documentation/git-index-pack.adoc | 3 ++-\n Documentation/git-log.adoc | 6 +++--\n Documentation/git-merge-tree.adoc | 3 ++-\n Documentation/git-multi-pack-index.adoc | 3 ++-\n Documentation/git-pack-objects.adoc | 3 ++-\n Documentation/git-pull.adoc | 3 ++-\n Documentation/git-push.adoc | 18 ++++++++-----\n Documentation/git-range-diff.adoc | 3 ++-\n Documentation/git-read-tree.adoc | 3 ++-\n Documentation/git-reset.adoc | 3 ++-\n Documentation/git-send-email.adoc | 30 ++++++++++++++-------\n Documentation/git-send-pack.adoc | 3 ++-\n Documentation/git-submodule.adoc | 6 +++--\n Documentation/git-update-index.adoc | 12 ++++++---\n Documentation/git-upload-pack.adoc | 3 ++-\n Documentation/git-worktree.adoc | 12 ++++++---\n Documentation/lint-documentation-style.perl | 3 +++\n Documentation/merge-options.adoc | 3 ++-\n Documentation/scalar.adoc | 18 ++++++++-----\n 36 files changed, 159 insertions(+), 78 deletions(-)\n\ndiff --git a/Documentation/blame-options.adoc b/Documentation/blame-options.adoc\nindex 19ea1872388f..1fb948fc76f3 100644\n--- a/Documentation/blame-options.adoc\n+++ b/Documentation/blame-options.adoc\n@@ -75,7 +75,8 @@ include::line-range-format.adoc[]\n \tiso format is used. For supported values, see the discussion\n \tof the --date option at linkgit:git-log[1].\n \n---[no-]progress::\n+--progress::\n+--no-progress::\n \tProgress status is reported on the standard error stream\n \tby default when it is attached to a terminal. This flag\n \tenables progress reporting even if not attached to a\ndiff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc\nindex f3a35d81411f..f19b85142f4e 100644\n--- a/Documentation/diff-options.adoc\n+++ b/Documentation/diff-options.adoc\n@@ -505,7 +505,8 @@ endif::git-format-patch[]\n \tTurn off rename detection, even when the configuration\n \tfile gives the default to do so.\n \n-`--[no-]rename-empty`::\n+`--rename-empty`::\n+`--no-rename-empty`::\n \tWhether to use empty blobs as rename source.\n \n ifndef::git-format-patch[]\ndiff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\nindex b01372e4b3c6..d3ac31f4e2a1 100644\n--- a/Documentation/fetch-options.adoc\n+++ b/Documentation/fetch-options.adoc\n@@ -1,4 +1,5 @@\n---[no-]all::\n+--all::\n+--no-all::\n \tFetch all remotes, except for the ones that has the\n \t`remote..skipFetchAll` configuration variable set.\n \tThis overrides the configuration variable fetch.all`.\n@@ -88,7 +89,8 @@ This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes\n precedence over the `fetch.output` config option.\n \n ifndef::git-pull[]\n---[no-]write-fetch-head::\n+--write-fetch-head::\n+--no-write-fetch-head::\n \tWrite the list of remote refs fetched in the `FETCH_HEAD`\n \tfile directly under `$GIT_DIR`. This is the default.\n \tPassing `--no-write-fetch-head` from the command line tells\n@@ -118,13 +120,16 @@ ifndef::git-pull[]\n \tAllow several and arguments to be\n \tspecified. No s may be specified.\n \n---[no-]auto-maintenance::\n---[no-]auto-gc::\n+--auto-maintenance::\n+--no-auto-maintenance::\n+--auto-gc::\n+--no-auto-gc::\n \tRun `git maintenance run --auto` at the end to perform automatic\n \trepository maintenance if needed. (`--[no-]auto-gc` is a synonym.)\n \tThis is enabled by default.\n \n---[no-]write-commit-graph::\n+--write-commit-graph::\n+--no-write-commit-graph::\n \tWrite a commit-graph after fetching. This overrides the config\n \tsetting `fetch.writeCommitGraph`.\n endif::git-pull[]\ndiff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc\nindex 221070de4812..b23b4fba2013 100644\n--- a/Documentation/git-am.adoc\n+++ b/Documentation/git-am.adoc\n@@ -48,7 +48,8 @@ OPTIONS\n --keep-non-patch::\n \tPass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).\n \n---[no-]keep-cr::\n+--keep-cr::\n+--no-keep-cr::\n \tWith `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1])\n \twith the same option, to prevent it from stripping CR at the end of\n \tlines. `am.keepcr` configuration variable can be used to specify the\ndiff --git a/Documentation/git-backfill.adoc b/Documentation/git-backfill.adoc\nindex 95623051f789..b8394dcf22b6 100644\n--- a/Documentation/git-backfill.adoc\n+++ b/Documentation/git-backfill.adoc\n@@ -57,7 +57,8 @@ OPTIONS\n \tblobs seen at a given path. The default minimum batch size is\n \t50,000.\n \n-`--[no-]sparse`::\n+`--sparse`::\n+`--no-sparse`::\n \tOnly download objects if they appear at a path that matches the\n \tcurrent sparse-checkout. If the sparse-checkout feature is enabled,\n \tthen `--sparse` is assumed and can be disabled with `--no-sparse`.\ndiff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc\nindex 180d1ad363fd..c139f55a168d 100644\n--- a/Documentation/git-cat-file.adoc\n+++ b/Documentation/git-cat-file.adoc\n@@ -62,8 +62,10 @@ OPTIONS\n \tor to ask for a \"blob\" with `` being a tag object that\n \tpoints at it.\n \n---[no-]mailmap::\n---[no-]use-mailmap::\n+--mailmap::\n+--no-mailmap::\n+--use-mailmap::\n+--no-use-mailmap::\n Use mailmap file to map author, committer and tagger names\n and email addresses to canonical real names and email addresses.\n See linkgit:git-shortlog[1].\ndiff --git a/Documentation/git-check-ref-format.adoc b/Documentation/git-check-ref-format.adoc\nindex 2aacfd18088d..0c3abf914657 100644\n--- a/Documentation/git-check-ref-format.adoc\n+++ b/Documentation/git-check-ref-format.adoc\n@@ -98,7 +98,8 @@ a branch.\n \n OPTIONS\n -------\n---[no-]allow-onelevel::\n+--allow-onelevel::\n+--no-allow-onelevel::\n \tControls whether one-level refnames are accepted (i.e.,\n \trefnames that do not contain multiple `/`-separated\n \tcomponents). The default is `--no-allow-onelevel`.\ndiff --git a/Documentation/git-clone.adoc b/Documentation/git-clone.adoc\nindex 222d558290ed..031b56f09824 100644\n--- a/Documentation/git-clone.adoc\n+++ b/Documentation/git-clone.adoc\n@@ -272,7 +272,8 @@ corresponding `--mirror` and `--no-tags` options instead.\n \treachable from a specified remote branch or tag. This option\n \tcan be specified multiple times.\n \n-`--[no-]single-branch`::\n+`--single-branch`::\n+`--no-single-branch`::\n \tClone only the history leading to the tip of a single branch,\n \teither specified by the `--branch` option or the primary\n \tbranch remote's `HEAD` points at.\n@@ -282,7 +283,8 @@ corresponding `--mirror` and `--no-tags` options instead.\n \tbranch when `--single-branch` clone was made, no remote-tracking\n \tbranch is created.\n \n-`--[no-]tags`::\n+`--tags`::\n+`--no-tags`::\n \tControl whether or not tags will be cloned. When `--no-tags` is\n \tgiven, the option will be become permanent by setting the\n \t`remote..tagOpt=--no-tags` configuration. This ensures that\n@@ -313,10 +315,12 @@ the clone is finished. This option is ignored if the cloned repository does\n not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,\n or `--mirror` is given)\n \n-`--[no-]shallow-submodules`::\n+`--shallow-submodules`::\n+`--no-shallow-submodules`::\n \tAll submodules which are cloned will be shallow with a depth of 1.\n \n-`--[no-]remote-submodules`::\n+`--remote-submodules`::\n+`--no-remote-submodules`::\n \tAll submodules which are cloned will use the status of the submodule's\n \tremote-tracking branch to update the submodule, rather than the\n \tsuperproject's recorded SHA-1. Equivalent to passing `--remote` to\ndiff --git a/Documentation/git-commit-graph.adoc b/Documentation/git-commit-graph.adoc\nindex 50b50168045c..e9558173c001 100644\n--- a/Documentation/git-commit-graph.adoc\n+++ b/Documentation/git-commit-graph.adoc\n@@ -34,7 +34,8 @@ OPTIONS\n \tobject directory, `git commit-graph ...` will exit with non-zero\n \tstatus.\n \n---[no-]progress::\n+--progress::\n+--no-progress::\n \tTurn progress on/off explicitly. If neither is specified, progress is\n \tshown if standard error is connected to a terminal.\n \ndiff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc\nindex d4d576ce665f..54c207ad45ea 100644\n--- a/Documentation/git-commit.adoc\n+++ b/Documentation/git-commit.adoc\n@@ -214,7 +214,8 @@ include::signoff-option.adoc[]\n \teach trailer would appear, and other details.\n \n `-n`::\n-`--[no-]verify`::\n+`--verify`::\n+`--no-verify`::\n \tBypass the `pre-commit` and `commit-msg` hooks.\n \tSee also linkgit:githooks[5].\n \ndiff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc\nindex 511b2e26bfb0..36d28451528e 100644\n--- a/Documentation/git-config.adoc\n+++ b/Documentation/git-config.adoc\n@@ -295,7 +295,8 @@ Valid ``'s include:\n \tWhen the color setting for `name` is undefined, the command uses\n \t`color.ui` as fallback.\n \n---[no-]includes::\n+--includes::\n+--no-includes::\n \tRespect `include.*` directives in config files when looking up\n \tvalues. Defaults to `off` when a specific file is given (e.g.,\n \tusing `--file`, `--global`, etc) and `on` when searching all\ndiff --git a/Documentation/git-difftool.adoc b/Documentation/git-difftool.adoc\nindex d596205eaf3b..064bc683471f 100644\n--- a/Documentation/git-difftool.adoc\n+++ b/Documentation/git-difftool.adoc\n@@ -77,7 +77,8 @@ with custom merge tool commands and has the same value as `$MERGED`.\n --tool-help::\n \tPrint a list of diff tools that may be used with `--tool`.\n \n---[no-]symlinks::\n+--symlinks::\n+--no-symlinks::\n \t'git difftool''s default behavior is to create symlinks to the\n \tworking tree when run in `--dir-diff` mode and the right-hand\n \tside of the comparison yields the same content as the file in\n@@ -94,7 +95,8 @@ instead. `--no-symlinks` is the default on Windows.\n \tAdditionally, `$BASE` is set in the environment.\n \n -g::\n---[no-]gui::\n+--gui::\n+--no-gui::\n \tWhen 'git-difftool' is invoked with the `-g` or `--gui` option\n \tthe default diff tool will be read from the configured\n \t`diff.guitool` variable instead of `diff.tool`. This may be\n@@ -104,7 +106,8 @@ instead. `--no-symlinks` is the default on Windows.\n \tfallback in the order of `merge.guitool`, `diff.tool`,\n \t`merge.tool` until a tool is found.\n \n---[no-]trust-exit-code::\n+--trust-exit-code::\n+--no-trust-exit-code::\n \tErrors reported by the diff tool are ignored by default.\n \tUse `--trust-exit-code` to make 'git-difftool' exit when an\n \tinvoked diff tool returns a non-zero exit code.\ndiff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc\nindex 6490d67fab56..3144ffcdb689 100644\n--- a/Documentation/git-fast-import.adoc\n+++ b/Documentation/git-fast-import.adoc\n@@ -111,7 +111,8 @@ Locations of Marks Files\n \tLike --import-marks but instead of erroring out, silently\n \tskips the file if it does not exist.\n \n---[no-]relative-marks::\n+--relative-marks::\n+--no-relative-marks::\n \tAfter specifying --relative-marks the paths specified\n \twith --import-marks= and --export-marks= are relative\n \tto an internal directory in the current repository.\ndiff --git a/Documentation/git-fmt-merge-msg.adoc b/Documentation/git-fmt-merge-msg.adoc\nindex 0f3328956dfd..6d91620be979 100644\n--- a/Documentation/git-fmt-merge-msg.adoc\n+++ b/Documentation/git-fmt-merge-msg.adoc\n@@ -35,7 +35,8 @@ OPTIONS\n \tDo not list one-line descriptions from the actual commits being\n \tmerged.\n \n---[no-]summary::\n+--summary::\n+--no-summary::\n \tSynonyms to --log and --no-log; these are deprecated and will be\n \tremoved in the future.\n \ndiff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc\nindex a8b53db9a663..048d1b981524 100644\n--- a/Documentation/git-format-patch.adoc\n+++ b/Documentation/git-format-patch.adoc\n@@ -295,7 +295,8 @@ header). Note also that `git send-email` already handles this\n transformation for you, and this option should not be used if you are\n feeding the result to `git send-email`.\n \n---[no-]force-in-body-from::\n+--force-in-body-from::\n+--no-force-in-body-from::\n \tWith the e-mail sender specified via the `--from` option, by\n \tdefault, an in-body \"From:\" to identify the real author of\n \tthe commit is added at the top of the commit log message if\n@@ -314,7 +315,8 @@ feeding the result to `git send-email`.\n \t`Cc:`, and custom) headers added so far from config or command\n \tline.\n \n---[no-]cover-letter::\n+--cover-letter::\n+--no-cover-letter::\n \tIn addition to the patches, generate a cover letter file\n \tcontaining the branch description, shortlog and the overall diffstat. You can\n \tfill in a description in the file before sending it out.\n@@ -379,7 +381,8 @@ configuration options in linkgit:git-notes[1] to use this workflow).\n The default is `--no-notes`, unless the `format.notes` configuration is\n set.\n \n---[no-]signature=::\n+--signature=::\n+--no-signature::\n \tAdd a signature to each message produced. Per RFC 3676 the signature\n \tis separated from the body by a line with '-- ' on it. If the\n \tsignature option is omitted the signature defaults to the Git version\n@@ -411,7 +414,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.\n Output an all-zero hash in each patch's From header instead\n of the hash of the commit.\n \n---[no-]base[=]::\n+--no-base::\n+--base[=]::\n \tRecord the base tree information to identify the state the\n \tpatch series applies to. See the BASE TREE INFORMATION section\n \tbelow for details. If is \"auto\", a base commit is\ndiff --git a/Documentation/git-fsck.adoc b/Documentation/git-fsck.adoc\nindex 11203ba925c7..1751f692d42b 100644\n--- a/Documentation/git-fsck.adoc\n+++ b/Documentation/git-fsck.adoc\n@@ -31,7 +31,8 @@ index file, all SHA-1 references in the `refs` namespace, and all reflogs\n \tPrint out objects that exist but that aren't reachable from any\n \tof the reference nodes.\n \n---[no-]dangling::\n+--dangling::\n+--no-dangling::\n \tPrint objects that exist but that are never 'directly' used (default).\n \t`--no-dangling` can be used to omit this information from the output.\n \n@@ -97,14 +98,16 @@ care about this output and want to speed it up further.\n \tcompatible with linkgit:git-rev-parse[1], e.g.\n \t`HEAD@{1234567890}~25^2:src/`.\n \n---[no-]progress::\n+--progress::\n+--no-progress::\n \tProgress status is reported on the standard error stream by\n \tdefault when it is attached to a terminal, unless\n \t--no-progress or --verbose is specified. --progress forces\n \tprogress status even if the standard error stream is not\n \tdirected to a terminal.\n \n---[no-]references::\n+--references::\n+--no-references::\n \tControl whether to check the references database consistency\n \tvia 'git refs verify'. See linkgit:git-refs[1] for details.\n \tThe default is to check the references database.\ndiff --git a/Documentation/git-gc.adoc b/Documentation/git-gc.adoc\nindex 526ce01463d7..6fed646dd883 100644\n--- a/Documentation/git-gc.adoc\n+++ b/Documentation/git-gc.adoc\n@@ -53,11 +53,13 @@ configuration options such as `gc.auto` and `gc.autoPackLimit`, all\n other housekeeping tasks (e.g. rerere, working trees, reflog...) will\n be performed as well.\n \n---[no-]detach::\n+--detach::\n+--no-detach::\n \tRun in the background if the system supports it. This option overrides\n \tthe `gc.autoDetach` config.\n \n---[no-]cruft::\n+--cruft::\n+--no-cruft::\n \tWhen expiring unreachable objects, pack them separately into a\n \tcruft pack instead of storing them as loose objects. `--cruft`\n \tis on by default.\ndiff --git a/Documentation/git-index-pack.adoc b/Documentation/git-index-pack.adoc\nindex 270056cf6352..18036953c06b 100644\n--- a/Documentation/git-index-pack.adoc\n+++ b/Documentation/git-index-pack.adoc\n@@ -36,7 +36,8 @@ OPTIONS\n \tfails if the name of packed archive does not end\n \twith .pack).\n \n---[no-]rev-index::\n+--rev-index::\n+--no-rev-index::\n \tWhen this flag is provided, generate a reverse index\n \t(a `.rev` file) corresponding to the given pack. If\n \t`--verify` is given, ensure that the existing\ndiff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc\nindex b6f3d92c435f..e304739c5e80 100644\n--- a/Documentation/git-log.adoc\n+++ b/Documentation/git-log.adoc\n@@ -73,8 +73,10 @@ used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`,\n \tPrint out the ref name given on the command line by which each\n \tcommit was reached.\n \n-`--[no-]mailmap`::\n-`--[no-]use-mailmap`::\n+`--mailmap`::\n+`--no-mailmap`::\n+`--use-mailmap`::\n+`--no-use-mailmap`::\n \tUse mailmap file to map author and committer names and email\n \taddresses to canonical real names and email addresses. See\n \tlinkgit:git-shortlog[1].\ndiff --git a/Documentation/git-merge-tree.adoc b/Documentation/git-merge-tree.adoc\nindex f824eea61f1e..271ab220e8d7 100644\n--- a/Documentation/git-merge-tree.adoc\n+++ b/Documentation/git-merge-tree.adoc\n@@ -59,7 +59,8 @@ OPTIONS\n \tdo not list filenames multiple times if they have multiple\n \tconflicting stages).\n \n---[no-]messages::\n+--messages::\n+--no-messages::\n \tWrite any informational messages such as \"Auto-merging \"\n \tor CONFLICT notices to the end of stdout. If unspecified, the\n \tdefault is to include these messages if there are merge\ndiff --git a/Documentation/git-multi-pack-index.adoc b/Documentation/git-multi-pack-index.adoc\nindex b6cd0d7f855d..e8073bc27232 100644\n--- a/Documentation/git-multi-pack-index.adoc\n+++ b/Documentation/git-multi-pack-index.adoc\n@@ -25,7 +25,8 @@ OPTIONS\n +\n `` must be an alternate of the current repository.\n \n---[no-]progress::\n+--progress::\n+--no-progress::\n \tTurn progress on/off explicitly. If neither is specified, progress is\n \tshown if standard error is connected to a terminal. Supported by\n \tsub-commands `write`, `verify`, `expire`, and `repack.\ndiff --git a/Documentation/git-pack-objects.adoc b/Documentation/git-pack-objects.adoc\nindex eba014c40615..71b9682485c3 100644\n--- a/Documentation/git-pack-objects.adoc\n+++ b/Documentation/git-pack-objects.adoc\n@@ -243,7 +243,8 @@ depth is 4095.\n \tAdd --no-reuse-object if you want to force a uniform compression\n \tlevel on all data no matter the source.\n \n---[no-]sparse::\n+--sparse::\n+--no-sparse::\n \tToggle the \"sparse\" algorithm to determine which objects to include in\n \tthe pack, when combined with the \"--revs\" option. This algorithm\n \tonly walks trees that appear in paths that introduce new objects.\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 3f4ecc47301a..48e924a10a40 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -87,7 +87,8 @@ OPTIONS\n --verbose::\n \tPass --verbose to git-fetch and git-merge.\n \n---[no-]recurse-submodules[=(yes|on-demand|no)]::\n+--recurse-submodules[=(yes|on-demand|no)]::\n+--no-recurse-submodules::\n \tThis option controls if new commits of populated submodules should\n \tbe fetched, and if the working trees of active submodules should be\n \tupdated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and\ndiff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc\nindex d1978650d60a..5f5408e2c01d 100644\n--- a/Documentation/git-push.adoc\n+++ b/Documentation/git-push.adoc\n@@ -197,7 +197,8 @@ already exists on the remote side.\n \twith configuration variable `push.followTags`. For more\n \tinformation, see `push.followTags` in linkgit:git-config[1].\n \n---[no-]signed::\n+--signed::\n+--no-signed::\n --signed=(true|false|if-asked)::\n \tGPG-sign the push request to update refs on the receiving\n \tside, to allow it to be checked by the hooks and/or be\n@@ -208,7 +209,8 @@ already exists on the remote side.\n \twill also fail if the actual call to `gpg --sign` fails. See\n \tlinkgit:git-receive-pack[1] for the details on the receiving end.\n \n---[no-]atomic::\n+--atomic::\n+--no-atomic::\n \tUse an atomic transaction on the remote side if available.\n \tEither all refs are updated, or on error, no refs are updated.\n \tIf the server does not support atomic pushes the push will fail.\n@@ -232,7 +234,8 @@ already exists on the remote side.\n \trepository over ssh, and you do not have the program in\n \ta directory on the default $PATH.\n \n---[no-]force-with-lease::\n+--force-with-lease::\n+--no-force-with-lease::\n --force-with-lease=::\n --force-with-lease=:::\n \tUsually, \"git push\" refuses to update a remote ref that is\n@@ -350,7 +353,8 @@ one branch, use a `+` in front of the refspec to push (e.g `git push\n origin +master` to force a push to the `master` branch). See the\n `...` section above for details.\n \n---[no-]force-if-includes::\n+--force-if-includes::\n+--no-force-if-includes::\n \tForce an update only if the tip of the remote-tracking ref\n \thas been integrated locally.\n +\n@@ -377,7 +381,8 @@ Specifying `--no-force-if-includes` disables this behavior.\n \tlinkgit:git-pull[1] and other commands. For more information,\n \tsee `branch..merge` in linkgit:git-config[1].\n \n---[no-]thin::\n+--thin::\n+--no-thin::\n \tThese options are passed to linkgit:git-send-pack[1]. A thin transfer\n \tsignificantly reduces the amount of sent data when the sender and\n \treceiver share many of the same objects in common. The default is\n@@ -419,7 +424,8 @@ When using 'on-demand' or 'only', if a submodule has a\n \"push.recurseSubmodules={on-demand,only}\" or \"submodule.recurse\" configuration,\n further recursion will occur. In this case, \"only\" is treated as \"on-demand\".\n \n---[no-]verify::\n+--verify::\n+--no-verify::\n \tToggle the pre-push hook (see linkgit:githooks[5]). The\n \tdefault is --verify, giving the hook a chance to prevent the\n \tpush. With --no-verify, the hook is bypassed completely.\ndiff --git a/Documentation/git-range-diff.adoc b/Documentation/git-range-diff.adoc\nindex db0e4279b528..b5e85d37f1be 100644\n--- a/Documentation/git-range-diff.adoc\n+++ b/Documentation/git-range-diff.adoc\n@@ -96,7 +96,8 @@ diff.\n --remerge-diff::\n \tConvenience option, equivalent to `--diff-merges=remerge`.\n \n---[no-]notes[=]::\n+--notes[=]::\n+--no-notes::\n \tThis flag is passed to the `git log` program\n \t(see linkgit:git-log[1]) that generates the patches.\n \ndiff --git a/Documentation/git-read-tree.adoc b/Documentation/git-read-tree.adoc\nindex 1c48c2899630..1c04bba2b7b8 100644\n--- a/Documentation/git-read-tree.adoc\n+++ b/Documentation/git-read-tree.adoc\n@@ -100,7 +100,8 @@ OPTIONS\n \tdirectories the index file and index output file are\n \tlocated in.\n \n---[no-]recurse-submodules::\n+--recurse-submodules::\n+--no-recurse-submodules::\n \tUsing --recurse-submodules will update the content of all active\n \tsubmodules according to the commit recorded in the superproject by\n \tcalling read-tree recursively, also setting the submodules' HEAD to be\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 50e8a0ba6f66..3b9ba9aee952 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -90,7 +90,8 @@ but carries forward unmerged index entries.\n \tIf a file that is different between __ and `HEAD` has local\n \tchanges, reset is aborted.\n \n-`--[no-]recurse-submodules`::\n+`--recurse-submodules`::\n+`--no-recurse-submodules`::\n \tWhen the working tree is updated, using `--recurse-submodules` will\n \talso recursively reset the working tree of all active submodules\n \taccording to the commit recorded in the superproject, also setting\ndiff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc\nindex 5335502d68fc..11b1ab1a070a 100644\n--- a/Documentation/git-send-email.adoc\n+++ b/Documentation/git-send-email.adoc\n@@ -115,7 +115,8 @@ illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`:\n Only necessary if `--compose` is also set. If `--compose`\n is not set, this will be prompted for.\n \n---[no-]outlook-id-fix::\n+--outlook-id-fix::\n+--no-outlook-id-fix::\n \tMicrosoft Outlook SMTP servers discard the Message-ID sent via email and\n \tassign a new random Message-ID, thus breaking threads.\n +\n@@ -350,7 +351,8 @@ Automating\n --no-header-cmd::\n \tDisable any header command in use.\n \n---[no-]chain-reply-to::\n+--chain-reply-to::\n+--no-chain-reply-to::\n \tIf this is set, each email will be sent as a reply to the previous\n \temail sent. If disabled with `--no-chain-reply-to`, all emails after\n \tthe first will be sent as replies to the first email sent. When using\n@@ -364,19 +366,22 @@ Automating\n \tvalues in the `sendemail` section. The default identity is\n \tthe value of `sendemail.identity`.\n \n---[no-]signed-off-by-cc::\n+--signed-off-by-cc::\n+--no-signed-off-by-cc::\n \tIf this is set, add emails found in the `Signed-off-by` trailer or `Cc:`\n \tlines to the cc list. Default is the value of `sendemail.signedOffByCc`\n \tconfiguration value; if that is unspecified, default to\n \t`--signed-off-by-cc`.\n \n---[no-]cc-cover::\n+--cc-cover::\n+--no-cc-cover::\n \tIf this is set, emails found in `Cc:` headers in the first patch of\n \tthe series (typically the cover letter) are added to the cc list\n \tfor each email set. Default is the value of `sendemail.ccCover`\n \tconfiguration value; if that is unspecified, default to `--no-cc-cover`.\n \n---[no-]to-cover::\n+--to-cover::\n+--no-to-cover::\n \tIf this is set, emails found in `To:` headers in the first patch of\n \tthe series (typically the cover letter) are added to the to list\n \tfor each email set. Default is the value of `sendemail.toCover`\n@@ -407,12 +412,14 @@ Default is the value of `sendemail.suppressCc` configuration value; if\n that is unspecified, default to `self` if `--suppress-from` is\n specified, as well as `body` if `--no-signed-off-cc` is specified.\n \n---[no-]suppress-from::\n+--suppress-from::\n+--no-suppress-from::\n \tIf this is set, do not add the `From:` address to the `Cc:` list.\n \tDefault is the value of `sendemail.suppressFrom` configuration\n \tvalue; if that is unspecified, default to `--no-suppress-from`.\n \n---[no-]thread::\n+--thread::\n+--no-thread::\n \tIf this is set, the `In-Reply-To` and `References` headers will be\n \tadded to each email sent. Whether each mail refers to the\n \tprevious email (`deep` threading per `git format-patch`\n@@ -430,7 +437,8 @@ exists when `git send-email` is asked to add it (especially note that\n Failure to do so may not produce the expected result in the\n recipient's MUA.\n \n---[no-]mailmap::\n+--mailmap::\n+--no-mailmap::\n \tUse the mailmap file (see linkgit:gitmailmap[5]) to map all\n \taddresses to their canonical real name and email address. Additional\n \tmailmap data specific to `git send-email` may be provided using the\n@@ -459,7 +467,8 @@ have been specified, in which case default to `compose`.\n --dry-run::\n \tDo everything except actually send the emails.\n \n---[no-]format-patch::\n+--format-patch::\n+--no-format-patch::\n \tWhen an argument may be understood either as a reference or as a file name,\n \tchoose to understand it as a format-patch argument (`--format-patch`)\n \tor as a file name (`--no-format-patch`). By default, when such a conflict\n@@ -469,7 +478,8 @@ have been specified, in which case default to `compose`.\n \tMake `git send-email` less verbose. One line per email should be\n \tall that is output.\n \n---[no-]validate::\n+--validate::\n+--no-validate::\n \tPerform sanity checks on patches.\n \tCurrently, validation means the following:\n +\ndiff --git a/Documentation/git-send-pack.adoc b/Documentation/git-send-pack.adoc\nindex b9e73f2e77b1..811193f16c33 100644\n--- a/Documentation/git-send-pack.adoc\n+++ b/Documentation/git-send-pack.adoc\n@@ -71,7 +71,8 @@ be in a separate packet, and the list must end with a flush packet.\n \tfails to update then the entire push will fail without changing any\n \trefs.\n \n---[no-]signed::\n+--signed::\n+--no-signed::\n --signed=(true|false|if-asked)::\n \tGPG-sign the push request to update refs on the receiving\n \tside, to allow it to be checked by the hooks and/or be\ndiff --git a/Documentation/git-submodule.adoc b/Documentation/git-submodule.adoc\nindex 87d8e0f0c563..2d6ac92ea450 100644\n--- a/Documentation/git-submodule.adoc\n+++ b/Documentation/git-submodule.adoc\n@@ -435,7 +435,8 @@ options carefully.\n \tclone with a history truncated to the specified number of revisions.\n \tSee linkgit:git-clone[1]\n \n---[no-]recommend-shallow::\n+--recommend-shallow::\n+--no-recommend-shallow::\n \tThis option is only valid for the update command.\n \tThe initial clone of a submodule will use the recommended\n \t`submodule..shallow` as provided by the `.gitmodules` file\n@@ -447,7 +448,8 @@ options carefully.\n \tClone new submodules in parallel with as many jobs.\n \tDefaults to the `submodule.fetchJobs` option.\n \n---[no-]single-branch::\n+--single-branch::\n+--no-single-branch::\n \tThis option is only valid for the update command.\n \tClone only one branch during update: HEAD or one specified by --branch.\n \ndiff --git a/Documentation/git-update-index.adoc b/Documentation/git-update-index.adoc\nindex 7128aed54058..9bea9fab9ad1 100644\n--- a/Documentation/git-update-index.adoc\n+++ b/Documentation/git-update-index.adoc\n@@ -86,7 +86,8 @@ OPTIONS\n --chmod=(+|-)x::\n Set the execute permissions on the updated files.\n \n---[no-]assume-unchanged::\n+--assume-unchanged::\n+--no-assume-unchanged::\n \tWhen this flag is specified, the object names recorded\n \tfor the paths are not updated. Instead, this option\n \tsets/unsets the \"assume unchanged\" bit for the\n@@ -108,18 +109,21 @@ you will need to handle the situation manually.\n \tLike `--refresh`, but checks stat information unconditionally,\n \twithout regard to the \"assume unchanged\" setting.\n \n---[no-]skip-worktree::\n+--skip-worktree::\n+--no-skip-worktree::\n \tWhen one of these flags is specified, the object names recorded\n \tfor the paths are not updated. Instead, these options\n \tset and unset the \"skip-worktree\" bit for the paths. See\n \tsection \"Skip-worktree bit\" below for more information.\n \n \n---[no-]ignore-skip-worktree-entries::\n+--ignore-skip-worktree-entries::\n+--no-ignore-skip-worktree-entries::\n \tDo not remove skip-worktree (AKA \"index-only\") entries even when\n \tthe `--remove` option was specified.\n \n---[no-]fsmonitor-valid::\n+--fsmonitor-valid::\n+--no-fsmonitor-valid::\n \tWhen one of these flags is specified, the object names recorded\n \tfor the paths are not updated. Instead, these options\n \tset and unset the \"fsmonitor valid\" bit for the paths. See\ndiff --git a/Documentation/git-upload-pack.adoc b/Documentation/git-upload-pack.adoc\nindex 516d1639d9d0..9167a321d08e 100644\n--- a/Documentation/git-upload-pack.adoc\n+++ b/Documentation/git-upload-pack.adoc\n@@ -25,7 +25,8 @@ repository. For push operations, see 'git send-pack'.\n OPTIONS\n -------\n \n---[no-]strict::\n+--strict::\n+--no-strict::\n \tDo not try /.git/ if is not a Git directory.\n \n --timeout=::\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex 8340b7f028e6..389e669ac044 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -200,13 +200,15 @@ To remove a locked worktree, specify `--force` twice.\n \tWith `add`, detach `HEAD` in the new worktree. See \"DETACHED HEAD\"\n \tin linkgit:git-checkout[1].\n \n---[no-]checkout::\n+--checkout::\n+--no-checkout::\n \tBy default, `add` checks out ``, however, `--no-checkout` can\n \tbe used to suppress checkout in order to make customizations,\n \tsuch as configuring sparse-checkout. See \"Sparse checkout\"\n \tin linkgit:git-read-tree[1].\n \n---[no-]guess-remote::\n+--guess-remote::\n+--no-guess-remote::\n \tWith `worktree add `, without ``, instead\n \tof creating a new branch from `HEAD`, if there exists a tracking\n \tbranch in exactly one remote matching the basename of ``,\n@@ -216,7 +218,8 @@ To remove a locked worktree, specify `--force` twice.\n This can also be set up as the default behaviour by using the\n `worktree.guessRemote` config option.\n \n---[no-]relative-paths::\n+--relative-paths::\n+--no-relative-paths::\n \tLink worktrees using relative paths or absolute paths (default).\n \tOverrides the `worktree.useRelativePaths` config option, see\n \tlinkgit:git-config[1].\n@@ -224,7 +227,8 @@ This can also be set up as the default behaviour by using the\n With `repair`, the linking files will be updated if there's an absolute/relative\n mismatch, even if the links are correct.\n \n---[no-]track::\n+--track::\n+--no-track::\n \tWhen creating a new branch, if `` is a branch,\n \tmark it as \"upstream\" from the new branch. This is the\n \tdefault if `` is a remote-tracking branch. See\ndiff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl\nindex 1f35a6a116da..11321a151bca 100755\n--- a/Documentation/lint-documentation-style.perl\n+++ b/Documentation/lint-documentation-style.perl\n@@ -18,6 +18,9 @@ while (my $line = <>) {\n \n \t\treport($line, \"multiple parameters in a definition list item\");\n \t}\n+\tif ($line =~ /^`?--\\[no-\\][a-z0-9-]+.*(::|;;)$/) {\n+\t\treport($line, \"definition list item with a `--[no-]` parameter\");\n+\t}\n }\n \n \ndiff --git a/Documentation/merge-options.adoc b/Documentation/merge-options.adoc\nindex 95ef491be109..9d433265b298 100644\n--- a/Documentation/merge-options.adoc\n+++ b/Documentation/merge-options.adoc\n@@ -135,7 +135,8 @@ ifdef::git-pull[]\n Only useful when merging.\n endif::git-pull[]\n \n-`--[no-]verify`::\n+`--verify`::\n+`--no-verify`::\n \tBy default, the pre-merge and commit-msg hooks are run.\n \tWhen `--no-verify` is given, these are bypassed.\n \tSee also linkgit:githooks[5].\ndiff --git a/Documentation/scalar.adoc b/Documentation/scalar.adoc\nindex 4bd5b150e8e1..f81b2832f8df 100644\n--- a/Documentation/scalar.adoc\n+++ b/Documentation/scalar.adoc\n@@ -71,7 +71,8 @@ HEAD[:]`.\n \tInstead of checking out the branch pointed to by the cloned\n \trepository's HEAD, check out the `` branch instead.\n \n---[no-]single-branch::\n+--single-branch::\n+--no-single-branch::\n \tClone only the history leading to the tip of a single branch, either\n \tspecified by the `--branch` option or the primary branch remote's\n \t`HEAD` points at.\n@@ -81,23 +82,27 @@ remote-tracking branch for the branch this option was used for the initial\n cloning. If the HEAD at the remote did not point at any branch when\n `--single-branch` clone was made, no remote-tracking branch is created.\n \n---[no-]src::\n+--src::\n+--no-src::\n \tBy default, `scalar clone` places the cloned repository within a\n \t`/src` directory. Use `--no-src` to place the cloned\n \trepository directly in the `` directory.\n \n---[no-]tags::\n+--tags::\n+--no-tags::\n \tBy default, `scalar clone` will fetch the tag objects advertised by\n \tthe remote and future `git fetch` commands will do the same. Use\n \t`--no-tags` to avoid fetching tags in `scalar clone` and to configure\n \tthe repository to avoid fetching tags in the future. To fetch tags after\n \tcloning with `--no-tags`, run `git fetch --tags`.\n \n---[no-]full-clone::\n+--full-clone::\n+--no-full-clone::\n \tA sparse-checkout is initialized by default. This behavior can be\n \tturned off via `--full-clone`.\n \n---[no-]maintenance::\n+--maintenance::\n+--no-maintenance::\n \tBy default, `scalar clone` configures the enlistment to use Git's\n \tbackground maintenance feature. Use the `--no-maintenance` to skip\n \tthis configuration.\n@@ -122,7 +127,8 @@ Note: when this subcommand is called in a worktree that is called `src/`, its\n parent directory is considered to be the Scalar enlistment. If the worktree is\n _not_ called `src/`, it itself will be considered to be the Scalar enlistment.\n \n---[no-]maintenance::\n+--maintenance::\n+--no-maintenance::\n \tBy default, `scalar register` configures the enlistment to use Git's\n \tbackground maintenance feature. Use the `--no-maintenance` to skip\n \tthis configuration. This does not disable any maintenance that may\n-- \ngitgitgadget\n\n"},{"id":"523543","messageId":"713c86dae92bd54824cb90e359c025c6f4236c17.1754399033.git.gitgitgadget@gmail.com","threadId":"63916","inReplyTo":"pull.1945.git.1754399033.gitgitgadget@gmail.com","subject":"[PATCH 5/6] doc:git-for-each-ref: fix styling and typos","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-05T13:03:52Z","receivedAt":"2025-08-05T13:04:03Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nThis commit fixes the synopsis syntax and changes the wording of a few\ndescriptions to be more consistent with the rest of the documentation.\n\nIt is a prepartion for the next commit that checks that synopsis style is\napplied consistently across a manual page.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-for-each-ref.adoc | 264 ++++++++++++++--------------\n 1 file changed, 132 insertions(+), 132 deletions(-)\n\ndiff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc\nindex 060940904da2..b69080c4a000 100644\n--- a/Documentation/git-for-each-ref.adoc\n+++ b/Documentation/git-for-each-ref.adoc\n@@ -14,101 +14,98 @@ git for-each-ref [--count=] [--shell|--perl|--python|--tcl]\n \t\t [--merged[=]] [--no-merged[=]]\n \t\t [--contains[=]] [--no-contains[=]]\n \t\t [(--exclude=)...] [--start-after=]\n-\t\t [ --stdin | ... ]\n+\t\t [ --stdin | (...)]\n \n DESCRIPTION\n -----------\n \n-Iterate over all refs that match `` and show them\n-according to the given ``, after sorting them according\n-to the given set of ``. If `` is given, stop after\n-showing that many refs. The interpolated values in ``\n+Iterate over all refs that match __ and show them\n+according to the given __, after sorting them according\n+to the given set of __. If __ is given, stop after\n+showing that many refs. The interpolated values in __\n can optionally be quoted as string literals in the specified\n host language allowing their direct evaluation in that language.\n \n OPTIONS\n -------\n-...::\n-\tIf one or more patterns are given, only refs are shown that\n-\tmatch against at least one pattern, either using fnmatch(3) or\n+`...`::\n+\tIf one or more __ parameters are given, only refs are shown that\n+\tmatch against at least one pattern, either using `fnmatch`(3) or\n \tliterally, in the latter case matching completely or from the\n \tbeginning up to a slash.\n \n---stdin::\n-\tIf `--stdin` is supplied, then the list of patterns is read from\n-\tstandard input instead of from the argument list.\n+`--stdin`::\n+\tThe list of patterns is read from standard input instead of from\n+\tthe argument list.\n \n---count=::\n-\tBy default the command shows all refs that match\n-\t``. This option makes it stop after showing\n-\tthat many refs.\n+`--count=`::\n+\tStop after showing __ refs.\n \n---sort=::\n-\tA field name to sort on. Prefix `-` to sort in\n+`--sort=`::\n+\tSort on the field name __. Prefix `-` to sort in\n \tdescending order of the value. When unspecified,\n-\t`refname` is used. You may use the --sort= option\n+\t`refname` is used. You may use the `--sort=` option\n \tmultiple times, in which case the last key becomes the primary\n \tkey.\n \n---format=::\n+`--format[=]`::\n \tA string that interpolates `%(fieldname)` from a ref being shown and\n \tthe object it points at. In addition, the string literal `%%`\n \trenders as `%` and `%xx` - where `xx` are hex digits - renders as\n \tthe character with hex code `xx`. For example, `%00` interpolates to\n-\t`\\0` (NUL), `%09` to `\\t` (TAB), and `%0a` to `\\n` (LF).\n-+\n-When unspecified, `` defaults to `%(objectname) SPC %(objecttype)\n+\t`\\0` (_NUL_), `%09` to `\\t` (_TAB_), and `%0a` to `\\n` (_LF_).\n+\n+When unspecified, __ defaults to `%(objectname) SPC %(objecttype)\n TAB %(refname)`.\n \n---color[=]::\n+`--color[=]`::\n \tRespect any colors specified in the `--format` option. The\n-\t`` field must be one of `always`, `never`, or `auto` (if\n+\t_` is absent, behave as if `always` was given).\n \n---shell::\n---perl::\n---python::\n---tcl::\n+`--shell`::\n+`--perl`::\n+`--python`::\n+`--tcl`::\n \tIf given, strings that substitute `%(fieldname)`\n \tplaceholders are quoted as string literals suitable for\n \tthe specified host language. This is meant to produce\n-\ta scriptlet that can directly be `eval`ed.\n+\ta scriptlet that can directly be \"eval\"ed.\n \n---points-at=::\n+`--points-at=`::\n \tOnly list refs which points at the given object.\n \n---merged[=]::\n+`--merged[=]`::\n \tOnly list refs whose tips are reachable from the\n-\tspecified commit (HEAD if not specified).\n-\n---no-merged[=]::\n-\tOnly list refs whose tips are not reachable from the\n-\tspecified commit (HEAD if not specified).\n+\tspecified commit (`HEAD` if not specified).\n \n---contains[=]::\n-\tOnly list refs which contain the specified commit (HEAD if not\n+`--no-merged[=]`::\n+\tOnly list refs whose tips are not reachable from __(`HEAD` if not\n \tspecified).\n \n---no-contains[=]::\n-\tOnly list refs which don't contain the specified commit (HEAD\n+`--contains[=]`::\n+\tOnly list refs which contain __(`HEAD` if not specified).\n+\n+`--no-contains[=]`::\n+\tOnly list refs which don't contain __ (`HEAD`\n \tif not specified).\n \n---ignore-case::\n+`--ignore-case`::\n \tSorting and filtering refs are case insensitive.\n \n---omit-empty::\n+`--omit-empty`::\n \tDo not print a newline after formatted refs where the format expands\n \tto the empty string.\n \n---exclude=::\n-\tIf one or more patterns are given, only refs which do not match\n-\tany excluded pattern(s) are shown. Matching is done using the\n-\tsame rules as `` above.\n+`--exclude=`::\n+\tIf one or more `--exclude` options are given, only refs which do not\n+\tmatch any __ parameters are shown. Matching is done\n+\tusing the same rules as __ above.\n \n---include-root-refs::\n-\tList root refs (HEAD and pseudorefs) apart from regular refs.\n+`--include-root-refs`::\n+\tList root refs (`HEAD` and pseudorefs) apart from regular refs.\n \n---start-after=::\n+`--start-after=`::\n Allows paginating the output by skipping references up to and including the\n specified marker. When paging, it should be noted that references may be\n deleted, modified or added between invocations. Output will only yield those\n@@ -126,44 +123,44 @@ keys.\n \n For all objects, the following names can be used:\n \n-refname::\n-\tThe name of the ref (the part after $GIT_DIR/).\n+`refname`::\n+\tThe name of the ref (the part after `$GIT_DIR/`).\n \tFor a non-ambiguous short name of the ref append `:short`.\n-\tThe option core.warnAmbiguousRefs is used to select the strict\n-\tabbreviation mode. If `lstrip=` (`rstrip=`) is appended, strips ``\n+\tThe option `core.warnAmbiguousRefs` is used to select the strict\n+\tabbreviation mode. If `lstrip=` (`rstrip=`) is appended, strip __\n \tslash-separated path components from the front (back) of the refname\n \t(e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and\n \t`%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`).\n-\tIf `` is a negative number, strip as many path components as\n-\tnecessary from the specified end to leave `-` path components\n+\tIf __ is a negative number, strip as many path components as\n+\tnecessary from the specified end to leave `-` path components\n \t(e.g. `%(refname:lstrip=-2)` turns\n \t`refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)`\n \tturns `refs/tags/foo` into `refs`). When the ref does not have\n \tenough components, the result becomes an empty string if\n-\tstripping with positive , or it becomes the full refname if\n-\tstripping with negative . Neither is an error.\n+\tstripping with positive __, or it becomes the full refname if\n+\tstripping with negative __. Neither is an error.\n +\n `strip` can be used as a synonym to `lstrip`.\n \n-objecttype::\n+`objecttype`::\n \tThe type of the object (`blob`, `tree`, `commit`, `tag`).\n \n-objectsize::\n+`objectsize`::\n \tThe size of the object (the same as 'git cat-file -s' reports).\n \tAppend `:disk` to get the size, in bytes, that the object takes up on\n-\tdisk. See the note about on-disk sizes in the `CAVEATS` section below.\n-objectname::\n+\tdisk. See the note about on-disk sizes in the 'CAVEATS' section below.\n+`objectname`::\n \tThe object name (aka SHA-1).\n \tFor a non-ambiguous abbreviation of the object name append `:short`.\n \tFor an abbreviation of the object name with desired length append\n-\t`:short=`, where the minimum length is MINIMUM_ABBREV. The\n+\t`:short=`, where the minimum length is `MINIMUM_ABBREV`. The\n \tlength may be exceeded to ensure unique object names.\n-deltabase::\n+`deltabase`::\n \tThis expands to the object name of the delta base for the\n \tgiven object, if it is stored as a delta. Otherwise it\n \texpands to the null object name (all zeroes).\n \n-upstream::\n+`upstream`::\n \tThe name of a local ref which can be considered ``upstream''\n \tfrom the displayed ref. Respects `:short`, `:lstrip` and\n \t`:rstrip` in the same way as `refname` above. Additionally\n@@ -185,100 +182,103 @@ Has no effect if the ref does not have tracking information associated\n with it. All the options apart from `nobracket` are mutually exclusive,\n but if used together the last option is selected.\n \n-push::\n+`push`::\n \tThe name of a local ref which represents the `@{push}`\n \tlocation for the displayed ref. Respects `:short`, `:lstrip`,\n \t`:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref`\n \toptions as `upstream` does. Produces an empty string if no `@{push}`\n \tref is configured.\n \n-HEAD::\n-\t'*' if HEAD matches current ref (the checked out branch), ' '\n+`HEAD`::\n+\t`*` if `HEAD` matches current ref (the checked out branch), ' '\n \totherwise.\n \n-color::\n+`color`::\n \tChange output color. Followed by `:`, where color\n \tnames are described under Values in the \"CONFIGURATION FILE\"\n \tsection of linkgit:git-config[1]. For example,\n \t`%(color:bold red)`.\n \n-align::\n+`align`::\n \tLeft-, middle-, or right-align the content between\n-\t%(align:...) and %(end). The \"align:\" is followed by\n+\t`%(align:...)` and `%(end)`. The \"`align:`\" is followed by\n \t`width=` and `position=` in any order\n-\tseparated by a comma, where the `` is either left,\n-\tright or middle, default being left and `` is the total\n+\tseparated by a comma, where the __ is either `left`,\n+\t`right` or `middle`, default being `left` and __ is the total\n \tlength of the content with alignment. For brevity, the\n \t\"width=\" and/or \"position=\" prefixes may be omitted, and bare\n-\t and used instead. For instance,\n+\t__ and __ used instead. For instance,\n \t`%(align:,)`. If the contents length is more\n \tthan the width then no alignment is performed. If used with\n-\t`--quote` everything in between %(align:...) and %(end) is\n+\t`--quote` everything in between `%(align:...)` and `%(end)` is\n \tquoted, but if nested then only the topmost level performs\n \tquoting.\n \n-if::\n-\tUsed as %(if)...%(then)...%(end) or\n-\t%(if)...%(then)...%(else)...%(end). If there is an atom with\n-\tvalue or string literal after the %(if) then everything after\n-\tthe %(then) is printed, else if the %(else) atom is used, then\n+`if`::\n+\tUsed as `%(if)...%(then)...%(end)` or\n+\t`%(if)...%(then)...%(else)...%(end)`. If there is an atom with\n+\tvalue or string literal after the `%(if)` then everything after\n+\tthe `%(then)` is printed, else if the `%(else)` atom is used, then\n \teverything after %(else) is printed. We ignore space when\n-\tevaluating the string before %(then), this is useful when we\n-\tuse the %(HEAD) atom which prints either \"*\" or \" \" and we\n-\twant to apply the 'if' condition only on the 'HEAD' ref.\n-\tAppend \":equals=\" or \":notequals=\" to compare\n-\tthe value between the %(if:...) and %(then) atoms with the\n+\tevaluating the string before `%(then)`, this is useful when we\n+\tuse the `%(HEAD)` atom which prints either \"`*`\" or \" \" and we\n+\twant to apply the 'if' condition only on the `HEAD` ref.\n+\tAppend \"`:equals=`\" or \"`:notequals=`\" to compare\n+\tthe value between the `%(if:...)` and `%(then)` atoms with the\n \tgiven string.\n \n-symref::\n+`symref`::\n \tThe ref which the given symbolic ref refers to. If not a\n \tsymbolic ref, nothing is printed. Respects the `:short`,\n \t`:lstrip` and `:rstrip` options in the same way as `refname`\n \tabove.\n \n-signature::\n+`signature`::\n \tThe GPG signature of a commit.\n \n-signature:grade::\n-\tShow \"G\" for a good (valid) signature, \"B\" for a bad\n-\tsignature, \"U\" for a good signature with unknown validity, \"X\"\n-\tfor a good signature that has expired, \"Y\" for a good\n-\tsignature made by an expired key, \"R\" for a good signature\n-\tmade by a revoked key, \"E\" if the signature cannot be\n-\tchecked (e.g. missing key) and \"N\" for no signature.\n-\n-signature:signer::\n+`signature:grade`::\n+\tShow\n+`G`;; for a good (valid) signature\n+`B`;; for a bad signature\n+`U`;; for a good signature with unknown validity\n+`X`;;\tfor a good signature that has expired\n+`Y`;; for a good signature made by an expired key\n+`R`;; for a good signature made by a revoked key\n+`E`;; if the signature cannot be checked (e.g. missing key)\n+`N`;; for no signature.\n+\n+`signature:signer`::\n \tThe signer of the GPG signature of a commit.\n \n-signature:key::\n+`signature:key`::\n \tThe key of the GPG signature of a commit.\n \n-signature:fingerprint::\n+`signature:fingerprint`::\n \tThe fingerprint of the GPG signature of a commit.\n \n-signature:primarykeyfingerprint::\n+`signature:primarykeyfingerprint`::\n \tThe primary key fingerprint of the GPG signature of a commit.\n \n-signature:trustlevel::\n+`signature:trustlevel`::\n \tThe trust level of the GPG signature of a commit. Possible\n \toutputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`.\n \n-worktreepath::\n+`worktreepath`::\n \tThe absolute path to the worktree in which the ref is checked\n \tout, if it is checked out in any linked worktree. Empty string\n \totherwise.\n \n-ahead-behind:::\n+`ahead-behind:`::\n \tTwo integers, separated by a space, demonstrating the number of\n \tcommits ahead and behind, respectively, when comparing the output\n-\tref to the `` specified in the format.\n+\tref to the __ specified in the format.\n \n-is-base:::\n-\tIn at most one row, `()` will appear to indicate the ref\n+`is-base:`::\n+\tIn at most one row, `()` will appear to indicate the ref\n \tthat is most likely the ref used as a starting point for the branch\n-\tthat produced ``. This choice is made using a heuristic:\n+\tthat produced __. This choice is made using a heuristic:\n \tchoose the ref that minimizes the number of commits in the\n-\tfirst-parent history of `` and not in the first-parent\n+\tfirst-parent history of __ and not in the first-parent\n \thistory of the ref.\n +\n For example, consider the following figure of first-parent histories of\n@@ -312,29 +312,29 @@ common first-parent ancestor of `B` and `C` and ties are broken by the\n earliest ref in the sorted order.\n +\n Note that this token will not appear if the first-parent history of\n-`` does not intersect the first-parent histories of the\n+__ does not intersect the first-parent histories of the\n filtered refs.\n \n-describe[:options]::\n+`describe[: