* [PATCH 0/6] Introduce more doc linting
@ 2025-08-05 13:03 Jean-Noël Avila via GitGitGadget
2025-08-05 13:03 ` [PATCH 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget
` (7 more replies)
0 siblings, 8 replies; 28+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 UTC (permalink / raw)
To: git; +Cc: Jean-Noël Avila
Reviewing the documentation part of the last patches, it turns out that the
majority of my comments are related to the latest documentation guidelines
which are both easy to forget and almost trivial to automatically check.
This series implements the automatic tests for basic doc rules. At the
moment it conflicts with "[GSoC][PATCH v6 0/6] Add refs list subcommand" and
possibly with "[PATCH v4 0/9] refs: fix migration of reflog entries"
Jean-Noël Avila (6):
doc: test linkgit macros for well-formedness
doc: check well-formedness of delimited sections
doc: check for absence of multiple terms in each entry of desc list
doc: check for absence of the form --[no-]parameter
doc:git-for-each-ref: fix styling and typos
doc lint: check that synopsis manpages have synopsis inlines
Documentation/Makefile | 21 +-
Documentation/RelNotes/1.6.2.4.adoc | 1 +
Documentation/blame-options.adoc | 3 +-
Documentation/diff-format.adoc | 1 +
Documentation/diff-options.adoc | 3 +-
Documentation/fetch-options.adoc | 15 +-
Documentation/git-am.adoc | 3 +-
Documentation/git-backfill.adoc | 3 +-
Documentation/git-cat-file.adoc | 6 +-
Documentation/git-check-attr.adoc | 3 +-
Documentation/git-check-ignore.adoc | 9 +-
Documentation/git-check-ref-format.adoc | 3 +-
Documentation/git-clone.adoc | 12 +-
Documentation/git-commit-graph.adoc | 3 +-
Documentation/git-commit.adoc | 4 +-
Documentation/git-config.adoc | 3 +-
Documentation/git-difftool.adoc | 9 +-
Documentation/git-fast-import.adoc | 5 +-
Documentation/git-fmt-merge-msg.adoc | 3 +-
Documentation/git-for-each-ref.adoc | 264 +++++++++---------
Documentation/git-format-patch.adoc | 12 +-
Documentation/git-fsck.adoc | 9 +-
Documentation/git-gc.adoc | 6 +-
Documentation/git-http-fetch.adoc | 4 +-
Documentation/git-index-pack.adoc | 3 +-
Documentation/git-log.adoc | 6 +-
Documentation/git-merge-tree.adoc | 3 +-
Documentation/git-multi-pack-index.adoc | 3 +-
Documentation/git-p4.adoc | 1 +
Documentation/git-pack-objects.adoc | 3 +-
Documentation/git-pull.adoc | 3 +-
Documentation/git-push.adoc | 18 +-
Documentation/git-range-diff.adoc | 3 +-
Documentation/git-read-tree.adoc | 3 +-
Documentation/git-rebase.adoc | 2 +-
Documentation/git-refs.adoc | 20 +-
Documentation/git-reset.adoc | 3 +-
Documentation/git-send-email.adoc | 30 +-
Documentation/git-send-pack.adoc | 3 +-
Documentation/git-submodule.adoc | 6 +-
Documentation/git-svn.adoc | 2 +
Documentation/git-update-index.adoc | 12 +-
Documentation/git-upload-pack.adoc | 3 +-
Documentation/git-worktree.adoc | 12 +-
Documentation/gitprotocol-http.adoc | 2 +-
Documentation/gitsubmodules.adoc | 3 +-
Documentation/gitweb.conf.adoc | 2 +-
Documentation/lint-delimited-sections.perl | 48 ++++
Documentation/lint-documentation-style.perl | 33 +++
Documentation/lint-gitlink.perl | 7 +
Documentation/merge-options.adoc | 3 +-
Documentation/mergetools/vimdiff.adoc | 8 +
Documentation/scalar.adoc | 18 +-
Documentation/technical/api-path-walk.adoc | 5 +-
.../long-running-process-protocol.adoc | 1 +
shared.mak | 2 +
56 files changed, 445 insertions(+), 231 deletions(-)
create mode 100755 Documentation/lint-delimited-sections.perl
create mode 100755 Documentation/lint-documentation-style.perl
base-commit: 112648dd6bdd8e4f485cd0ae11636807959d48be
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1945%2Fjnavila%2Fdoc_linting-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1945/jnavila/doc_linting-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1945
--
gitgitgadget
^ permalink raw reply [flat|nested] 28+ messages in thread* [PATCH 1/6] doc: test linkgit macros for well-formedness 2025-08-05 13:03 [PATCH 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 ` Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 2/6] doc: check well-formedness of delimited sections Jean-Noël Avila via GitGitGadget ` (6 subsequent siblings) 7 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> Some readers of man pages have reported that they found malformed linkgit macros in the documentation (absence or bad spelling). Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/gitweb.conf.adoc | 2 +- Documentation/lint-gitlink.perl | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/Documentation/gitweb.conf.adoc b/Documentation/gitweb.conf.adoc index 1348e9b12504..64bebb811c97 100644 --- a/Documentation/gitweb.conf.adoc +++ b/Documentation/gitweb.conf.adoc @@ -178,7 +178,7 @@ $export_ok:: Show repository only if this file exists (in repository). Only effective if this variable evaluates to true. Can be set when building gitweb by setting `GITWEB_EXPORT_OK`. This path is - relative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok', + relative to `GIT_DIR`. linkgit:git-daemon[1] uses 'git-daemon-export-ok', unless started with `--export-all`. By default this variable is not set, which means that this feature is turned off. diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl index aea564dad7ed..f183a18df284 100755 --- a/Documentation/lint-gitlink.perl +++ b/Documentation/lint-gitlink.perl @@ -41,6 +41,13 @@ die "BUG: No list of valid linkgit:* files given" unless @ARGV; @ARGV = $to_check; while (<>) { my $line = $_; + while ($line =~ m/(.{,8})((git[-a-z]+|scalar)\[(\d)*\])/g) { + my $pos = pos $line; + my ($macro, $target, $page, $section) = ($1, $2, $3, $4); + if ( $macro ne "linkgit:" && $macro !~ "ifn?def::" && $macro ne "endif::" ) { + report($pos, $line, $target, "linkgit: macro expected"); + } + } while ($line =~ m/linkgit:((.*?)\[(\d)\])/g) { my $pos = pos $line; my ($target, $page, $section) = ($1, $2, $3); -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 2/6] doc: check well-formedness of delimited sections 2025-08-05 13:03 [PATCH 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 ` Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 3/6] doc: check for absence of multiple terms in each entry of desc list Jean-Noël Avila via GitGitGadget ` (5 subsequent siblings) 7 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> Having an empty line before each delimited sections is not required by asciidoc, but it is a safety measure that prevents generating malformed asciidoc when generating translated documentation. When a delimited section appears just after a paragraph, the asciidoc processor checks that the length of the delimited section header is different from the length of the paragraph. If it is not, the asciidoc processor will generate a title. In the original English documentation, this is not a problem because the authors always check the output of the asciidoc processor and fix the length of the delimited section header if it turns out to be the same as the paragraph length. However, this is not the case for translations, where the authors have no way to check the length of the delimited section header or the output of the asciidoc processor. This can lead to a section title that is not intended. Indeed, this test also checks that titles are correctly formed, that is, the length of the underline is equal to the length of the title (otherwise it would not be a title but a section header). Finally, this test checks that the delimited section are terminated within the same file. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/Makefile | 11 ++++- Documentation/RelNotes/1.6.2.4.adoc | 1 + Documentation/diff-format.adoc | 1 + Documentation/git-commit.adoc | 1 + Documentation/git-fast-import.adoc | 2 + Documentation/git-p4.adoc | 1 + Documentation/git-rebase.adoc | 2 +- Documentation/git-svn.adoc | 2 + Documentation/gitprotocol-http.adoc | 2 +- Documentation/gitsubmodules.adoc | 3 +- Documentation/lint-delimited-sections.perl | 48 +++++++++++++++++++ Documentation/mergetools/vimdiff.adoc | 8 ++++ .../long-running-process-protocol.adoc | 1 + shared.mak | 1 + 14 files changed, 80 insertions(+), 4 deletions(-) create mode 100755 Documentation/lint-delimited-sections.perl diff --git a/Documentation/Makefile b/Documentation/Makefile index df2ce187eb84..76a9e1d02b26 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -497,9 +497,17 @@ $(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.adoc $(call mkdir_p_parent_template) $(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \ ../fsck.h fsck-msgids.adoc $@ - lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) +## Lint: delimited sections +LINT_DOCS_DELIMITED_SECTIONS = $(patsubst %.adoc,.build/lint-docs/delimited-sections/%.ok,$(MAN_TXT)) +$(LINT_DOCS_DELIMITED_SECTIONS): lint-delimited-sections.perl +$(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.adoc + $(call mkdir_p_parent_template) + $(QUIET_LINT_DELIMSEC)$(PERL_PATH) lint-delimited-sections.perl $< >$@ +.PHONY: lint-docs-delimited-sections +lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) + lint-docs-manpages: $(QUIET_GEN)./lint-manpages.sh @@ -528,6 +536,7 @@ lint-docs: lint-docs-fsck-msgids lint-docs: lint-docs-gitlink lint-docs: lint-docs-man-end-blurb lint-docs: lint-docs-man-section-order +lint-docs: lint-docs-delimited-sections lint-docs: lint-docs-manpages lint-docs: lint-docs-meson diff --git a/Documentation/RelNotes/1.6.2.4.adoc b/Documentation/RelNotes/1.6.2.4.adoc index f4bf1d09863c..053dbb604de6 100644 --- a/Documentation/RelNotes/1.6.2.4.adoc +++ b/Documentation/RelNotes/1.6.2.4.adoc @@ -37,3 +37,4 @@ exec >/var/tmp/1 echo O=$(git describe maint) O=v1.6.2.3-38-g318b847 git shortlog --no-merges $O..maint +--- diff --git a/Documentation/diff-format.adoc b/Documentation/diff-format.adoc index 80e36e153dac..9f7e98824183 100644 --- a/Documentation/diff-format.adoc +++ b/Documentation/diff-format.adoc @@ -103,6 +103,7 @@ if the file was renamed on any side of history. With followed by the name of the path in the merge commit. Examples for `-c` and `--cc` without `--combined-all-paths`: + ------------------------------------------------ ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM desc.c ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM bar.sh diff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc index ae988a883b5b..d4d576ce665f 100644 --- a/Documentation/git-commit.adoc +++ b/Documentation/git-commit.adoc @@ -281,6 +281,7 @@ variable (see linkgit:git-config[1]). + -- It is a rough equivalent for: + ------ $ git reset --soft HEAD^ $ ... do something else to come up with the right tree ... diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index 6f9763c11b3c..6490d67fab56 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -605,9 +605,11 @@ Marks must be declared (via `mark`) before they can be used. The special case of restarting an incremental import from the current branch value should be written as: + ---- from refs/heads/branch^0 ---- + The `^0` suffix is necessary as fast-import does not permit a branch to start from itself, and the branch is created in memory before the `from` command is even read from the input. Adding `^0` will force diff --git a/Documentation/git-p4.adoc b/Documentation/git-p4.adoc index f97b786bf98a..59edd241341e 100644 --- a/Documentation/git-p4.adoc +++ b/Documentation/git-p4.adoc @@ -66,6 +66,7 @@ Clone ~~~~~ Generally, 'git p4 clone' is used to create a new Git directory from an existing p4 repository: + ------------ $ git p4 clone //depot/path/project ------------ diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index 956d3048f5a6..727160c6db77 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -687,7 +687,7 @@ In addition, the following pairs of options are incompatible: * --fork-point and --root BEHAVIORAL DIFFERENCES ------------------------ +---------------------- `git rebase` has two primary backends: 'apply' and 'merge'. (The 'apply' backend used to be known as the 'am' backend, but the name led to diff --git a/Documentation/git-svn.adoc b/Documentation/git-svn.adoc index bcf7d84a87d1..c26c12bab37a 100644 --- a/Documentation/git-svn.adoc +++ b/Documentation/git-svn.adoc @@ -1012,9 +1012,11 @@ branch. If you do merge, note the following rule: 'git svn dcommit' will attempt to commit on top of the SVN commit named in + ------------------------------------------------------------------------ git log --grep=^git-svn-id: --first-parent -1 ------------------------------------------------------------------------ + You 'must' therefore ensure that the most recent commit of the branch you want to dcommit to is the 'first' parent of the merge. Chaos will ensue otherwise, especially if the first parent is an older commit on diff --git a/Documentation/gitprotocol-http.adoc b/Documentation/gitprotocol-http.adoc index ec40a550ccab..d024010414aa 100644 --- a/Documentation/gitprotocol-http.adoc +++ b/Documentation/gitprotocol-http.adoc @@ -318,7 +318,7 @@ Extra Parameter. Smart Service git-upload-pack ------------------------------- +----------------------------- This service reads from the repository pointed to by `$GIT_URL`. Clients MUST first perform ref discovery with diff --git a/Documentation/gitsubmodules.adoc b/Documentation/gitsubmodules.adoc index f7b5a25a0caa..20822961999a 100644 --- a/Documentation/gitsubmodules.adoc +++ b/Documentation/gitsubmodules.adoc @@ -8,6 +8,7 @@ gitsubmodules - Mounting one repository inside another SYNOPSIS -------- .gitmodules, $GIT_DIR/config + ------------------ git submodule git <command> --recurse-submodules @@ -240,7 +241,7 @@ Workflow for a third party library Workflow for an artificially split repo --------------------------------------- +--------------------------------------- # Enable recursion for relevant commands, such that # regular commands recurse into submodules by default diff --git a/Documentation/lint-delimited-sections.perl b/Documentation/lint-delimited-sections.perl new file mode 100755 index 000000000000..140b852e5d46 --- /dev/null +++ b/Documentation/lint-delimited-sections.perl @@ -0,0 +1,48 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +my $exit_code = 0; +sub report { + my ($msg) = @_; + print STDERR "$ARGV:$.: $msg\n"; + $exit_code = 1; +} + +my $line_length = 0; +my $in_section = 0; +my $section_header = ""; + + +while (my $line = <>) { + if (($line =~ /^\+?$/) || + ($line =~ /^\[.*\]$/) || + ($line =~ /^ifdef::/)) { + $line_length = 0; + } elsif ($line =~ /^[^-.]/) { + $line_length = length($line); + } elsif (($line =~ /^-{3,}$/) || ($line =~ /^\.{3,}$/)) { + if ($in_section) { + if ($line eq $section_header) { + $in_section = 0; + } + next; + } + if ($line_length == 0) { + $in_section = 1; + $section_header = $line; + next; + } + if (($line_length != 0) && (length($line) != $line_length)) { + report("section delimiter not preceded by an empty line"); + } + $line_length = 0; + } +} + +if ($in_section) { + report("section not finished"); +} + +exit $exit_code; diff --git a/Documentation/mergetools/vimdiff.adoc b/Documentation/mergetools/vimdiff.adoc index abfd426f74a0..b4ab83a510e0 100644 --- a/Documentation/mergetools/vimdiff.adoc +++ b/Documentation/mergetools/vimdiff.adoc @@ -3,6 +3,7 @@ Description When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4 windows layout distributed in the following way: + .... ------------------------------------------ | | | | @@ -56,6 +57,7 @@ needed in this case. The next layout definition is equivalent: + -- If, for some reason, we are not interested in the `BASE` buffer. + .... ------------------------------------------ | | | | @@ -72,6 +74,7 @@ If, for some reason, we are not interested in the `BASE` buffer. Only the `MERGED` buffer will be shown. Note, however, that all the other ones are still loaded in vim, and you can access them with the "buffers" command. + .... ------------------------------------------ | | @@ -88,6 +91,7 @@ command. When `MERGED` is not present in the layout, you must "mark" one of the buffers with an arobase (`@`). That will become the buffer you need to edit and save after resolving the conflicts. + .... ------------------------------------------ | | | @@ -106,6 +110,7 @@ save after resolving the conflicts. Three tabs will open: the first one is a copy of the default layout, while the other two only show the differences between (`BASE` and `LOCAL`) and (`BASE` and `REMOTE`) respectively. + .... ------------------------------------------ | <TAB #1> | TAB #2 | TAB #3 | | @@ -119,6 +124,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and | | ------------------------------------------ .... + .... ------------------------------------------ | TAB #1 | <TAB #2> | TAB #3 | | @@ -132,6 +138,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and | | | ------------------------------------------ .... + .... ------------------------------------------ | TAB #1 | TAB #2 | <TAB #3> | | @@ -151,6 +158,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and -- Same as the previous example, but adds a fourth tab with the same information as the first tab, with a different layout. + .... --------------------------------------------- | TAB #1 | TAB #2 | TAB #3 | <TAB #4> | diff --git a/Documentation/technical/long-running-process-protocol.adoc b/Documentation/technical/long-running-process-protocol.adoc index 6f33654b4288..39bd89d467d6 100644 --- a/Documentation/technical/long-running-process-protocol.adoc +++ b/Documentation/technical/long-running-process-protocol.adoc @@ -24,6 +24,7 @@ After the version negotiation Git sends a list of all capabilities that it supports and a flush packet. Git expects to read a list of desired capabilities, which must be a subset of the supported capabilities list, and a flush packet as response: + ------------------------ packet: git> git-filter-client packet: git> version=2 diff --git a/shared.mak b/shared.mak index 1a99848a9517..57095d6cf96c 100644 --- a/shared.mak +++ b/shared.mak @@ -88,6 +88,7 @@ ifndef V QUIET_LINT_GITLINK = @echo ' ' LINT GITLINK $<; QUIET_LINT_MANSEC = @echo ' ' LINT MAN SEC $<; + QUIET_LINT_DELIMSEC = @echo ' ' LINT DEL SEC $<; QUIET_LINT_MANEND = @echo ' ' LINT MAN END $<; export V -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 3/6] doc: check for absence of multiple terms in each entry of desc list 2025-08-05 13:03 [PATCH 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 2/6] doc: check well-formedness of delimited sections Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 ` Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 4/6] doc: check for absence of the form --[no-]parameter Jean-Noël Avila via GitGitGadget ` (4 subsequent siblings) 7 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> Due to portability issues, the script generate-configlist.sh was fixed to not use carriage returns in the output. However, the result is that it no longer correctly handles multiple terms in a single entry of the definition list. We now check that these entries do not exist in the documentation. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/Makefile | 10 +++++++++ Documentation/git-check-attr.adoc | 3 ++- Documentation/git-check-ignore.adoc | 9 +++++--- Documentation/git-http-fetch.adoc | 4 +++- Documentation/lint-documentation-style.perl | 24 +++++++++++++++++++++ Documentation/technical/api-path-walk.adoc | 5 ++++- shared.mak | 1 + 7 files changed, 50 insertions(+), 6 deletions(-) create mode 100755 Documentation/lint-documentation-style.perl diff --git a/Documentation/Makefile b/Documentation/Makefile index 76a9e1d02b26..ac8a21e3015c 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -508,6 +508,15 @@ $(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.ado .PHONY: lint-docs-delimited-sections lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) +## Lint: Documentation style +LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(MAN_TXT)) +$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl +$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc + $(call mkdir_p_parent_template) + $(QUIET_LINT_DOCSTYLE)$(PERL_PATH) lint-documentation-style.perl $< >$@ +.PHONY: lint-docs-doc-style +lint-docs-doc-style: $(LINT_DOCS_DOC_STYLE) + lint-docs-manpages: $(QUIET_GEN)./lint-manpages.sh @@ -537,6 +546,7 @@ lint-docs: lint-docs-gitlink lint-docs: lint-docs-man-end-blurb lint-docs: lint-docs-man-section-order lint-docs: lint-docs-delimited-sections +lint-docs: lint-docs-doc-style lint-docs: lint-docs-manpages lint-docs: lint-docs-meson diff --git a/Documentation/git-check-attr.adoc b/Documentation/git-check-attr.adoc index 503b6446574d..15a37a38e3f7 100644 --- a/Documentation/git-check-attr.adoc +++ b/Documentation/git-check-attr.adoc @@ -19,7 +19,8 @@ For every pathname, this command will list if each attribute is 'unspecified', OPTIONS ------- --a, --all:: +-a:: +--all:: List all attributes that are associated with the specified paths. If this option is used, then 'unspecified' attributes will not be included in the output. diff --git a/Documentation/git-check-ignore.adoc b/Documentation/git-check-ignore.adoc index 3e3b4e344629..a6c6c1b6e5be 100644 --- a/Documentation/git-check-ignore.adoc +++ b/Documentation/git-check-ignore.adoc @@ -25,11 +25,13 @@ subject to exclude rules; but see `--no-index'. OPTIONS ------- --q, --quiet:: +-q:: +--quiet:: Don't output anything, just set exit status. This is only valid with a single pathname. --v, --verbose:: +-v:: +--verbose:: Instead of printing the paths that are excluded, for each path that matches an exclude pattern, print the exclude pattern together with the path. (Matching an exclude pattern usually @@ -49,7 +51,8 @@ linkgit:gitignore[5]. below). If `--stdin` is also given, input paths are separated with a NUL character instead of a linefeed character. --n, --non-matching:: +-n:: +--non-matching:: Show given paths which don't match any pattern. This only makes sense when `--verbose` is enabled, otherwise it would not be possible to distinguish between paths which match a diff --git a/Documentation/git-http-fetch.adoc b/Documentation/git-http-fetch.adoc index 4ec7c68d3b9e..dcb05890aefd 100644 --- a/Documentation/git-http-fetch.adoc +++ b/Documentation/git-http-fetch.adoc @@ -25,8 +25,10 @@ commit-id:: Either the hash or the filename under [URL]/refs/ to pull. --a, -c, -t:: +-a::-c:: +-t:: These options are ignored for historical reasons. + -v:: Report what is downloaded. diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl new file mode 100755 index 000000000000..1f35a6a116da --- /dev/null +++ b/Documentation/lint-documentation-style.perl @@ -0,0 +1,24 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +my $exit_code = 0; +sub report { + my ($line, $msg) = @_; + chomp $line; + print STDERR "$ARGV:$.: '$line' $msg\n"; + $exit_code = 1; +} + +my $synopsis_style = 0; + +while (my $line = <>) { + if ($line =~ /^[ \t]*`?[-a-z0-9.]+`?(, `?[-a-z0-9.]+`?)+(::|;;)$/) { + + report($line, "multiple parameters in a definition list item"); + } +} + + +exit $exit_code; diff --git a/Documentation/technical/api-path-walk.adoc b/Documentation/technical/api-path-walk.adoc index 34c905eb9c31..a67de1b143ab 100644 --- a/Documentation/technical/api-path-walk.adoc +++ b/Documentation/technical/api-path-walk.adoc @@ -39,7 +39,10 @@ It is also important that you do not specify the `--objects` flag for the the objects will be walked in a separate way based on those starting commits. -`commits`, `blobs`, `trees`, `tags`:: +`commits`:: +`blobs`:: +`trees`:: +`tags`:: By default, these members are enabled and signal that the path-walk API should call the `path_fn` on objects of these types. Specialized applications could disable some options to make it simpler to walk diff --git a/shared.mak b/shared.mak index 57095d6cf96c..5c7bc9478544 100644 --- a/shared.mak +++ b/shared.mak @@ -89,6 +89,7 @@ ifndef V QUIET_LINT_GITLINK = @echo ' ' LINT GITLINK $<; QUIET_LINT_MANSEC = @echo ' ' LINT MAN SEC $<; QUIET_LINT_DELIMSEC = @echo ' ' LINT DEL SEC $<; + QUIET_LINT_DOCSTYLE = @echo ' ' LINT DOCSTYLE $<; QUIET_LINT_MANEND = @echo ' ' LINT MAN END $<; export V -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 4/6] doc: check for absence of the form --[no-]parameter 2025-08-05 13:03 [PATCH 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget ` (2 preceding siblings ...) 2025-08-05 13:03 ` [PATCH 3/6] doc: check for absence of multiple terms in each entry of desc list Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 ` Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 5/6] doc:git-for-each-ref: fix styling and typos Jean-Noël Avila via GitGitGadget ` (3 subsequent siblings) 7 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> For better searchability, this commit adds a check to ensure that parameters expressed in the form of `--[no-]parameter` are not used in the documentation. In the place of such parameters, the documentation should list two separate parameters: `--parameter` and `--no-parameter`. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/blame-options.adoc | 3 ++- Documentation/diff-options.adoc | 3 ++- Documentation/fetch-options.adoc | 15 +++++++---- Documentation/git-am.adoc | 3 ++- Documentation/git-backfill.adoc | 3 ++- Documentation/git-cat-file.adoc | 6 +++-- Documentation/git-check-ref-format.adoc | 3 ++- Documentation/git-clone.adoc | 12 ++++++--- Documentation/git-commit-graph.adoc | 3 ++- Documentation/git-commit.adoc | 3 ++- Documentation/git-config.adoc | 3 ++- Documentation/git-difftool.adoc | 9 ++++--- Documentation/git-fast-import.adoc | 3 ++- Documentation/git-fmt-merge-msg.adoc | 3 ++- Documentation/git-format-patch.adoc | 12 ++++++--- Documentation/git-fsck.adoc | 9 ++++--- Documentation/git-gc.adoc | 6 +++-- Documentation/git-index-pack.adoc | 3 ++- Documentation/git-log.adoc | 6 +++-- Documentation/git-merge-tree.adoc | 3 ++- Documentation/git-multi-pack-index.adoc | 3 ++- Documentation/git-pack-objects.adoc | 3 ++- Documentation/git-pull.adoc | 3 ++- Documentation/git-push.adoc | 18 ++++++++----- Documentation/git-range-diff.adoc | 3 ++- Documentation/git-read-tree.adoc | 3 ++- Documentation/git-reset.adoc | 3 ++- Documentation/git-send-email.adoc | 30 ++++++++++++++------- Documentation/git-send-pack.adoc | 3 ++- Documentation/git-submodule.adoc | 6 +++-- Documentation/git-update-index.adoc | 12 ++++++--- Documentation/git-upload-pack.adoc | 3 ++- Documentation/git-worktree.adoc | 12 ++++++--- Documentation/lint-documentation-style.perl | 3 +++ Documentation/merge-options.adoc | 3 ++- Documentation/scalar.adoc | 18 ++++++++----- 36 files changed, 159 insertions(+), 78 deletions(-) diff --git a/Documentation/blame-options.adoc b/Documentation/blame-options.adoc index 19ea1872388f..1fb948fc76f3 100644 --- a/Documentation/blame-options.adoc +++ b/Documentation/blame-options.adoc @@ -75,7 +75,8 @@ include::line-range-format.adoc[] iso format is used. For supported values, see the discussion of the --date option at linkgit:git-log[1]. ---[no-]progress:: +--progress:: +--no-progress:: Progress status is reported on the standard error stream by default when it is attached to a terminal. This flag enables progress reporting even if not attached to a diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc index f3a35d81411f..f19b85142f4e 100644 --- a/Documentation/diff-options.adoc +++ b/Documentation/diff-options.adoc @@ -505,7 +505,8 @@ endif::git-format-patch[] Turn off rename detection, even when the configuration file gives the default to do so. -`--[no-]rename-empty`:: +`--rename-empty`:: +`--no-rename-empty`:: Whether to use empty blobs as rename source. ifndef::git-format-patch[] diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc index b01372e4b3c6..d3ac31f4e2a1 100644 --- a/Documentation/fetch-options.adoc +++ b/Documentation/fetch-options.adoc @@ -1,4 +1,5 @@ ---[no-]all:: +--all:: +--no-all:: Fetch all remotes, except for the ones that has the `remote.<name>.skipFetchAll` configuration variable set. This overrides the configuration variable fetch.all`. @@ -88,7 +89,8 @@ This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes precedence over the `fetch.output` config option. ifndef::git-pull[] ---[no-]write-fetch-head:: +--write-fetch-head:: +--no-write-fetch-head:: Write the list of remote refs fetched in the `FETCH_HEAD` file directly under `$GIT_DIR`. This is the default. Passing `--no-write-fetch-head` from the command line tells @@ -118,13 +120,16 @@ ifndef::git-pull[] Allow several <repository> and <group> arguments to be specified. No <refspec>s may be specified. ---[no-]auto-maintenance:: ---[no-]auto-gc:: +--auto-maintenance:: +--no-auto-maintenance:: +--auto-gc:: +--no-auto-gc:: Run `git maintenance run --auto` at the end to perform automatic repository maintenance if needed. (`--[no-]auto-gc` is a synonym.) This is enabled by default. ---[no-]write-commit-graph:: +--write-commit-graph:: +--no-write-commit-graph:: Write a commit-graph after fetching. This overrides the config setting `fetch.writeCommitGraph`. endif::git-pull[] diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc index 221070de4812..b23b4fba2013 100644 --- a/Documentation/git-am.adoc +++ b/Documentation/git-am.adoc @@ -48,7 +48,8 @@ OPTIONS --keep-non-patch:: Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). ---[no-]keep-cr:: +--keep-cr:: +--no-keep-cr:: With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) with the same option, to prevent it from stripping CR at the end of lines. `am.keepcr` configuration variable can be used to specify the diff --git a/Documentation/git-backfill.adoc b/Documentation/git-backfill.adoc index 95623051f789..b8394dcf22b6 100644 --- a/Documentation/git-backfill.adoc +++ b/Documentation/git-backfill.adoc @@ -57,7 +57,8 @@ OPTIONS blobs seen at a given path. The default minimum batch size is 50,000. -`--[no-]sparse`:: +`--sparse`:: +`--no-sparse`:: Only download objects if they appear at a path that matches the current sparse-checkout. If the sparse-checkout feature is enabled, then `--sparse` is assumed and can be disabled with `--no-sparse`. diff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc index 180d1ad363fd..c139f55a168d 100644 --- a/Documentation/git-cat-file.adoc +++ b/Documentation/git-cat-file.adoc @@ -62,8 +62,10 @@ OPTIONS or to ask for a "blob" with `<object>` being a tag object that points at it. ---[no-]mailmap:: ---[no-]use-mailmap:: +--mailmap:: +--no-mailmap:: +--use-mailmap:: +--no-use-mailmap:: Use mailmap file to map author, committer and tagger names and email addresses to canonical real names and email addresses. See linkgit:git-shortlog[1]. diff --git a/Documentation/git-check-ref-format.adoc b/Documentation/git-check-ref-format.adoc index 2aacfd18088d..0c3abf914657 100644 --- a/Documentation/git-check-ref-format.adoc +++ b/Documentation/git-check-ref-format.adoc @@ -98,7 +98,8 @@ a branch. OPTIONS ------- ---[no-]allow-onelevel:: +--allow-onelevel:: +--no-allow-onelevel:: Controls whether one-level refnames are accepted (i.e., refnames that do not contain multiple `/`-separated components). The default is `--no-allow-onelevel`. diff --git a/Documentation/git-clone.adoc b/Documentation/git-clone.adoc index 222d558290ed..031b56f09824 100644 --- a/Documentation/git-clone.adoc +++ b/Documentation/git-clone.adoc @@ -272,7 +272,8 @@ corresponding `--mirror` and `--no-tags` options instead. reachable from a specified remote branch or tag. This option can be specified multiple times. -`--[no-]single-branch`:: +`--single-branch`:: +`--no-single-branch`:: Clone only the history leading to the tip of a single branch, either specified by the `--branch` option or the primary branch remote's `HEAD` points at. @@ -282,7 +283,8 @@ corresponding `--mirror` and `--no-tags` options instead. branch when `--single-branch` clone was made, no remote-tracking branch is created. -`--[no-]tags`:: +`--tags`:: +`--no-tags`:: Control whether or not tags will be cloned. When `--no-tags` is given, the option will be become permanent by setting the `remote.<remote>.tagOpt=--no-tags` configuration. This ensures that @@ -313,10 +315,12 @@ the clone is finished. This option is ignored if the cloned repository does not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) -`--[no-]shallow-submodules`:: +`--shallow-submodules`:: +`--no-shallow-submodules`:: All submodules which are cloned will be shallow with a depth of 1. -`--[no-]remote-submodules`:: +`--remote-submodules`:: +`--no-remote-submodules`:: All submodules which are cloned will use the status of the submodule's remote-tracking branch to update the submodule, rather than the superproject's recorded SHA-1. Equivalent to passing `--remote` to diff --git a/Documentation/git-commit-graph.adoc b/Documentation/git-commit-graph.adoc index 50b50168045c..e9558173c001 100644 --- a/Documentation/git-commit-graph.adoc +++ b/Documentation/git-commit-graph.adoc @@ -34,7 +34,8 @@ OPTIONS object directory, `git commit-graph ...` will exit with non-zero status. ---[no-]progress:: +--progress:: +--no-progress:: Turn progress on/off explicitly. If neither is specified, progress is shown if standard error is connected to a terminal. diff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc index d4d576ce665f..54c207ad45ea 100644 --- a/Documentation/git-commit.adoc +++ b/Documentation/git-commit.adoc @@ -214,7 +214,8 @@ include::signoff-option.adoc[] each trailer would appear, and other details. `-n`:: -`--[no-]verify`:: +`--verify`:: +`--no-verify`:: Bypass the `pre-commit` and `commit-msg` hooks. See also linkgit:githooks[5]. diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc index 511b2e26bfb0..36d28451528e 100644 --- a/Documentation/git-config.adoc +++ b/Documentation/git-config.adoc @@ -295,7 +295,8 @@ Valid `<type>`'s include: When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---[no-]includes:: +--includes:: +--no-includes:: Respect `include.*` directives in config files when looking up values. Defaults to `off` when a specific file is given (e.g., using `--file`, `--global`, etc) and `on` when searching all diff --git a/Documentation/git-difftool.adoc b/Documentation/git-difftool.adoc index d596205eaf3b..064bc683471f 100644 --- a/Documentation/git-difftool.adoc +++ b/Documentation/git-difftool.adoc @@ -77,7 +77,8 @@ with custom merge tool commands and has the same value as `$MERGED`. --tool-help:: Print a list of diff tools that may be used with `--tool`. ---[no-]symlinks:: +--symlinks:: +--no-symlinks:: 'git difftool''s default behavior is to create symlinks to the working tree when run in `--dir-diff` mode and the right-hand side of the comparison yields the same content as the file in @@ -94,7 +95,8 @@ instead. `--no-symlinks` is the default on Windows. Additionally, `$BASE` is set in the environment. -g:: ---[no-]gui:: +--gui:: +--no-gui:: When 'git-difftool' is invoked with the `-g` or `--gui` option the default diff tool will be read from the configured `diff.guitool` variable instead of `diff.tool`. This may be @@ -104,7 +106,8 @@ instead. `--no-symlinks` is the default on Windows. fallback in the order of `merge.guitool`, `diff.tool`, `merge.tool` until a tool is found. ---[no-]trust-exit-code:: +--trust-exit-code:: +--no-trust-exit-code:: Errors reported by the diff tool are ignored by default. Use `--trust-exit-code` to make 'git-difftool' exit when an invoked diff tool returns a non-zero exit code. diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index 6490d67fab56..3144ffcdb689 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -111,7 +111,8 @@ Locations of Marks Files Like --import-marks but instead of erroring out, silently skips the file if it does not exist. ---[no-]relative-marks:: +--relative-marks:: +--no-relative-marks:: After specifying --relative-marks the paths specified with --import-marks= and --export-marks= are relative to an internal directory in the current repository. diff --git a/Documentation/git-fmt-merge-msg.adoc b/Documentation/git-fmt-merge-msg.adoc index 0f3328956dfd..6d91620be979 100644 --- a/Documentation/git-fmt-merge-msg.adoc +++ b/Documentation/git-fmt-merge-msg.adoc @@ -35,7 +35,8 @@ OPTIONS Do not list one-line descriptions from the actual commits being merged. ---[no-]summary:: +--summary:: +--no-summary:: Synonyms to --log and --no-log; these are deprecated and will be removed in the future. diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc index a8b53db9a663..048d1b981524 100644 --- a/Documentation/git-format-patch.adoc +++ b/Documentation/git-format-patch.adoc @@ -295,7 +295,8 @@ header). Note also that `git send-email` already handles this transformation for you, and this option should not be used if you are feeding the result to `git send-email`. ---[no-]force-in-body-from:: +--force-in-body-from:: +--no-force-in-body-from:: With the e-mail sender specified via the `--from` option, by default, an in-body "From:" to identify the real author of the commit is added at the top of the commit log message if @@ -314,7 +315,8 @@ feeding the result to `git send-email`. `Cc:`, and custom) headers added so far from config or command line. ---[no-]cover-letter:: +--cover-letter:: +--no-cover-letter:: In addition to the patches, generate a cover letter file containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out. @@ -379,7 +381,8 @@ configuration options in linkgit:git-notes[1] to use this workflow). The default is `--no-notes`, unless the `format.notes` configuration is set. ---[no-]signature=<signature>:: +--signature=<signature>:: +--no-signature:: Add a signature to each message produced. Per RFC 3676 the signature is separated from the body by a line with '-- ' on it. If the signature option is omitted the signature defaults to the Git version @@ -411,7 +414,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. Output an all-zero hash in each patch's From header instead of the hash of the commit. ---[no-]base[=<commit>]:: +--no-base:: +--base[=<commit>]:: Record the base tree information to identify the state the patch series applies to. See the BASE TREE INFORMATION section below for details. If <commit> is "auto", a base commit is diff --git a/Documentation/git-fsck.adoc b/Documentation/git-fsck.adoc index 11203ba925c7..1751f692d42b 100644 --- a/Documentation/git-fsck.adoc +++ b/Documentation/git-fsck.adoc @@ -31,7 +31,8 @@ index file, all SHA-1 references in the `refs` namespace, and all reflogs Print out objects that exist but that aren't reachable from any of the reference nodes. ---[no-]dangling:: +--dangling:: +--no-dangling:: Print objects that exist but that are never 'directly' used (default). `--no-dangling` can be used to omit this information from the output. @@ -97,14 +98,16 @@ care about this output and want to speed it up further. compatible with linkgit:git-rev-parse[1], e.g. `HEAD@{1234567890}~25^2:src/`. ---[no-]progress:: +--progress:: +--no-progress:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless --no-progress or --verbose is specified. --progress forces progress status even if the standard error stream is not directed to a terminal. ---[no-]references:: +--references:: +--no-references:: Control whether to check the references database consistency via 'git refs verify'. See linkgit:git-refs[1] for details. The default is to check the references database. diff --git a/Documentation/git-gc.adoc b/Documentation/git-gc.adoc index 526ce01463d7..6fed646dd883 100644 --- a/Documentation/git-gc.adoc +++ b/Documentation/git-gc.adoc @@ -53,11 +53,13 @@ configuration options such as `gc.auto` and `gc.autoPackLimit`, all other housekeeping tasks (e.g. rerere, working trees, reflog...) will be performed as well. ---[no-]detach:: +--detach:: +--no-detach:: Run in the background if the system supports it. This option overrides the `gc.autoDetach` config. ---[no-]cruft:: +--cruft:: +--no-cruft:: When expiring unreachable objects, pack them separately into a cruft pack instead of storing them as loose objects. `--cruft` is on by default. diff --git a/Documentation/git-index-pack.adoc b/Documentation/git-index-pack.adoc index 270056cf6352..18036953c06b 100644 --- a/Documentation/git-index-pack.adoc +++ b/Documentation/git-index-pack.adoc @@ -36,7 +36,8 @@ OPTIONS fails if the name of packed archive does not end with .pack). ---[no-]rev-index:: +--rev-index:: +--no-rev-index:: When this flag is provided, generate a reverse index (a `.rev` file) corresponding to the given pack. If `--verify` is given, ensure that the existing diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc index b6f3d92c435f..e304739c5e80 100644 --- a/Documentation/git-log.adoc +++ b/Documentation/git-log.adoc @@ -73,8 +73,10 @@ used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`, Print out the ref name given on the command line by which each commit was reached. -`--[no-]mailmap`:: -`--[no-]use-mailmap`:: +`--mailmap`:: +`--no-mailmap`:: +`--use-mailmap`:: +`--no-use-mailmap`:: Use mailmap file to map author and committer names and email addresses to canonical real names and email addresses. See linkgit:git-shortlog[1]. diff --git a/Documentation/git-merge-tree.adoc b/Documentation/git-merge-tree.adoc index f824eea61f1e..271ab220e8d7 100644 --- a/Documentation/git-merge-tree.adoc +++ b/Documentation/git-merge-tree.adoc @@ -59,7 +59,8 @@ OPTIONS do not list filenames multiple times if they have multiple conflicting stages). ---[no-]messages:: +--messages:: +--no-messages:: Write any informational messages such as "Auto-merging <path>" or CONFLICT notices to the end of stdout. If unspecified, the default is to include these messages if there are merge diff --git a/Documentation/git-multi-pack-index.adoc b/Documentation/git-multi-pack-index.adoc index b6cd0d7f855d..e8073bc27232 100644 --- a/Documentation/git-multi-pack-index.adoc +++ b/Documentation/git-multi-pack-index.adoc @@ -25,7 +25,8 @@ OPTIONS + `<dir>` must be an alternate of the current repository. ---[no-]progress:: +--progress:: +--no-progress:: Turn progress on/off explicitly. If neither is specified, progress is shown if standard error is connected to a terminal. Supported by sub-commands `write`, `verify`, `expire`, and `repack. diff --git a/Documentation/git-pack-objects.adoc b/Documentation/git-pack-objects.adoc index eba014c40615..71b9682485c3 100644 --- a/Documentation/git-pack-objects.adoc +++ b/Documentation/git-pack-objects.adoc @@ -243,7 +243,8 @@ depth is 4095. Add --no-reuse-object if you want to force a uniform compression level on all data no matter the source. ---[no-]sparse:: +--sparse:: +--no-sparse:: Toggle the "sparse" algorithm to determine which objects to include in the pack, when combined with the "--revs" option. This algorithm only walks trees that appear in paths that introduce new objects. diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc index 3f4ecc47301a..48e924a10a40 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -87,7 +87,8 @@ OPTIONS --verbose:: Pass --verbose to git-fetch and git-merge. ---[no-]recurse-submodules[=(yes|on-demand|no)]:: +--recurse-submodules[=(yes|on-demand|no)]:: +--no-recurse-submodules:: This option controls if new commits of populated submodules should be fetched, and if the working trees of active submodules should be updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index d1978650d60a..5f5408e2c01d 100644 --- a/Documentation/git-push.adoc +++ b/Documentation/git-push.adoc @@ -197,7 +197,8 @@ already exists on the remote side. with configuration variable `push.followTags`. For more information, see `push.followTags` in linkgit:git-config[1]. ---[no-]signed:: +--signed:: +--no-signed:: --signed=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be @@ -208,7 +209,8 @@ already exists on the remote side. will also fail if the actual call to `gpg --sign` fails. See linkgit:git-receive-pack[1] for the details on the receiving end. ---[no-]atomic:: +--atomic:: +--no-atomic:: Use an atomic transaction on the remote side if available. Either all refs are updated, or on error, no refs are updated. If the server does not support atomic pushes the push will fail. @@ -232,7 +234,8 @@ already exists on the remote side. repository over ssh, and you do not have the program in a directory on the default $PATH. ---[no-]force-with-lease:: +--force-with-lease:: +--no-force-with-lease:: --force-with-lease=<refname>:: --force-with-lease=<refname>:<expect>:: Usually, "git push" refuses to update a remote ref that is @@ -350,7 +353,8 @@ one branch, use a `+` in front of the refspec to push (e.g `git push origin +master` to force a push to the `master` branch). See the `<refspec>...` section above for details. ---[no-]force-if-includes:: +--force-if-includes:: +--no-force-if-includes:: Force an update only if the tip of the remote-tracking ref has been integrated locally. + @@ -377,7 +381,8 @@ Specifying `--no-force-if-includes` disables this behavior. linkgit:git-pull[1] and other commands. For more information, see `branch.<name>.merge` in linkgit:git-config[1]. ---[no-]thin:: +--thin:: +--no-thin:: These options are passed to linkgit:git-send-pack[1]. A thin transfer significantly reduces the amount of sent data when the sender and receiver share many of the same objects in common. The default is @@ -419,7 +424,8 @@ When using 'on-demand' or 'only', if a submodule has a "push.recurseSubmodules={on-demand,only}" or "submodule.recurse" configuration, further recursion will occur. In this case, "only" is treated as "on-demand". ---[no-]verify:: +--verify:: +--no-verify:: Toggle the pre-push hook (see linkgit:githooks[5]). The default is --verify, giving the hook a chance to prevent the push. With --no-verify, the hook is bypassed completely. diff --git a/Documentation/git-range-diff.adoc b/Documentation/git-range-diff.adoc index db0e4279b528..b5e85d37f1be 100644 --- a/Documentation/git-range-diff.adoc +++ b/Documentation/git-range-diff.adoc @@ -96,7 +96,8 @@ diff. --remerge-diff:: Convenience option, equivalent to `--diff-merges=remerge`. ---[no-]notes[=<ref>]:: +--notes[=<ref>]:: +--no-notes:: This flag is passed to the `git log` program (see linkgit:git-log[1]) that generates the patches. diff --git a/Documentation/git-read-tree.adoc b/Documentation/git-read-tree.adoc index 1c48c2899630..1c04bba2b7b8 100644 --- a/Documentation/git-read-tree.adoc +++ b/Documentation/git-read-tree.adoc @@ -100,7 +100,8 @@ OPTIONS directories the index file and index output file are located in. ---[no-]recurse-submodules:: +--recurse-submodules:: +--no-recurse-submodules:: Using --recurse-submodules will update the content of all active submodules according to the commit recorded in the superproject by calling read-tree recursively, also setting the submodules' HEAD to be diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc index 50e8a0ba6f66..3b9ba9aee952 100644 --- a/Documentation/git-reset.adoc +++ b/Documentation/git-reset.adoc @@ -90,7 +90,8 @@ but carries forward unmerged index entries. If a file that is different between _<commit>_ and `HEAD` has local changes, reset is aborted. -`--[no-]recurse-submodules`:: +`--recurse-submodules`:: +`--no-recurse-submodules`:: When the working tree is updated, using `--recurse-submodules` will also recursively reset the working tree of all active submodules according to the commit recorded in the superproject, also setting diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc index 5335502d68fc..11b1ab1a070a 100644 --- a/Documentation/git-send-email.adoc +++ b/Documentation/git-send-email.adoc @@ -115,7 +115,8 @@ illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`: Only necessary if `--compose` is also set. If `--compose` is not set, this will be prompted for. ---[no-]outlook-id-fix:: +--outlook-id-fix:: +--no-outlook-id-fix:: Microsoft Outlook SMTP servers discard the Message-ID sent via email and assign a new random Message-ID, thus breaking threads. + @@ -350,7 +351,8 @@ Automating --no-header-cmd:: Disable any header command in use. ---[no-]chain-reply-to:: +--chain-reply-to:: +--no-chain-reply-to:: If this is set, each email will be sent as a reply to the previous email sent. If disabled with `--no-chain-reply-to`, all emails after the first will be sent as replies to the first email sent. When using @@ -364,19 +366,22 @@ Automating values in the `sendemail` section. The default identity is the value of `sendemail.identity`. ---[no-]signed-off-by-cc:: +--signed-off-by-cc:: +--no-signed-off-by-cc:: If this is set, add emails found in the `Signed-off-by` trailer or `Cc:` lines to the cc list. Default is the value of `sendemail.signedOffByCc` configuration value; if that is unspecified, default to `--signed-off-by-cc`. ---[no-]cc-cover:: +--cc-cover:: +--no-cc-cover:: If this is set, emails found in `Cc:` headers in the first patch of the series (typically the cover letter) are added to the cc list for each email set. Default is the value of `sendemail.ccCover` configuration value; if that is unspecified, default to `--no-cc-cover`. ---[no-]to-cover:: +--to-cover:: +--no-to-cover:: If this is set, emails found in `To:` headers in the first patch of the series (typically the cover letter) are added to the to list for each email set. Default is the value of `sendemail.toCover` @@ -407,12 +412,14 @@ Default is the value of `sendemail.suppressCc` configuration value; if that is unspecified, default to `self` if `--suppress-from` is specified, as well as `body` if `--no-signed-off-cc` is specified. ---[no-]suppress-from:: +--suppress-from:: +--no-suppress-from:: If this is set, do not add the `From:` address to the `Cc:` list. Default is the value of `sendemail.suppressFrom` configuration value; if that is unspecified, default to `--no-suppress-from`. ---[no-]thread:: +--thread:: +--no-thread:: If this is set, the `In-Reply-To` and `References` headers will be added to each email sent. Whether each mail refers to the previous email (`deep` threading per `git format-patch` @@ -430,7 +437,8 @@ exists when `git send-email` is asked to add it (especially note that Failure to do so may not produce the expected result in the recipient's MUA. ---[no-]mailmap:: +--mailmap:: +--no-mailmap:: Use the mailmap file (see linkgit:gitmailmap[5]) to map all addresses to their canonical real name and email address. Additional mailmap data specific to `git send-email` may be provided using the @@ -459,7 +467,8 @@ have been specified, in which case default to `compose`. --dry-run:: Do everything except actually send the emails. ---[no-]format-patch:: +--format-patch:: +--no-format-patch:: When an argument may be understood either as a reference or as a file name, choose to understand it as a format-patch argument (`--format-patch`) or as a file name (`--no-format-patch`). By default, when such a conflict @@ -469,7 +478,8 @@ have been specified, in which case default to `compose`. Make `git send-email` less verbose. One line per email should be all that is output. ---[no-]validate:: +--validate:: +--no-validate:: Perform sanity checks on patches. Currently, validation means the following: + diff --git a/Documentation/git-send-pack.adoc b/Documentation/git-send-pack.adoc index b9e73f2e77b1..811193f16c33 100644 --- a/Documentation/git-send-pack.adoc +++ b/Documentation/git-send-pack.adoc @@ -71,7 +71,8 @@ be in a separate packet, and the list must end with a flush packet. fails to update then the entire push will fail without changing any refs. ---[no-]signed:: +--signed:: +--no-signed:: --signed=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be diff --git a/Documentation/git-submodule.adoc b/Documentation/git-submodule.adoc index 87d8e0f0c563..2d6ac92ea450 100644 --- a/Documentation/git-submodule.adoc +++ b/Documentation/git-submodule.adoc @@ -435,7 +435,8 @@ options carefully. clone with a history truncated to the specified number of revisions. See linkgit:git-clone[1] ---[no-]recommend-shallow:: +--recommend-shallow:: +--no-recommend-shallow:: This option is only valid for the update command. The initial clone of a submodule will use the recommended `submodule.<name>.shallow` as provided by the `.gitmodules` file @@ -447,7 +448,8 @@ options carefully. Clone new submodules in parallel with as many jobs. Defaults to the `submodule.fetchJobs` option. ---[no-]single-branch:: +--single-branch:: +--no-single-branch:: This option is only valid for the update command. Clone only one branch during update: HEAD or one specified by --branch. diff --git a/Documentation/git-update-index.adoc b/Documentation/git-update-index.adoc index 7128aed54058..9bea9fab9ad1 100644 --- a/Documentation/git-update-index.adoc +++ b/Documentation/git-update-index.adoc @@ -86,7 +86,8 @@ OPTIONS --chmod=(+|-)x:: Set the execute permissions on the updated files. ---[no-]assume-unchanged:: +--assume-unchanged:: +--no-assume-unchanged:: When this flag is specified, the object names recorded for the paths are not updated. Instead, this option sets/unsets the "assume unchanged" bit for the @@ -108,18 +109,21 @@ you will need to handle the situation manually. Like `--refresh`, but checks stat information unconditionally, without regard to the "assume unchanged" setting. ---[no-]skip-worktree:: +--skip-worktree:: +--no-skip-worktree:: When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "skip-worktree" bit for the paths. See section "Skip-worktree bit" below for more information. ---[no-]ignore-skip-worktree-entries:: +--ignore-skip-worktree-entries:: +--no-ignore-skip-worktree-entries:: Do not remove skip-worktree (AKA "index-only") entries even when the `--remove` option was specified. ---[no-]fsmonitor-valid:: +--fsmonitor-valid:: +--no-fsmonitor-valid:: When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "fsmonitor valid" bit for the paths. See diff --git a/Documentation/git-upload-pack.adoc b/Documentation/git-upload-pack.adoc index 516d1639d9d0..9167a321d08e 100644 --- a/Documentation/git-upload-pack.adoc +++ b/Documentation/git-upload-pack.adoc @@ -25,7 +25,8 @@ repository. For push operations, see 'git send-pack'. OPTIONS ------- ---[no-]strict:: +--strict:: +--no-strict:: Do not try <directory>/.git/ if <directory> is not a Git directory. --timeout=<n>:: diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc index 8340b7f028e6..389e669ac044 100644 --- a/Documentation/git-worktree.adoc +++ b/Documentation/git-worktree.adoc @@ -200,13 +200,15 @@ To remove a locked worktree, specify `--force` twice. With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD" in linkgit:git-checkout[1]. ---[no-]checkout:: +--checkout:: +--no-checkout:: By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can be used to suppress checkout in order to make customizations, such as configuring sparse-checkout. See "Sparse checkout" in linkgit:git-read-tree[1]. ---[no-]guess-remote:: +--guess-remote:: +--no-guess-remote:: With `worktree add <path>`, without `<commit-ish>`, instead of creating a new branch from `HEAD`, if there exists a tracking branch in exactly one remote matching the basename of `<path>`, @@ -216,7 +218,8 @@ To remove a locked worktree, specify `--force` twice. This can also be set up as the default behaviour by using the `worktree.guessRemote` config option. ---[no-]relative-paths:: +--relative-paths:: +--no-relative-paths:: Link worktrees using relative paths or absolute paths (default). Overrides the `worktree.useRelativePaths` config option, see linkgit:git-config[1]. @@ -224,7 +227,8 @@ This can also be set up as the default behaviour by using the With `repair`, the linking files will be updated if there's an absolute/relative mismatch, even if the links are correct. ---[no-]track:: +--track:: +--no-track:: When creating a new branch, if `<commit-ish>` is a branch, mark it as "upstream" from the new branch. This is the default if `<commit-ish>` is a remote-tracking branch. See diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl index 1f35a6a116da..11321a151bca 100755 --- a/Documentation/lint-documentation-style.perl +++ b/Documentation/lint-documentation-style.perl @@ -18,6 +18,9 @@ while (my $line = <>) { report($line, "multiple parameters in a definition list item"); } + if ($line =~ /^`?--\[no-\][a-z0-9-]+.*(::|;;)$/) { + report($line, "definition list item with a `--[no-]` parameter"); + } } diff --git a/Documentation/merge-options.adoc b/Documentation/merge-options.adoc index 95ef491be109..9d433265b298 100644 --- a/Documentation/merge-options.adoc +++ b/Documentation/merge-options.adoc @@ -135,7 +135,8 @@ ifdef::git-pull[] Only useful when merging. endif::git-pull[] -`--[no-]verify`:: +`--verify`:: +`--no-verify`:: By default, the pre-merge and commit-msg hooks are run. When `--no-verify` is given, these are bypassed. See also linkgit:githooks[5]. diff --git a/Documentation/scalar.adoc b/Documentation/scalar.adoc index 4bd5b150e8e1..f81b2832f8df 100644 --- a/Documentation/scalar.adoc +++ b/Documentation/scalar.adoc @@ -71,7 +71,8 @@ HEAD[:<directory>]`. Instead of checking out the branch pointed to by the cloned repository's HEAD, check out the `<name>` branch instead. ---[no-]single-branch:: +--single-branch:: +--no-single-branch:: Clone only the history leading to the tip of a single branch, either specified by the `--branch` option or the primary branch remote's `HEAD` points at. @@ -81,23 +82,27 @@ remote-tracking branch for the branch this option was used for the initial cloning. If the HEAD at the remote did not point at any branch when `--single-branch` clone was made, no remote-tracking branch is created. ---[no-]src:: +--src:: +--no-src:: By default, `scalar clone` places the cloned repository within a `<entlistment>/src` directory. Use `--no-src` to place the cloned repository directly in the `<enlistment>` directory. ---[no-]tags:: +--tags:: +--no-tags:: By default, `scalar clone` will fetch the tag objects advertised by the remote and future `git fetch` commands will do the same. Use `--no-tags` to avoid fetching tags in `scalar clone` and to configure the repository to avoid fetching tags in the future. To fetch tags after cloning with `--no-tags`, run `git fetch --tags`. ---[no-]full-clone:: +--full-clone:: +--no-full-clone:: A sparse-checkout is initialized by default. This behavior can be turned off via `--full-clone`. ---[no-]maintenance:: +--maintenance:: +--no-maintenance:: By default, `scalar clone` configures the enlistment to use Git's background maintenance feature. Use the `--no-maintenance` to skip this configuration. @@ -122,7 +127,8 @@ Note: when this subcommand is called in a worktree that is called `src/`, its parent directory is considered to be the Scalar enlistment. If the worktree is _not_ called `src/`, it itself will be considered to be the Scalar enlistment. ---[no-]maintenance:: +--maintenance:: +--no-maintenance:: By default, `scalar register` configures the enlistment to use Git's background maintenance feature. Use the `--no-maintenance` to skip this configuration. This does not disable any maintenance that may -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 5/6] doc:git-for-each-ref: fix styling and typos 2025-08-05 13:03 [PATCH 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget ` (3 preceding siblings ...) 2025-08-05 13:03 ` [PATCH 4/6] doc: check for absence of the form --[no-]parameter Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 ` Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 6/6] doc lint: check that synopsis manpages have synopsis inlines Jean-Noël Avila via GitGitGadget ` (2 subsequent siblings) 7 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> This commit fixes the synopsis syntax and changes the wording of a few descriptions to be more consistent with the rest of the documentation. It is a prepartion for the next commit that checks that synopsis style is applied consistently across a manual page. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/git-for-each-ref.adoc | 264 ++++++++++++++-------------- 1 file changed, 132 insertions(+), 132 deletions(-) diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc index 060940904da2..b69080c4a000 100644 --- a/Documentation/git-for-each-ref.adoc +++ b/Documentation/git-for-each-ref.adoc @@ -14,101 +14,98 @@ git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl] [--merged[=<object>]] [--no-merged[=<object>]] [--contains[=<object>]] [--no-contains[=<object>]] [(--exclude=<pattern>)...] [--start-after=<marker>] - [ --stdin | <pattern>... ] + [ --stdin | (<pattern>...)] DESCRIPTION ----------- -Iterate over all refs that match `<pattern>` and show them -according to the given `<format>`, after sorting them according -to the given set of `<key>`. If `<count>` is given, stop after -showing that many refs. The interpolated values in `<format>` +Iterate over all refs that match _<pattern>_ and show them +according to the given _<format>_, after sorting them according +to the given set of _<key>_. If _<count>_ is given, stop after +showing that many refs. The interpolated values in _<format>_ can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language. OPTIONS ------- -<pattern>...:: - If one or more patterns are given, only refs are shown that - match against at least one pattern, either using fnmatch(3) or +`<pattern>...`:: + If one or more _<pattern>_ parameters are given, only refs are shown that + match against at least one pattern, either using `fnmatch`(3) or literally, in the latter case matching completely or from the beginning up to a slash. ---stdin:: - If `--stdin` is supplied, then the list of patterns is read from - standard input instead of from the argument list. +`--stdin`:: + The list of patterns is read from standard input instead of from + the argument list. ---count=<count>:: - By default the command shows all refs that match - `<pattern>`. This option makes it stop after showing - that many refs. +`--count=<count>`:: + Stop after showing _<count>_ refs. ---sort=<key>:: - A field name to sort on. Prefix `-` to sort in +`--sort=<key>`:: + Sort on the field name _<key>_. Prefix `-` to sort in descending order of the value. When unspecified, - `refname` is used. You may use the --sort=<key> option + `refname` is used. You may use the `--sort=<key>` option multiple times, in which case the last key becomes the primary key. ---format=<format>:: +`--format[=<format>]`:: A string that interpolates `%(fieldname)` from a ref being shown and the object it points at. In addition, the string literal `%%` renders as `%` and `%xx` - where `xx` are hex digits - renders as the character with hex code `xx`. For example, `%00` interpolates to - `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF). -+ -When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype) + `\0` (_NUL_), `%09` to `\t` (_TAB_), and `%0a` to `\n` (_LF_). + +When unspecified, _<format>_ defaults to `%(objectname) SPC %(objecttype) TAB %(refname)`. ---color[=<when>]:: +`--color[=<when>]`:: Respect any colors specified in the `--format` option. The - `<when>` field must be one of `always`, `never`, or `auto` (if + _<when__ field must be one of `always`, `never`, or `auto` (if `<when>` is absent, behave as if `always` was given). ---shell:: ---perl:: ---python:: ---tcl:: +`--shell`:: +`--perl`:: +`--python`:: +`--tcl`:: If given, strings that substitute `%(fieldname)` placeholders are quoted as string literals suitable for the specified host language. This is meant to produce - a scriptlet that can directly be `eval`ed. + a scriptlet that can directly be "eval"ed. ---points-at=<object>:: +`--points-at=<object>`:: Only list refs which points at the given object. ---merged[=<object>]:: +`--merged[=<object>]`:: Only list refs whose tips are reachable from the - specified commit (HEAD if not specified). - ---no-merged[=<object>]:: - Only list refs whose tips are not reachable from the - specified commit (HEAD if not specified). + specified commit (`HEAD` if not specified). ---contains[=<object>]:: - Only list refs which contain the specified commit (HEAD if not +`--no-merged[=<object>]`:: + Only list refs whose tips are not reachable from _<object>_(`HEAD` if not specified). ---no-contains[=<object>]:: - Only list refs which don't contain the specified commit (HEAD +`--contains[=<object>]`:: + Only list refs which contain _<object>_(`HEAD` if not specified). + +`--no-contains[=<object>]`:: + Only list refs which don't contain _<object>_ (`HEAD` if not specified). ---ignore-case:: +`--ignore-case`:: Sorting and filtering refs are case insensitive. ---omit-empty:: +`--omit-empty`:: Do not print a newline after formatted refs where the format expands to the empty string. ---exclude=<pattern>:: - If one or more patterns are given, only refs which do not match - any excluded pattern(s) are shown. Matching is done using the - same rules as `<pattern>` above. +`--exclude=<excluded-pattern>`:: + If one or more `--exclude` options are given, only refs which do not + match any _<excluded-pattern>_ parameters are shown. Matching is done + using the same rules as _<pattern>_ above. ---include-root-refs:: - List root refs (HEAD and pseudorefs) apart from regular refs. +`--include-root-refs`:: + List root refs (`HEAD` and pseudorefs) apart from regular refs. ---start-after=<marker>:: +`--start-after=<marker>`:: Allows paginating the output by skipping references up to and including the specified marker. When paging, it should be noted that references may be deleted, modified or added between invocations. Output will only yield those @@ -126,44 +123,44 @@ keys. For all objects, the following names can be used: -refname:: - The name of the ref (the part after $GIT_DIR/). +`refname`:: + The name of the ref (the part after `$GIT_DIR/`). For a non-ambiguous short name of the ref append `:short`. - The option core.warnAmbiguousRefs is used to select the strict - abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>` + The option `core.warnAmbiguousRefs` is used to select the strict + abbreviation mode. If `lstrip=<n>` (`rstrip=<n>`) is appended, strip _<n>_ slash-separated path components from the front (back) of the refname (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`). - If `<N>` is a negative number, strip as many path components as - necessary from the specified end to leave `-<N>` path components + If _<n>_ is a negative number, strip as many path components as + necessary from the specified end to leave `-<n>` path components (e.g. `%(refname:lstrip=-2)` turns `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)` turns `refs/tags/foo` into `refs`). When the ref does not have enough components, the result becomes an empty string if - stripping with positive <N>, or it becomes the full refname if - stripping with negative <N>. Neither is an error. + stripping with positive _<n>_, or it becomes the full refname if + stripping with negative _<N>_. Neither is an error. + `strip` can be used as a synonym to `lstrip`. -objecttype:: +`objecttype`:: The type of the object (`blob`, `tree`, `commit`, `tag`). -objectsize:: +`objectsize`:: The size of the object (the same as 'git cat-file -s' reports). Append `:disk` to get the size, in bytes, that the object takes up on - disk. See the note about on-disk sizes in the `CAVEATS` section below. -objectname:: + disk. See the note about on-disk sizes in the 'CAVEATS' section below. +`objectname`:: The object name (aka SHA-1). For a non-ambiguous abbreviation of the object name append `:short`. For an abbreviation of the object name with desired length append - `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The + `:short=<length>`, where the minimum length is `MINIMUM_ABBREV`. The length may be exceeded to ensure unique object names. -deltabase:: +`deltabase`:: This expands to the object name of the delta base for the given object, if it is stored as a delta. Otherwise it expands to the null object name (all zeroes). -upstream:: +`upstream`:: The name of a local ref which can be considered ``upstream'' from the displayed ref. Respects `:short`, `:lstrip` and `:rstrip` in the same way as `refname` above. Additionally @@ -185,100 +182,103 @@ Has no effect if the ref does not have tracking information associated with it. All the options apart from `nobracket` are mutually exclusive, but if used together the last option is selected. -push:: +`push`:: The name of a local ref which represents the `@{push}` location for the displayed ref. Respects `:short`, `:lstrip`, `:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref` options as `upstream` does. Produces an empty string if no `@{push}` ref is configured. -HEAD:: - '*' if HEAD matches current ref (the checked out branch), ' ' +`HEAD`:: + `*` if `HEAD` matches current ref (the checked out branch), ' ' otherwise. -color:: +`color`:: Change output color. Followed by `:<colorname>`, where color names are described under Values in the "CONFIGURATION FILE" section of linkgit:git-config[1]. For example, `%(color:bold red)`. -align:: +`align`:: Left-, middle-, or right-align the content between - %(align:...) and %(end). The "align:" is followed by + `%(align:...)` and `%(end)`. The "`align:`" is followed by `width=<width>` and `position=<position>` in any order - separated by a comma, where the `<position>` is either left, - right or middle, default being left and `<width>` is the total + separated by a comma, where the _<position>_ is either `left`, + `right` or `middle`, default being `left` and _<width>_ is the total length of the content with alignment. For brevity, the "width=" and/or "position=" prefixes may be omitted, and bare - <width> and <position> used instead. For instance, + _<width>_ and _<position>_ used instead. For instance, `%(align:<width>,<position>)`. If the contents length is more than the width then no alignment is performed. If used with - `--quote` everything in between %(align:...) and %(end) is + `--quote` everything in between `%(align:...)` and `%(end)` is quoted, but if nested then only the topmost level performs quoting. -if:: - Used as %(if)...%(then)...%(end) or - %(if)...%(then)...%(else)...%(end). If there is an atom with - value or string literal after the %(if) then everything after - the %(then) is printed, else if the %(else) atom is used, then +`if`:: + Used as `%(if)...%(then)...%(end)` or + `%(if)...%(then)...%(else)...%(end)`. If there is an atom with + value or string literal after the `%(if)` then everything after + the `%(then)` is printed, else if the `%(else)` atom is used, then everything after %(else) is printed. We ignore space when - evaluating the string before %(then), this is useful when we - use the %(HEAD) atom which prints either "*" or " " and we - want to apply the 'if' condition only on the 'HEAD' ref. - Append ":equals=<string>" or ":notequals=<string>" to compare - the value between the %(if:...) and %(then) atoms with the + evaluating the string before `%(then)`, this is useful when we + use the `%(HEAD)` atom which prints either "`*`" or " " and we + want to apply the 'if' condition only on the `HEAD` ref. + Append "`:equals=<string>`" or "`:notequals=<string>`" to compare + the value between the `%(if:...)` and `%(then)` atoms with the given string. -symref:: +`symref`:: The ref which the given symbolic ref refers to. If not a symbolic ref, nothing is printed. Respects the `:short`, `:lstrip` and `:rstrip` options in the same way as `refname` above. -signature:: +`signature`:: The GPG signature of a commit. -signature:grade:: - Show "G" for a good (valid) signature, "B" for a bad - signature, "U" for a good signature with unknown validity, "X" - for a good signature that has expired, "Y" for a good - signature made by an expired key, "R" for a good signature - made by a revoked key, "E" if the signature cannot be - checked (e.g. missing key) and "N" for no signature. - -signature:signer:: +`signature:grade`:: + Show +`G`;; for a good (valid) signature +`B`;; for a bad signature +`U`;; for a good signature with unknown validity +`X`;; for a good signature that has expired +`Y`;; for a good signature made by an expired key +`R`;; for a good signature made by a revoked key +`E`;; if the signature cannot be checked (e.g. missing key) +`N`;; for no signature. + +`signature:signer`:: The signer of the GPG signature of a commit. -signature:key:: +`signature:key`:: The key of the GPG signature of a commit. -signature:fingerprint:: +`signature:fingerprint`:: The fingerprint of the GPG signature of a commit. -signature:primarykeyfingerprint:: +`signature:primarykeyfingerprint`:: The primary key fingerprint of the GPG signature of a commit. -signature:trustlevel:: +`signature:trustlevel`:: The trust level of the GPG signature of a commit. Possible outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`. -worktreepath:: +`worktreepath`:: The absolute path to the worktree in which the ref is checked out, if it is checked out in any linked worktree. Empty string otherwise. -ahead-behind:<committish>:: +`ahead-behind:<commit-ish>`:: Two integers, separated by a space, demonstrating the number of commits ahead and behind, respectively, when comparing the output - ref to the `<committish>` specified in the format. + ref to the _<committish>_ specified in the format. -is-base:<committish>:: - In at most one row, `(<committish>)` will appear to indicate the ref +`is-base:<commit-ish>`:: + In at most one row, `(<commit-ish>)` will appear to indicate the ref that is most likely the ref used as a starting point for the branch - that produced `<committish>`. This choice is made using a heuristic: + that produced _<commit-ish>_. This choice is made using a heuristic: choose the ref that minimizes the number of commits in the - first-parent history of `<committish>` and not in the first-parent + first-parent history of _<commit-ish>_ and not in the first-parent history of the ref. + For example, consider the following figure of first-parent histories of @@ -312,29 +312,29 @@ common first-parent ancestor of `B` and `C` and ties are broken by the earliest ref in the sorted order. + Note that this token will not appear if the first-parent history of -`<committish>` does not intersect the first-parent histories of the +_<commit-ish>_ does not intersect the first-parent histories of the filtered refs. -describe[:options]:: +`describe[:<option>,...]`:: A human-readable name, like linkgit:git-describe[1]; empty string for undescribable commits. The `describe` string may be followed by a colon and one or more comma-separated options. + -- -tags=<bool-value>;; +`tags=<bool-value>`;; Instead of only considering annotated tags, consider lightweight tags as well; see the corresponding option in linkgit:git-describe[1] for details. -abbrev=<number>;; - Use at least <number> hexadecimal digits; see the corresponding +`abbrev=<number>`;; + Use at least _<number>_ hexadecimal digits; see the corresponding option in linkgit:git-describe[1] for details. -match=<pattern>;; - Only consider tags matching the given `glob(7)` pattern, - excluding the "refs/tags/" prefix; see the corresponding option +`match=<pattern>`;; + Only consider tags matching the `glob`(7) _<pattern>_, + excluding the `refs/tags/` prefix; see the corresponding option in linkgit:git-describe[1] for details. -exclude=<pattern>;; - Do not consider tags matching the given `glob(7)` pattern, - excluding the "refs/tags/" prefix; see the corresponding option +`exclude=<pattern>`;; + Do not consider tags matching the `glob`(7) _<pattern>_, + excluding the `refs/tags/` prefix; see the corresponding option in linkgit:git-describe[1] for details. -- @@ -366,7 +366,7 @@ variable (see linkgit:gitmailmap[5]). The raw data in an object is `raw`. -raw:size:: +`raw:size`:: The raw data size of the object. Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`, @@ -376,10 +376,10 @@ variable type. The message in a commit or a tag object is `contents`, from which `contents:<part>` can be used to extract various parts out of: -contents:size:: +`contents:size`:: The size in bytes of the commit or tag message. -contents:subject:: +`contents:subject`:: The first paragraph of the message, which typically is a single line, is taken as the "subject" of the commit or the tag message. @@ -387,19 +387,19 @@ contents:subject:: obtain same results. `:sanitize` can be appended to `subject` for subject line suitable for filename. -contents:body:: +`contents:body`:: The remainder of the commit or the tag message that follows the "subject". -contents:signature:: +`contents:signature`:: The optional GPG signature of the tag. -contents:lines=N:: - The first `N` lines of the message. +`contents:lines=<n>`:: + The first _<n>_ lines of the message. Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1] -are obtained as `trailers[:options]` (or by using the historical alias -`contents:trailers[:options]`). For valid [:option] values see `trailers` +are obtained as `trailers[:<option>,...]` (or by using the historical alias +`contents:trailers[:<option>,...]`). For valid _<option>_ values see `trailers` section of linkgit:git-log[1]. For sorting purposes, fields with numeric values sort in numeric order @@ -419,8 +419,8 @@ option to linkgit:git-rev-list[1] takes). If this formatting is provided in a `--sort` key, references will be sorted according to the byte-value of the formatted string rather than the numeric value of the underlying timestamp. -Some atoms like %(align) and %(if) always require a matching %(end). -We call them "opening atoms" and sometimes denote them as %($open). +Some atoms like `%(align)` and `%(if)` always require a matching `%(end)`. +We call them "opening atoms" and sometimes denote them as `%($open)`. When a scripting language specific quoting is in effect, everything between a top-level opening atom and its matching %(end) is evaluated @@ -438,7 +438,7 @@ An example directly producing formatted text. Show the most recent #!/bin/sh git for-each-ref --count=3 --sort='-*authordate' \ ---format='From: %(*authorname) %(*authoremail) +`--format='From: %(*authorname) %(*authoremail) Subject: %(*subject) Date: %(*authordate) Ref: %(*refname) @@ -449,7 +449,7 @@ Ref: %(*refname) A simple example showing the use of shell eval on the output, -demonstrating the use of --shell. List the prefixes of all heads: +demonstrating the use of `--shell`. List the prefixes of all heads: ------------ #!/bin/sh @@ -517,7 +517,7 @@ eval "$eval" ------------ -An example to show the usage of %(if)...%(then)...%(else)...%(end). +An example to show the usage of `%(if)...%(then)...%(else)...%(end)`. This prefixes the current branch with a star. ------------ @@ -525,7 +525,7 @@ git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" ------------ -An example to show the usage of %(if)...%(then)...%(end). +An example to show the usage of `%(if)...%(then)...%(end)`. This prints the authorname, if present. ------------ -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 6/6] doc lint: check that synopsis manpages have synopsis inlines 2025-08-05 13:03 [PATCH 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget ` (4 preceding siblings ...) 2025-08-05 13:03 ` [PATCH 5/6] doc:git-for-each-ref: fix styling and typos Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 ` Jean-Noël Avila via GitGitGadget 2025-08-05 16:56 ` [PATCH 0/6] Introduce more doc linting Junio C Hamano 2025-08-05 19:10 ` [PATCH v2 " Jean-Noël Avila via GitGitGadget 7 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 13:03 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> When switching manpages to the synopsis style, the description lists of options need to be switched to inline synopsis for proper formatting. This is done by enclosing the option name in double backticks, e.g. `--option`. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/git-refs.adoc | 20 ++++++++++---------- Documentation/lint-documentation-style.perl | 6 ++++++ 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc index 4d6dc994f92e..5d26de8acb22 100644 --- a/Documentation/git-refs.adoc +++ b/Documentation/git-refs.adoc @@ -20,41 +20,41 @@ This command provides low-level access to refs. COMMANDS -------- -migrate:: +`migrate`:: Migrate ref store between different formats. -verify:: +`verify`:: Verify reference database consistency. OPTIONS ------- -The following options are specific to 'git refs migrate': +The following options are specific to `git refs migrate`: ---ref-format=<format>:: +`--ref-format=<format>`:: The ref format to migrate the ref store to. Can be one of: + include::ref-storage-format.adoc[] ---dry-run:: +`--dry-run`:: Perform the migration, but do not modify the repository. The migrated refs will be written into a separate directory that can be inspected separately. The name of the directory will be reported on stdout. This can be used to double check that the migration works as expected before performing the actual migration. ---reflog:: ---no-reflog:: +`--reflog`:: +`--no-reflog`:: Choose between migrating the reflog data to the new backend, and discarding them. The default is "--reflog", to migrate. -The following options are specific to 'git refs verify': +The following options are specific to `git refs verify`: ---strict:: +`--strict`:: Enable stricter error checking. This will cause warnings to be reported as errors. See linkgit:git-fsck[1]. ---verbose:: +`--verbose`:: When verifying the reference database consistency, be chatty. KNOWN LIMITATIONS diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl index 11321a151bca..f9f1da20b7ad 100755 --- a/Documentation/lint-documentation-style.perl +++ b/Documentation/lint-documentation-style.perl @@ -21,6 +21,12 @@ while (my $line = <>) { if ($line =~ /^`?--\[no-\][a-z0-9-]+.*(::|;;)$/) { report($line, "definition list item with a `--[no-]` parameter"); } + if ($line =~ /^\[synopsis\]$/) { + $synopsis_style = 1; + } + if (($line =~ /^-[-a-z].*(::|;;)$/) && ($synopsis_style)) { + report($line, "synopsis style and definition list item not backquoted"); + } } -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH 0/6] Introduce more doc linting 2025-08-05 13:03 [PATCH 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget ` (5 preceding siblings ...) 2025-08-05 13:03 ` [PATCH 6/6] doc lint: check that synopsis manpages have synopsis inlines Jean-Noël Avila via GitGitGadget @ 2025-08-05 16:56 ` Junio C Hamano 2025-08-05 19:10 ` [PATCH v2 " Jean-Noël Avila via GitGitGadget 7 siblings, 0 replies; 28+ messages in thread From: Junio C Hamano @ 2025-08-05 16:56 UTC (permalink / raw) To: Jean-Noël Avila via GitGitGadget; +Cc: git, Jean-Noël Avila "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes: > Reviewing the documentation part of the last patches, it turns out that the > majority of my comments are related to the latest documentation guidelines > which are both easy to forget and almost trivial to automatically check. Thanks. Automation is very much appreciated. These updated documentation pages will also help as examples when reviewing others' patches. Will queue. ^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH v2 0/6] Introduce more doc linting 2025-08-05 13:03 [PATCH 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget ` (6 preceding siblings ...) 2025-08-05 16:56 ` [PATCH 0/6] Introduce more doc linting Junio C Hamano @ 2025-08-05 19:10 ` Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget ` (6 more replies) 7 siblings, 7 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila Reviewing the documentation part of the last patches, it turns out that the majority of my comments are related to the latest documentation guidelines which are both easy to forget and almost trivial to automatically check. This series implements the automatic tests for basic doc rules. At the moment it conflicts with "[GSoC][PATCH v6 0/6] Add refs list subcommand" and possibly with "[PATCH v4 0/9] refs: fix migration of reflog entries" Jean-Noël Avila (6): doc: test linkgit macros for well-formedness doc: check well-formedness of delimited sections doc: check for absence of multiple terms in each entry of desc list doc: check for absence of the form --[no-]parameter doc:git-for-each-ref: fix styling and typos doc lint: check that synopsis manpages have synopsis inlines Documentation/Makefile | 21 +- Documentation/RelNotes/1.6.2.4.adoc | 1 + Documentation/blame-options.adoc | 3 +- Documentation/diff-format.adoc | 1 + Documentation/diff-options.adoc | 3 +- Documentation/fetch-options.adoc | 15 +- Documentation/git-am.adoc | 3 +- Documentation/git-backfill.adoc | 3 +- Documentation/git-cat-file.adoc | 6 +- Documentation/git-check-attr.adoc | 3 +- Documentation/git-check-ignore.adoc | 9 +- Documentation/git-check-ref-format.adoc | 3 +- Documentation/git-checkout.adoc | 2 +- Documentation/git-clone.adoc | 12 +- Documentation/git-commit-graph.adoc | 3 +- Documentation/git-commit.adoc | 4 +- Documentation/git-config.adoc | 3 +- Documentation/git-difftool.adoc | 9 +- Documentation/git-fast-import.adoc | 5 +- Documentation/git-fmt-merge-msg.adoc | 3 +- Documentation/git-for-each-ref.adoc | 264 +++++++++--------- Documentation/git-format-patch.adoc | 12 +- Documentation/git-fsck.adoc | 9 +- Documentation/git-gc.adoc | 6 +- Documentation/git-http-fetch.adoc | 4 +- Documentation/git-index-pack.adoc | 3 +- Documentation/git-log.adoc | 6 +- Documentation/git-merge-tree.adoc | 3 +- Documentation/git-multi-pack-index.adoc | 3 +- Documentation/git-p4.adoc | 1 + Documentation/git-pack-objects.adoc | 3 +- Documentation/git-pull.adoc | 3 +- Documentation/git-push.adoc | 18 +- Documentation/git-range-diff.adoc | 3 +- Documentation/git-read-tree.adoc | 3 +- Documentation/git-rebase.adoc | 2 +- Documentation/git-refs.adoc | 20 +- Documentation/git-reset.adoc | 3 +- Documentation/git-send-email.adoc | 30 +- Documentation/git-send-pack.adoc | 3 +- Documentation/git-submodule.adoc | 6 +- Documentation/git-svn.adoc | 2 + Documentation/git-update-index.adoc | 12 +- Documentation/git-upload-pack.adoc | 3 +- Documentation/git-worktree.adoc | 12 +- Documentation/gitprotocol-http.adoc | 2 +- Documentation/gitsubmodules.adoc | 3 +- Documentation/gitweb.conf.adoc | 2 +- Documentation/lint-delimited-sections.perl | 48 ++++ Documentation/lint-documentation-style.perl | 33 +++ Documentation/lint-gitlink.perl | 7 + Documentation/merge-options.adoc | 3 +- Documentation/mergetools/vimdiff.adoc | 8 + Documentation/scalar.adoc | 18 +- Documentation/technical/api-path-walk.adoc | 5 +- .../long-running-process-protocol.adoc | 1 + shared.mak | 2 + 57 files changed, 446 insertions(+), 232 deletions(-) create mode 100755 Documentation/lint-delimited-sections.perl create mode 100755 Documentation/lint-documentation-style.perl base-commit: 112648dd6bdd8e4f485cd0ae11636807959d48be Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1945%2Fjnavila%2Fdoc_linting-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1945/jnavila/doc_linting-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/1945 Range-diff vs v1: 1: e79bd6a67ef = 1: e79bd6a67ef doc: test linkgit macros for well-formedness 2: 322df2d8dde = 2: 322df2d8dde doc: check well-formedness of delimited sections 3: 5806390052b = 3: 5806390052b doc: check for absence of multiple terms in each entry of desc list 4: 03a8428849f = 4: 03a8428849f doc: check for absence of the form --[no-]parameter 5: 713c86dae92 = 5: 713c86dae92 doc:git-for-each-ref: fix styling and typos 6: e03f3f5c55a ! 6: d57478ea5cd doc lint: check that synopsis manpages have synopsis inlines @@ Commit message Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> + ## Documentation/git-checkout.adoc ## +@@ Documentation/git-checkout.adoc: include::diff-context-options.adoc[] + separated with _NUL_ character and all other characters are taken + literally (including newlines and quotes). + +-<branch>:: ++`<branch>`:: + Branch to checkout; if it refers to a branch (i.e., a name that, + when prepended with "refs/heads/", is a valid ref), then that + branch is checked out. Otherwise, if it refers to a valid + ## Documentation/git-refs.adoc ## @@ Documentation/git-refs.adoc: This command provides low-level access to refs. COMMANDS @@ Documentation/lint-documentation-style.perl: while (my $line = <>) { + if ($line =~ /^\[synopsis\]$/) { + $synopsis_style = 1; + } -+ if (($line =~ /^-[-a-z].*(::|;;)$/) && ($synopsis_style)) { ++ if (($line =~ /^(-[-a-z].*|<[-a-z0-9]+>(\.{3})?)(::|;;)$/) && ($synopsis_style)) { + report($line, "synopsis style and definition list item not backquoted"); + } } -- gitgitgadget ^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH v2 1/6] doc: test linkgit macros for well-formedness 2025-08-05 19:10 ` [PATCH v2 " Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 ` Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 2/6] doc: check well-formedness of delimited sections Jean-Noël Avila via GitGitGadget ` (5 subsequent siblings) 6 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> Some readers of man pages have reported that they found malformed linkgit macros in the documentation (absence or bad spelling). Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/gitweb.conf.adoc | 2 +- Documentation/lint-gitlink.perl | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/Documentation/gitweb.conf.adoc b/Documentation/gitweb.conf.adoc index 1348e9b12504..64bebb811c97 100644 --- a/Documentation/gitweb.conf.adoc +++ b/Documentation/gitweb.conf.adoc @@ -178,7 +178,7 @@ $export_ok:: Show repository only if this file exists (in repository). Only effective if this variable evaluates to true. Can be set when building gitweb by setting `GITWEB_EXPORT_OK`. This path is - relative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok', + relative to `GIT_DIR`. linkgit:git-daemon[1] uses 'git-daemon-export-ok', unless started with `--export-all`. By default this variable is not set, which means that this feature is turned off. diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl index aea564dad7ed..f183a18df284 100755 --- a/Documentation/lint-gitlink.perl +++ b/Documentation/lint-gitlink.perl @@ -41,6 +41,13 @@ die "BUG: No list of valid linkgit:* files given" unless @ARGV; @ARGV = $to_check; while (<>) { my $line = $_; + while ($line =~ m/(.{,8})((git[-a-z]+|scalar)\[(\d)*\])/g) { + my $pos = pos $line; + my ($macro, $target, $page, $section) = ($1, $2, $3, $4); + if ( $macro ne "linkgit:" && $macro !~ "ifn?def::" && $macro ne "endif::" ) { + report($pos, $line, $target, "linkgit: macro expected"); + } + } while ($line =~ m/linkgit:((.*?)\[(\d)\])/g) { my $pos = pos $line; my ($target, $page, $section) = ($1, $2, $3); -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH v2 2/6] doc: check well-formedness of delimited sections 2025-08-05 19:10 ` [PATCH v2 " Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 ` Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 3/6] doc: check for absence of multiple terms in each entry of desc list Jean-Noël Avila via GitGitGadget ` (4 subsequent siblings) 6 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> Having an empty line before each delimited sections is not required by asciidoc, but it is a safety measure that prevents generating malformed asciidoc when generating translated documentation. When a delimited section appears just after a paragraph, the asciidoc processor checks that the length of the delimited section header is different from the length of the paragraph. If it is not, the asciidoc processor will generate a title. In the original English documentation, this is not a problem because the authors always check the output of the asciidoc processor and fix the length of the delimited section header if it turns out to be the same as the paragraph length. However, this is not the case for translations, where the authors have no way to check the length of the delimited section header or the output of the asciidoc processor. This can lead to a section title that is not intended. Indeed, this test also checks that titles are correctly formed, that is, the length of the underline is equal to the length of the title (otherwise it would not be a title but a section header). Finally, this test checks that the delimited section are terminated within the same file. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/Makefile | 11 ++++- Documentation/RelNotes/1.6.2.4.adoc | 1 + Documentation/diff-format.adoc | 1 + Documentation/git-commit.adoc | 1 + Documentation/git-fast-import.adoc | 2 + Documentation/git-p4.adoc | 1 + Documentation/git-rebase.adoc | 2 +- Documentation/git-svn.adoc | 2 + Documentation/gitprotocol-http.adoc | 2 +- Documentation/gitsubmodules.adoc | 3 +- Documentation/lint-delimited-sections.perl | 48 +++++++++++++++++++ Documentation/mergetools/vimdiff.adoc | 8 ++++ .../long-running-process-protocol.adoc | 1 + shared.mak | 1 + 14 files changed, 80 insertions(+), 4 deletions(-) create mode 100755 Documentation/lint-delimited-sections.perl diff --git a/Documentation/Makefile b/Documentation/Makefile index df2ce187eb84..76a9e1d02b26 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -497,9 +497,17 @@ $(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.adoc $(call mkdir_p_parent_template) $(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \ ../fsck.h fsck-msgids.adoc $@ - lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) +## Lint: delimited sections +LINT_DOCS_DELIMITED_SECTIONS = $(patsubst %.adoc,.build/lint-docs/delimited-sections/%.ok,$(MAN_TXT)) +$(LINT_DOCS_DELIMITED_SECTIONS): lint-delimited-sections.perl +$(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.adoc + $(call mkdir_p_parent_template) + $(QUIET_LINT_DELIMSEC)$(PERL_PATH) lint-delimited-sections.perl $< >$@ +.PHONY: lint-docs-delimited-sections +lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) + lint-docs-manpages: $(QUIET_GEN)./lint-manpages.sh @@ -528,6 +536,7 @@ lint-docs: lint-docs-fsck-msgids lint-docs: lint-docs-gitlink lint-docs: lint-docs-man-end-blurb lint-docs: lint-docs-man-section-order +lint-docs: lint-docs-delimited-sections lint-docs: lint-docs-manpages lint-docs: lint-docs-meson diff --git a/Documentation/RelNotes/1.6.2.4.adoc b/Documentation/RelNotes/1.6.2.4.adoc index f4bf1d09863c..053dbb604de6 100644 --- a/Documentation/RelNotes/1.6.2.4.adoc +++ b/Documentation/RelNotes/1.6.2.4.adoc @@ -37,3 +37,4 @@ exec >/var/tmp/1 echo O=$(git describe maint) O=v1.6.2.3-38-g318b847 git shortlog --no-merges $O..maint +--- diff --git a/Documentation/diff-format.adoc b/Documentation/diff-format.adoc index 80e36e153dac..9f7e98824183 100644 --- a/Documentation/diff-format.adoc +++ b/Documentation/diff-format.adoc @@ -103,6 +103,7 @@ if the file was renamed on any side of history. With followed by the name of the path in the merge commit. Examples for `-c` and `--cc` without `--combined-all-paths`: + ------------------------------------------------ ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM desc.c ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM bar.sh diff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc index ae988a883b5b..d4d576ce665f 100644 --- a/Documentation/git-commit.adoc +++ b/Documentation/git-commit.adoc @@ -281,6 +281,7 @@ variable (see linkgit:git-config[1]). + -- It is a rough equivalent for: + ------ $ git reset --soft HEAD^ $ ... do something else to come up with the right tree ... diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index 6f9763c11b3c..6490d67fab56 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -605,9 +605,11 @@ Marks must be declared (via `mark`) before they can be used. The special case of restarting an incremental import from the current branch value should be written as: + ---- from refs/heads/branch^0 ---- + The `^0` suffix is necessary as fast-import does not permit a branch to start from itself, and the branch is created in memory before the `from` command is even read from the input. Adding `^0` will force diff --git a/Documentation/git-p4.adoc b/Documentation/git-p4.adoc index f97b786bf98a..59edd241341e 100644 --- a/Documentation/git-p4.adoc +++ b/Documentation/git-p4.adoc @@ -66,6 +66,7 @@ Clone ~~~~~ Generally, 'git p4 clone' is used to create a new Git directory from an existing p4 repository: + ------------ $ git p4 clone //depot/path/project ------------ diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index 956d3048f5a6..727160c6db77 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -687,7 +687,7 @@ In addition, the following pairs of options are incompatible: * --fork-point and --root BEHAVIORAL DIFFERENCES ------------------------ +---------------------- `git rebase` has two primary backends: 'apply' and 'merge'. (The 'apply' backend used to be known as the 'am' backend, but the name led to diff --git a/Documentation/git-svn.adoc b/Documentation/git-svn.adoc index bcf7d84a87d1..c26c12bab37a 100644 --- a/Documentation/git-svn.adoc +++ b/Documentation/git-svn.adoc @@ -1012,9 +1012,11 @@ branch. If you do merge, note the following rule: 'git svn dcommit' will attempt to commit on top of the SVN commit named in + ------------------------------------------------------------------------ git log --grep=^git-svn-id: --first-parent -1 ------------------------------------------------------------------------ + You 'must' therefore ensure that the most recent commit of the branch you want to dcommit to is the 'first' parent of the merge. Chaos will ensue otherwise, especially if the first parent is an older commit on diff --git a/Documentation/gitprotocol-http.adoc b/Documentation/gitprotocol-http.adoc index ec40a550ccab..d024010414aa 100644 --- a/Documentation/gitprotocol-http.adoc +++ b/Documentation/gitprotocol-http.adoc @@ -318,7 +318,7 @@ Extra Parameter. Smart Service git-upload-pack ------------------------------- +----------------------------- This service reads from the repository pointed to by `$GIT_URL`. Clients MUST first perform ref discovery with diff --git a/Documentation/gitsubmodules.adoc b/Documentation/gitsubmodules.adoc index f7b5a25a0caa..20822961999a 100644 --- a/Documentation/gitsubmodules.adoc +++ b/Documentation/gitsubmodules.adoc @@ -8,6 +8,7 @@ gitsubmodules - Mounting one repository inside another SYNOPSIS -------- .gitmodules, $GIT_DIR/config + ------------------ git submodule git <command> --recurse-submodules @@ -240,7 +241,7 @@ Workflow for a third party library Workflow for an artificially split repo --------------------------------------- +--------------------------------------- # Enable recursion for relevant commands, such that # regular commands recurse into submodules by default diff --git a/Documentation/lint-delimited-sections.perl b/Documentation/lint-delimited-sections.perl new file mode 100755 index 000000000000..140b852e5d46 --- /dev/null +++ b/Documentation/lint-delimited-sections.perl @@ -0,0 +1,48 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +my $exit_code = 0; +sub report { + my ($msg) = @_; + print STDERR "$ARGV:$.: $msg\n"; + $exit_code = 1; +} + +my $line_length = 0; +my $in_section = 0; +my $section_header = ""; + + +while (my $line = <>) { + if (($line =~ /^\+?$/) || + ($line =~ /^\[.*\]$/) || + ($line =~ /^ifdef::/)) { + $line_length = 0; + } elsif ($line =~ /^[^-.]/) { + $line_length = length($line); + } elsif (($line =~ /^-{3,}$/) || ($line =~ /^\.{3,}$/)) { + if ($in_section) { + if ($line eq $section_header) { + $in_section = 0; + } + next; + } + if ($line_length == 0) { + $in_section = 1; + $section_header = $line; + next; + } + if (($line_length != 0) && (length($line) != $line_length)) { + report("section delimiter not preceded by an empty line"); + } + $line_length = 0; + } +} + +if ($in_section) { + report("section not finished"); +} + +exit $exit_code; diff --git a/Documentation/mergetools/vimdiff.adoc b/Documentation/mergetools/vimdiff.adoc index abfd426f74a0..b4ab83a510e0 100644 --- a/Documentation/mergetools/vimdiff.adoc +++ b/Documentation/mergetools/vimdiff.adoc @@ -3,6 +3,7 @@ Description When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4 windows layout distributed in the following way: + .... ------------------------------------------ | | | | @@ -56,6 +57,7 @@ needed in this case. The next layout definition is equivalent: + -- If, for some reason, we are not interested in the `BASE` buffer. + .... ------------------------------------------ | | | | @@ -72,6 +74,7 @@ If, for some reason, we are not interested in the `BASE` buffer. Only the `MERGED` buffer will be shown. Note, however, that all the other ones are still loaded in vim, and you can access them with the "buffers" command. + .... ------------------------------------------ | | @@ -88,6 +91,7 @@ command. When `MERGED` is not present in the layout, you must "mark" one of the buffers with an arobase (`@`). That will become the buffer you need to edit and save after resolving the conflicts. + .... ------------------------------------------ | | | @@ -106,6 +110,7 @@ save after resolving the conflicts. Three tabs will open: the first one is a copy of the default layout, while the other two only show the differences between (`BASE` and `LOCAL`) and (`BASE` and `REMOTE`) respectively. + .... ------------------------------------------ | <TAB #1> | TAB #2 | TAB #3 | | @@ -119,6 +124,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and | | ------------------------------------------ .... + .... ------------------------------------------ | TAB #1 | <TAB #2> | TAB #3 | | @@ -132,6 +138,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and | | | ------------------------------------------ .... + .... ------------------------------------------ | TAB #1 | TAB #2 | <TAB #3> | | @@ -151,6 +158,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and -- Same as the previous example, but adds a fourth tab with the same information as the first tab, with a different layout. + .... --------------------------------------------- | TAB #1 | TAB #2 | TAB #3 | <TAB #4> | diff --git a/Documentation/technical/long-running-process-protocol.adoc b/Documentation/technical/long-running-process-protocol.adoc index 6f33654b4288..39bd89d467d6 100644 --- a/Documentation/technical/long-running-process-protocol.adoc +++ b/Documentation/technical/long-running-process-protocol.adoc @@ -24,6 +24,7 @@ After the version negotiation Git sends a list of all capabilities that it supports and a flush packet. Git expects to read a list of desired capabilities, which must be a subset of the supported capabilities list, and a flush packet as response: + ------------------------ packet: git> git-filter-client packet: git> version=2 diff --git a/shared.mak b/shared.mak index 1a99848a9517..57095d6cf96c 100644 --- a/shared.mak +++ b/shared.mak @@ -88,6 +88,7 @@ ifndef V QUIET_LINT_GITLINK = @echo ' ' LINT GITLINK $<; QUIET_LINT_MANSEC = @echo ' ' LINT MAN SEC $<; + QUIET_LINT_DELIMSEC = @echo ' ' LINT DEL SEC $<; QUIET_LINT_MANEND = @echo ' ' LINT MAN END $<; export V -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH v2 3/6] doc: check for absence of multiple terms in each entry of desc list 2025-08-05 19:10 ` [PATCH v2 " Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 2/6] doc: check well-formedness of delimited sections Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 ` Jean-Noël Avila via GitGitGadget 2025-08-05 20:30 ` [-SPAM-] " Ramsay Jones 2025-08-06 1:02 ` Collin Funk 2025-08-05 19:10 ` [PATCH v2 4/6] doc: check for absence of the form --[no-]parameter Jean-Noël Avila via GitGitGadget ` (3 subsequent siblings) 6 siblings, 2 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> Due to portability issues, the script generate-configlist.sh was fixed to not use carriage returns in the output. However, the result is that it no longer correctly handles multiple terms in a single entry of the definition list. We now check that these entries do not exist in the documentation. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/Makefile | 10 +++++++++ Documentation/git-check-attr.adoc | 3 ++- Documentation/git-check-ignore.adoc | 9 +++++--- Documentation/git-http-fetch.adoc | 4 +++- Documentation/lint-documentation-style.perl | 24 +++++++++++++++++++++ Documentation/technical/api-path-walk.adoc | 5 ++++- shared.mak | 1 + 7 files changed, 50 insertions(+), 6 deletions(-) create mode 100755 Documentation/lint-documentation-style.perl diff --git a/Documentation/Makefile b/Documentation/Makefile index 76a9e1d02b26..ac8a21e3015c 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -508,6 +508,15 @@ $(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.ado .PHONY: lint-docs-delimited-sections lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) +## Lint: Documentation style +LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(MAN_TXT)) +$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl +$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc + $(call mkdir_p_parent_template) + $(QUIET_LINT_DOCSTYLE)$(PERL_PATH) lint-documentation-style.perl $< >$@ +.PHONY: lint-docs-doc-style +lint-docs-doc-style: $(LINT_DOCS_DOC_STYLE) + lint-docs-manpages: $(QUIET_GEN)./lint-manpages.sh @@ -537,6 +546,7 @@ lint-docs: lint-docs-gitlink lint-docs: lint-docs-man-end-blurb lint-docs: lint-docs-man-section-order lint-docs: lint-docs-delimited-sections +lint-docs: lint-docs-doc-style lint-docs: lint-docs-manpages lint-docs: lint-docs-meson diff --git a/Documentation/git-check-attr.adoc b/Documentation/git-check-attr.adoc index 503b6446574d..15a37a38e3f7 100644 --- a/Documentation/git-check-attr.adoc +++ b/Documentation/git-check-attr.adoc @@ -19,7 +19,8 @@ For every pathname, this command will list if each attribute is 'unspecified', OPTIONS ------- --a, --all:: +-a:: +--all:: List all attributes that are associated with the specified paths. If this option is used, then 'unspecified' attributes will not be included in the output. diff --git a/Documentation/git-check-ignore.adoc b/Documentation/git-check-ignore.adoc index 3e3b4e344629..a6c6c1b6e5be 100644 --- a/Documentation/git-check-ignore.adoc +++ b/Documentation/git-check-ignore.adoc @@ -25,11 +25,13 @@ subject to exclude rules; but see `--no-index'. OPTIONS ------- --q, --quiet:: +-q:: +--quiet:: Don't output anything, just set exit status. This is only valid with a single pathname. --v, --verbose:: +-v:: +--verbose:: Instead of printing the paths that are excluded, for each path that matches an exclude pattern, print the exclude pattern together with the path. (Matching an exclude pattern usually @@ -49,7 +51,8 @@ linkgit:gitignore[5]. below). If `--stdin` is also given, input paths are separated with a NUL character instead of a linefeed character. --n, --non-matching:: +-n:: +--non-matching:: Show given paths which don't match any pattern. This only makes sense when `--verbose` is enabled, otherwise it would not be possible to distinguish between paths which match a diff --git a/Documentation/git-http-fetch.adoc b/Documentation/git-http-fetch.adoc index 4ec7c68d3b9e..dcb05890aefd 100644 --- a/Documentation/git-http-fetch.adoc +++ b/Documentation/git-http-fetch.adoc @@ -25,8 +25,10 @@ commit-id:: Either the hash or the filename under [URL]/refs/ to pull. --a, -c, -t:: +-a::-c:: +-t:: These options are ignored for historical reasons. + -v:: Report what is downloaded. diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl new file mode 100755 index 000000000000..1f35a6a116da --- /dev/null +++ b/Documentation/lint-documentation-style.perl @@ -0,0 +1,24 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +my $exit_code = 0; +sub report { + my ($line, $msg) = @_; + chomp $line; + print STDERR "$ARGV:$.: '$line' $msg\n"; + $exit_code = 1; +} + +my $synopsis_style = 0; + +while (my $line = <>) { + if ($line =~ /^[ \t]*`?[-a-z0-9.]+`?(, `?[-a-z0-9.]+`?)+(::|;;)$/) { + + report($line, "multiple parameters in a definition list item"); + } +} + + +exit $exit_code; diff --git a/Documentation/technical/api-path-walk.adoc b/Documentation/technical/api-path-walk.adoc index 34c905eb9c31..a67de1b143ab 100644 --- a/Documentation/technical/api-path-walk.adoc +++ b/Documentation/technical/api-path-walk.adoc @@ -39,7 +39,10 @@ It is also important that you do not specify the `--objects` flag for the the objects will be walked in a separate way based on those starting commits. -`commits`, `blobs`, `trees`, `tags`:: +`commits`:: +`blobs`:: +`trees`:: +`tags`:: By default, these members are enabled and signal that the path-walk API should call the `path_fn` on objects of these types. Specialized applications could disable some options to make it simpler to walk diff --git a/shared.mak b/shared.mak index 57095d6cf96c..5c7bc9478544 100644 --- a/shared.mak +++ b/shared.mak @@ -89,6 +89,7 @@ ifndef V QUIET_LINT_GITLINK = @echo ' ' LINT GITLINK $<; QUIET_LINT_MANSEC = @echo ' ' LINT MAN SEC $<; QUIET_LINT_DELIMSEC = @echo ' ' LINT DEL SEC $<; + QUIET_LINT_DOCSTYLE = @echo ' ' LINT DOCSTYLE $<; QUIET_LINT_MANEND = @echo ' ' LINT MAN END $<; export V -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [-SPAM-] [PATCH v2 3/6] doc: check for absence of multiple terms in each entry of desc list 2025-08-05 19:10 ` [PATCH v2 3/6] doc: check for absence of multiple terms in each entry of desc list Jean-Noël Avila via GitGitGadget @ 2025-08-05 20:30 ` Ramsay Jones 2025-08-08 13:00 ` Jean-Noël AVILA 2025-08-06 1:02 ` Collin Funk 1 sibling, 1 reply; 28+ messages in thread From: Ramsay Jones @ 2025-08-05 20:30 UTC (permalink / raw) To: Jean-Noël Avila via GitGitGadget, git; +Cc: Jean-Noël Avila On 05/08/2025 20:10, Jean-Noël Avila via GitGitGadget wrote: > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> > > Due to portability issues, the script generate-configlist.sh was fixed to > not use carriage returns in the output. However, the result is that it no > longer correctly handles multiple terms in a single entry of the definition > list. > > We now check that these entries do not exist in the documentation. > > Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> > --- > Documentation/Makefile | 10 +++++++++ > Documentation/git-check-attr.adoc | 3 ++- > Documentation/git-check-ignore.adoc | 9 +++++--- > Documentation/git-http-fetch.adoc | 4 +++- > Documentation/lint-documentation-style.perl | 24 +++++++++++++++++++++ > Documentation/technical/api-path-walk.adoc | 5 ++++- > shared.mak | 1 + > 7 files changed, 50 insertions(+), 6 deletions(-) > create mode 100755 Documentation/lint-documentation-style.perl > > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 76a9e1d02b26..ac8a21e3015c 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -508,6 +508,15 @@ $(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.ado > .PHONY: lint-docs-delimited-sections > lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) > > +## Lint: Documentation style > +LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(MAN_TXT)) > +$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl > +$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc > + $(call mkdir_p_parent_template) > + $(QUIET_LINT_DOCSTYLE)$(PERL_PATH) lint-documentation-style.perl $< >$@ > +.PHONY: lint-docs-doc-style > +lint-docs-doc-style: $(LINT_DOCS_DOC_STYLE) > + > lint-docs-manpages: > $(QUIET_GEN)./lint-manpages.sh > > @@ -537,6 +546,7 @@ lint-docs: lint-docs-gitlink > lint-docs: lint-docs-man-end-blurb > lint-docs: lint-docs-man-section-order > lint-docs: lint-docs-delimited-sections > +lint-docs: lint-docs-doc-style > lint-docs: lint-docs-manpages > lint-docs: lint-docs-meson > > diff --git a/Documentation/git-check-attr.adoc b/Documentation/git-check-attr.adoc > index 503b6446574d..15a37a38e3f7 100644 > --- a/Documentation/git-check-attr.adoc > +++ b/Documentation/git-check-attr.adoc > @@ -19,7 +19,8 @@ For every pathname, this command will list if each attribute is 'unspecified', > > OPTIONS > ------- > --a, --all:: > +-a:: > +--all:: > List all attributes that are associated with the specified > paths. If this option is used, then 'unspecified' attributes > will not be included in the output. > diff --git a/Documentation/git-check-ignore.adoc b/Documentation/git-check-ignore.adoc > index 3e3b4e344629..a6c6c1b6e5be 100644 > --- a/Documentation/git-check-ignore.adoc > +++ b/Documentation/git-check-ignore.adoc > @@ -25,11 +25,13 @@ subject to exclude rules; but see `--no-index'. > > OPTIONS > ------- > --q, --quiet:: > +-q:: > +--quiet:: > Don't output anything, just set exit status. This is only > valid with a single pathname. > > --v, --verbose:: > +-v:: > +--verbose:: > Instead of printing the paths that are excluded, for each path > that matches an exclude pattern, print the exclude pattern > together with the path. (Matching an exclude pattern usually > @@ -49,7 +51,8 @@ linkgit:gitignore[5]. > below). If `--stdin` is also given, input paths are separated > with a NUL character instead of a linefeed character. > > --n, --non-matching:: > +-n:: > +--non-matching:: > Show given paths which don't match any pattern. This only > makes sense when `--verbose` is enabled, otherwise it would > not be possible to distinguish between paths which match a > diff --git a/Documentation/git-http-fetch.adoc b/Documentation/git-http-fetch.adoc > index 4ec7c68d3b9e..dcb05890aefd 100644 > --- a/Documentation/git-http-fetch.adoc > +++ b/Documentation/git-http-fetch.adoc > @@ -25,8 +25,10 @@ commit-id:: > Either the hash or the filename under [URL]/refs/ to > pull. > > --a, -c, -t:: > +-a::-c:: > +-t:: s/-a::-c::/-a:: -c::/ ? ATB, Ramsay Jones ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [-SPAM-] [PATCH v2 3/6] doc: check for absence of multiple terms in each entry of desc list 2025-08-05 20:30 ` [-SPAM-] " Ramsay Jones @ 2025-08-08 13:00 ` Jean-Noël AVILA 0 siblings, 0 replies; 28+ messages in thread From: Jean-Noël AVILA @ 2025-08-08 13:00 UTC (permalink / raw) To: Jean-Noël Avila via GitGitGadget, git, Ramsay Jones On Tuesday, 5 August 2025 22:30:23 CEST Ramsay Jones wrote: > On 05/08/2025 20:10, Jean-Noël Avila via GitGitGadget wrote: > > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> > > > > Due to portability issues, the script generate-configlist.sh was fixed to > > not use carriage returns in the output. However, the result is that it no > > longer correctly handles multiple terms in a single entry of the definition > > list. > > > > We now check that these entries do not exist in the documentation. > > > > Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> > > --- > > > > Documentation/Makefile | 10 +++++++++ > > Documentation/git-check-attr.adoc | 3 ++- > > Documentation/git-check-ignore.adoc | 9 +++++--- > > Documentation/git-http-fetch.adoc | 4 +++- > > Documentation/lint-documentation-style.perl | 24 +++++++++++++++++++++ > > Documentation/technical/api-path-walk.adoc | 5 ++++- > > shared.mak | 1 + > > 7 files changed, 50 insertions(+), 6 deletions(-) > > create mode 100755 Documentation/lint-documentation-style.perl > > > > diff --git a/Documentation/Makefile b/Documentation/Makefile > > index 76a9e1d02b26..ac8a21e3015c 100644 > > --- a/Documentation/Makefile > > +++ b/Documentation/Makefile > > @@ -508,6 +508,15 @@ $(LINT_DOCS_DELIMITED_SECTIONS): > > .build/lint-docs/delimited-sections/%.ok: %.ado> > > .PHONY: lint-docs-delimited-sections > > lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) > > > > +## Lint: Documentation style > > +LINT_DOCS_DOC_STYLE = $(patsubst > > %.adoc,.build/lint-docs/doc-style/%.ok,$(MAN_TXT)) +$ (LINT_DOCS_DOC_STYLE): > > lint-documentation-style.perl > > +$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc > > + $(call mkdir_p_parent_template) > > + $(QUIET_LINT_DOCSTYLE)$(PERL_PATH) lint-documentation-style.perl $< >$@ > > +.PHONY: lint-docs-doc-style > > +lint-docs-doc-style: $(LINT_DOCS_DOC_STYLE) > > + > > > > lint-docs-manpages: > > $(QUIET_GEN)./lint-manpages.sh > > > > @@ -537,6 +546,7 @@ lint-docs: lint-docs-gitlink > > > > lint-docs: lint-docs-man-end-blurb > > lint-docs: lint-docs-man-section-order > > lint-docs: lint-docs-delimited-sections > > > > +lint-docs: lint-docs-doc-style > > > > lint-docs: lint-docs-manpages > > lint-docs: lint-docs-meson > > > > diff --git a/Documentation/git-check-attr.adoc > > b/Documentation/git-check-attr.adoc > > index 503b6446574d..15a37a38e3f7 100644 > > --- a/Documentation/git-check-attr.adoc > > +++ b/Documentation/git-check-attr.adoc > > @@ -19,7 +19,8 @@ For every pathname, this command will list if each attribute is > > 'unspecified',> > > OPTIONS > > ------- > > > > --a, --all:: > > +-a:: > > > > +--all:: > > List all attributes that are associated with the specified > > paths. If this option is used, then 'unspecified' attributes > > will not be included in the output. > > > > diff --git a/Documentation/git-check-ignore.adoc > > b/Documentation/git-check-ignore.adoc index 3e3b4e344629..a6c6c1b6e5be 100644 > > --- a/Documentation/git-check-ignore.adoc > > +++ b/Documentation/git-check-ignore.adoc > > @@ -25,11 +25,13 @@ subject to exclude rules; but see `--no-index'. > > > > OPTIONS > > ------- > > > > --q, --quiet:: > > +-q:: > > > > +--quiet:: > > Don't output anything, just set exit status. This is only > > valid with a single pathname. > > > > --v, --verbose:: > > +-v:: > > > > +--verbose:: > > Instead of printing the paths that are excluded, for each path > > that matches an exclude pattern, print the exclude pattern > > together with the path. (Matching an exclude pattern usually > > > > @@ -49,7 +51,8 @@ linkgit:gitignore[5]. > > > > below). If `--stdin` is also given, input paths are separated > > with a NUL character instead of a linefeed character. > > > > --n, --non-matching:: > > +-n:: > > > > +--non-matching:: > > Show given paths which don't match any pattern. This only > > makes sense when `--verbose` is enabled, otherwise it would > > not be possible to distinguish between paths which match a > > > > diff --git a/Documentation/git-http-fetch.adoc > > b/Documentation/git-http-fetch.adoc > > index 4ec7c68d3b9e..dcb05890aefd 100644 > > --- a/Documentation/git-http-fetch.adoc > > +++ b/Documentation/git-http-fetch.adoc > > > > @@ -25,8 +25,10 @@ commit-id:: > > Either the hash or the filename under [URL]/refs/ to > > pull. > > > > --a, -c, -t:: > > +-a::-c:: > > > +-t:: > s/-a::-c::/-a:: > -c::/ ? > > ATB, > Ramsay Jones Yep, the newline is inserted too late. Thank you for the review. Will reroll in a couple days. Jean-Noël Avila ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 3/6] doc: check for absence of multiple terms in each entry of desc list 2025-08-05 19:10 ` [PATCH v2 3/6] doc: check for absence of multiple terms in each entry of desc list Jean-Noël Avila via GitGitGadget 2025-08-05 20:30 ` [-SPAM-] " Ramsay Jones @ 2025-08-06 1:02 ` Collin Funk 2025-08-08 21:52 ` Jean-Noël AVILA 1 sibling, 1 reply; 28+ messages in thread From: Collin Funk @ 2025-08-06 1:02 UTC (permalink / raw) To: Jean-Noël Avila via GitGitGadget; +Cc: git, Jean-Noël Avila Hi, "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> > > Due to portability issues, the script generate-configlist.sh was fixed to > not use carriage returns in the output. However, the result is that it no > longer correctly handles multiple terms in a single entry of the definition > list. > > We now check that these entries do not exist in the documentation. > > Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> > --- > Documentation/Makefile | 10 +++++++++ > Documentation/git-check-attr.adoc | 3 ++- > Documentation/git-check-ignore.adoc | 9 +++++--- > Documentation/git-http-fetch.adoc | 4 +++- > Documentation/lint-documentation-style.perl | 24 +++++++++++++++++++++ > Documentation/technical/api-path-walk.adoc | 5 ++++- > shared.mak | 1 + > 7 files changed, 50 insertions(+), 6 deletions(-) > create mode 100755 Documentation/lint-documentation-style.perl I documented that this was the correct way to format them in CodingGuidelines. At the time I commented that there were some places that didn't follow this rule. Junio replied [1]: > We are updating them gradually while avoiding collisions with > patches that do other "real" work; see many recent patches to > Documentation/config/ area by Jean-Noël Avila for more, e.g. > d30c5cc4 (doc: convert git-mergetool options to new synopsis style, > 2025-05-25). As long as he is okay with the change, this looks good to me. It isn't that many changes, so hopefully it is. :) Small nit, but the issue was '\n' not being interpreted as a newline in sed's s command. Mentioning carriage return makes me think of '\r'. Reviewed-by: Collin Funk <collin.funk1@gmail.com> Collin ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 3/6] doc: check for absence of multiple terms in each entry of desc list 2025-08-06 1:02 ` Collin Funk @ 2025-08-08 21:52 ` Jean-Noël AVILA 0 siblings, 0 replies; 28+ messages in thread From: Jean-Noël AVILA @ 2025-08-08 21:52 UTC (permalink / raw) To: Jean-Noël Avila via GitGitGadget, Collin Funk; +Cc: git On Wednesday, 6 August 2025 03:02:04 CEST Collin Funk wrote: > Hi, > > "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes: > > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> > > > > Due to portability issues, the script generate-configlist.sh was fixed to > > not use carriage returns in the output. However, the result is that it no > > longer correctly handles multiple terms in a single entry of the definition > > list. > > > > We now check that these entries do not exist in the documentation. > > > > Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> > > --- > > > > Documentation/Makefile | 10 +++++++++ > > Documentation/git-check-attr.adoc | 3 ++- > > Documentation/git-check-ignore.adoc | 9 +++++--- > > Documentation/git-http-fetch.adoc | 4 +++- > > Documentation/lint-documentation-style.perl | 24 +++++++++++++++++++++ > > Documentation/technical/api-path-walk.adoc | 5 ++++- > > shared.mak | 1 + > > 7 files changed, 50 insertions(+), 6 deletions(-) > > create mode 100755 Documentation/lint-documentation-style.perl > > I documented that this was the correct way to format them in > CodingGuidelines. At the time I commented that there were some places > > that didn't follow this rule. Junio replied [1]: > > We are updating them gradually while avoiding collisions with > > patches that do other "real" work; see many recent patches to > > Documentation/config/ area by Jean-Noël Avila for more, e.g. > > d30c5cc4 (doc: convert git-mergetool options to new synopsis style, > > 2025-05-25). > > As long as he is okay with the change, this looks good to me. It isn't > that many changes, so hopefully it is. :) > > Small nit, but the issue was '\n' not being interpreted as a newline in > sed's s command. Mentioning carriage return makes me think of '\r'. > > Reviewed-by: Collin Funk <collin.funk1@gmail.com> > > Collin As a matter of fact, the script did not check config description files, but only root man pages. Will also push this change in the next iteration. Thanks Jean-Noël ^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH v2 4/6] doc: check for absence of the form --[no-]parameter 2025-08-05 19:10 ` [PATCH v2 " Jean-Noël Avila via GitGitGadget ` (2 preceding siblings ...) 2025-08-05 19:10 ` [PATCH v2 3/6] doc: check for absence of multiple terms in each entry of desc list Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 ` Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 5/6] doc:git-for-each-ref: fix styling and typos Jean-Noël Avila via GitGitGadget ` (2 subsequent siblings) 6 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> For better searchability, this commit adds a check to ensure that parameters expressed in the form of `--[no-]parameter` are not used in the documentation. In the place of such parameters, the documentation should list two separate parameters: `--parameter` and `--no-parameter`. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/blame-options.adoc | 3 ++- Documentation/diff-options.adoc | 3 ++- Documentation/fetch-options.adoc | 15 +++++++---- Documentation/git-am.adoc | 3 ++- Documentation/git-backfill.adoc | 3 ++- Documentation/git-cat-file.adoc | 6 +++-- Documentation/git-check-ref-format.adoc | 3 ++- Documentation/git-clone.adoc | 12 ++++++--- Documentation/git-commit-graph.adoc | 3 ++- Documentation/git-commit.adoc | 3 ++- Documentation/git-config.adoc | 3 ++- Documentation/git-difftool.adoc | 9 ++++--- Documentation/git-fast-import.adoc | 3 ++- Documentation/git-fmt-merge-msg.adoc | 3 ++- Documentation/git-format-patch.adoc | 12 ++++++--- Documentation/git-fsck.adoc | 9 ++++--- Documentation/git-gc.adoc | 6 +++-- Documentation/git-index-pack.adoc | 3 ++- Documentation/git-log.adoc | 6 +++-- Documentation/git-merge-tree.adoc | 3 ++- Documentation/git-multi-pack-index.adoc | 3 ++- Documentation/git-pack-objects.adoc | 3 ++- Documentation/git-pull.adoc | 3 ++- Documentation/git-push.adoc | 18 ++++++++----- Documentation/git-range-diff.adoc | 3 ++- Documentation/git-read-tree.adoc | 3 ++- Documentation/git-reset.adoc | 3 ++- Documentation/git-send-email.adoc | 30 ++++++++++++++------- Documentation/git-send-pack.adoc | 3 ++- Documentation/git-submodule.adoc | 6 +++-- Documentation/git-update-index.adoc | 12 ++++++--- Documentation/git-upload-pack.adoc | 3 ++- Documentation/git-worktree.adoc | 12 ++++++--- Documentation/lint-documentation-style.perl | 3 +++ Documentation/merge-options.adoc | 3 ++- Documentation/scalar.adoc | 18 ++++++++----- 36 files changed, 159 insertions(+), 78 deletions(-) diff --git a/Documentation/blame-options.adoc b/Documentation/blame-options.adoc index 19ea1872388f..1fb948fc76f3 100644 --- a/Documentation/blame-options.adoc +++ b/Documentation/blame-options.adoc @@ -75,7 +75,8 @@ include::line-range-format.adoc[] iso format is used. For supported values, see the discussion of the --date option at linkgit:git-log[1]. ---[no-]progress:: +--progress:: +--no-progress:: Progress status is reported on the standard error stream by default when it is attached to a terminal. This flag enables progress reporting even if not attached to a diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc index f3a35d81411f..f19b85142f4e 100644 --- a/Documentation/diff-options.adoc +++ b/Documentation/diff-options.adoc @@ -505,7 +505,8 @@ endif::git-format-patch[] Turn off rename detection, even when the configuration file gives the default to do so. -`--[no-]rename-empty`:: +`--rename-empty`:: +`--no-rename-empty`:: Whether to use empty blobs as rename source. ifndef::git-format-patch[] diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc index b01372e4b3c6..d3ac31f4e2a1 100644 --- a/Documentation/fetch-options.adoc +++ b/Documentation/fetch-options.adoc @@ -1,4 +1,5 @@ ---[no-]all:: +--all:: +--no-all:: Fetch all remotes, except for the ones that has the `remote.<name>.skipFetchAll` configuration variable set. This overrides the configuration variable fetch.all`. @@ -88,7 +89,8 @@ This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes precedence over the `fetch.output` config option. ifndef::git-pull[] ---[no-]write-fetch-head:: +--write-fetch-head:: +--no-write-fetch-head:: Write the list of remote refs fetched in the `FETCH_HEAD` file directly under `$GIT_DIR`. This is the default. Passing `--no-write-fetch-head` from the command line tells @@ -118,13 +120,16 @@ ifndef::git-pull[] Allow several <repository> and <group> arguments to be specified. No <refspec>s may be specified. ---[no-]auto-maintenance:: ---[no-]auto-gc:: +--auto-maintenance:: +--no-auto-maintenance:: +--auto-gc:: +--no-auto-gc:: Run `git maintenance run --auto` at the end to perform automatic repository maintenance if needed. (`--[no-]auto-gc` is a synonym.) This is enabled by default. ---[no-]write-commit-graph:: +--write-commit-graph:: +--no-write-commit-graph:: Write a commit-graph after fetching. This overrides the config setting `fetch.writeCommitGraph`. endif::git-pull[] diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc index 221070de4812..b23b4fba2013 100644 --- a/Documentation/git-am.adoc +++ b/Documentation/git-am.adoc @@ -48,7 +48,8 @@ OPTIONS --keep-non-patch:: Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). ---[no-]keep-cr:: +--keep-cr:: +--no-keep-cr:: With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) with the same option, to prevent it from stripping CR at the end of lines. `am.keepcr` configuration variable can be used to specify the diff --git a/Documentation/git-backfill.adoc b/Documentation/git-backfill.adoc index 95623051f789..b8394dcf22b6 100644 --- a/Documentation/git-backfill.adoc +++ b/Documentation/git-backfill.adoc @@ -57,7 +57,8 @@ OPTIONS blobs seen at a given path. The default minimum batch size is 50,000. -`--[no-]sparse`:: +`--sparse`:: +`--no-sparse`:: Only download objects if they appear at a path that matches the current sparse-checkout. If the sparse-checkout feature is enabled, then `--sparse` is assumed and can be disabled with `--no-sparse`. diff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc index 180d1ad363fd..c139f55a168d 100644 --- a/Documentation/git-cat-file.adoc +++ b/Documentation/git-cat-file.adoc @@ -62,8 +62,10 @@ OPTIONS or to ask for a "blob" with `<object>` being a tag object that points at it. ---[no-]mailmap:: ---[no-]use-mailmap:: +--mailmap:: +--no-mailmap:: +--use-mailmap:: +--no-use-mailmap:: Use mailmap file to map author, committer and tagger names and email addresses to canonical real names and email addresses. See linkgit:git-shortlog[1]. diff --git a/Documentation/git-check-ref-format.adoc b/Documentation/git-check-ref-format.adoc index 2aacfd18088d..0c3abf914657 100644 --- a/Documentation/git-check-ref-format.adoc +++ b/Documentation/git-check-ref-format.adoc @@ -98,7 +98,8 @@ a branch. OPTIONS ------- ---[no-]allow-onelevel:: +--allow-onelevel:: +--no-allow-onelevel:: Controls whether one-level refnames are accepted (i.e., refnames that do not contain multiple `/`-separated components). The default is `--no-allow-onelevel`. diff --git a/Documentation/git-clone.adoc b/Documentation/git-clone.adoc index 222d558290ed..031b56f09824 100644 --- a/Documentation/git-clone.adoc +++ b/Documentation/git-clone.adoc @@ -272,7 +272,8 @@ corresponding `--mirror` and `--no-tags` options instead. reachable from a specified remote branch or tag. This option can be specified multiple times. -`--[no-]single-branch`:: +`--single-branch`:: +`--no-single-branch`:: Clone only the history leading to the tip of a single branch, either specified by the `--branch` option or the primary branch remote's `HEAD` points at. @@ -282,7 +283,8 @@ corresponding `--mirror` and `--no-tags` options instead. branch when `--single-branch` clone was made, no remote-tracking branch is created. -`--[no-]tags`:: +`--tags`:: +`--no-tags`:: Control whether or not tags will be cloned. When `--no-tags` is given, the option will be become permanent by setting the `remote.<remote>.tagOpt=--no-tags` configuration. This ensures that @@ -313,10 +315,12 @@ the clone is finished. This option is ignored if the cloned repository does not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) -`--[no-]shallow-submodules`:: +`--shallow-submodules`:: +`--no-shallow-submodules`:: All submodules which are cloned will be shallow with a depth of 1. -`--[no-]remote-submodules`:: +`--remote-submodules`:: +`--no-remote-submodules`:: All submodules which are cloned will use the status of the submodule's remote-tracking branch to update the submodule, rather than the superproject's recorded SHA-1. Equivalent to passing `--remote` to diff --git a/Documentation/git-commit-graph.adoc b/Documentation/git-commit-graph.adoc index 50b50168045c..e9558173c001 100644 --- a/Documentation/git-commit-graph.adoc +++ b/Documentation/git-commit-graph.adoc @@ -34,7 +34,8 @@ OPTIONS object directory, `git commit-graph ...` will exit with non-zero status. ---[no-]progress:: +--progress:: +--no-progress:: Turn progress on/off explicitly. If neither is specified, progress is shown if standard error is connected to a terminal. diff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc index d4d576ce665f..54c207ad45ea 100644 --- a/Documentation/git-commit.adoc +++ b/Documentation/git-commit.adoc @@ -214,7 +214,8 @@ include::signoff-option.adoc[] each trailer would appear, and other details. `-n`:: -`--[no-]verify`:: +`--verify`:: +`--no-verify`:: Bypass the `pre-commit` and `commit-msg` hooks. See also linkgit:githooks[5]. diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc index 511b2e26bfb0..36d28451528e 100644 --- a/Documentation/git-config.adoc +++ b/Documentation/git-config.adoc @@ -295,7 +295,8 @@ Valid `<type>`'s include: When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---[no-]includes:: +--includes:: +--no-includes:: Respect `include.*` directives in config files when looking up values. Defaults to `off` when a specific file is given (e.g., using `--file`, `--global`, etc) and `on` when searching all diff --git a/Documentation/git-difftool.adoc b/Documentation/git-difftool.adoc index d596205eaf3b..064bc683471f 100644 --- a/Documentation/git-difftool.adoc +++ b/Documentation/git-difftool.adoc @@ -77,7 +77,8 @@ with custom merge tool commands and has the same value as `$MERGED`. --tool-help:: Print a list of diff tools that may be used with `--tool`. ---[no-]symlinks:: +--symlinks:: +--no-symlinks:: 'git difftool''s default behavior is to create symlinks to the working tree when run in `--dir-diff` mode and the right-hand side of the comparison yields the same content as the file in @@ -94,7 +95,8 @@ instead. `--no-symlinks` is the default on Windows. Additionally, `$BASE` is set in the environment. -g:: ---[no-]gui:: +--gui:: +--no-gui:: When 'git-difftool' is invoked with the `-g` or `--gui` option the default diff tool will be read from the configured `diff.guitool` variable instead of `diff.tool`. This may be @@ -104,7 +106,8 @@ instead. `--no-symlinks` is the default on Windows. fallback in the order of `merge.guitool`, `diff.tool`, `merge.tool` until a tool is found. ---[no-]trust-exit-code:: +--trust-exit-code:: +--no-trust-exit-code:: Errors reported by the diff tool are ignored by default. Use `--trust-exit-code` to make 'git-difftool' exit when an invoked diff tool returns a non-zero exit code. diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index 6490d67fab56..3144ffcdb689 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -111,7 +111,8 @@ Locations of Marks Files Like --import-marks but instead of erroring out, silently skips the file if it does not exist. ---[no-]relative-marks:: +--relative-marks:: +--no-relative-marks:: After specifying --relative-marks the paths specified with --import-marks= and --export-marks= are relative to an internal directory in the current repository. diff --git a/Documentation/git-fmt-merge-msg.adoc b/Documentation/git-fmt-merge-msg.adoc index 0f3328956dfd..6d91620be979 100644 --- a/Documentation/git-fmt-merge-msg.adoc +++ b/Documentation/git-fmt-merge-msg.adoc @@ -35,7 +35,8 @@ OPTIONS Do not list one-line descriptions from the actual commits being merged. ---[no-]summary:: +--summary:: +--no-summary:: Synonyms to --log and --no-log; these are deprecated and will be removed in the future. diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc index a8b53db9a663..048d1b981524 100644 --- a/Documentation/git-format-patch.adoc +++ b/Documentation/git-format-patch.adoc @@ -295,7 +295,8 @@ header). Note also that `git send-email` already handles this transformation for you, and this option should not be used if you are feeding the result to `git send-email`. ---[no-]force-in-body-from:: +--force-in-body-from:: +--no-force-in-body-from:: With the e-mail sender specified via the `--from` option, by default, an in-body "From:" to identify the real author of the commit is added at the top of the commit log message if @@ -314,7 +315,8 @@ feeding the result to `git send-email`. `Cc:`, and custom) headers added so far from config or command line. ---[no-]cover-letter:: +--cover-letter:: +--no-cover-letter:: In addition to the patches, generate a cover letter file containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out. @@ -379,7 +381,8 @@ configuration options in linkgit:git-notes[1] to use this workflow). The default is `--no-notes`, unless the `format.notes` configuration is set. ---[no-]signature=<signature>:: +--signature=<signature>:: +--no-signature:: Add a signature to each message produced. Per RFC 3676 the signature is separated from the body by a line with '-- ' on it. If the signature option is omitted the signature defaults to the Git version @@ -411,7 +414,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. Output an all-zero hash in each patch's From header instead of the hash of the commit. ---[no-]base[=<commit>]:: +--no-base:: +--base[=<commit>]:: Record the base tree information to identify the state the patch series applies to. See the BASE TREE INFORMATION section below for details. If <commit> is "auto", a base commit is diff --git a/Documentation/git-fsck.adoc b/Documentation/git-fsck.adoc index 11203ba925c7..1751f692d42b 100644 --- a/Documentation/git-fsck.adoc +++ b/Documentation/git-fsck.adoc @@ -31,7 +31,8 @@ index file, all SHA-1 references in the `refs` namespace, and all reflogs Print out objects that exist but that aren't reachable from any of the reference nodes. ---[no-]dangling:: +--dangling:: +--no-dangling:: Print objects that exist but that are never 'directly' used (default). `--no-dangling` can be used to omit this information from the output. @@ -97,14 +98,16 @@ care about this output and want to speed it up further. compatible with linkgit:git-rev-parse[1], e.g. `HEAD@{1234567890}~25^2:src/`. ---[no-]progress:: +--progress:: +--no-progress:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless --no-progress or --verbose is specified. --progress forces progress status even if the standard error stream is not directed to a terminal. ---[no-]references:: +--references:: +--no-references:: Control whether to check the references database consistency via 'git refs verify'. See linkgit:git-refs[1] for details. The default is to check the references database. diff --git a/Documentation/git-gc.adoc b/Documentation/git-gc.adoc index 526ce01463d7..6fed646dd883 100644 --- a/Documentation/git-gc.adoc +++ b/Documentation/git-gc.adoc @@ -53,11 +53,13 @@ configuration options such as `gc.auto` and `gc.autoPackLimit`, all other housekeeping tasks (e.g. rerere, working trees, reflog...) will be performed as well. ---[no-]detach:: +--detach:: +--no-detach:: Run in the background if the system supports it. This option overrides the `gc.autoDetach` config. ---[no-]cruft:: +--cruft:: +--no-cruft:: When expiring unreachable objects, pack them separately into a cruft pack instead of storing them as loose objects. `--cruft` is on by default. diff --git a/Documentation/git-index-pack.adoc b/Documentation/git-index-pack.adoc index 270056cf6352..18036953c06b 100644 --- a/Documentation/git-index-pack.adoc +++ b/Documentation/git-index-pack.adoc @@ -36,7 +36,8 @@ OPTIONS fails if the name of packed archive does not end with .pack). ---[no-]rev-index:: +--rev-index:: +--no-rev-index:: When this flag is provided, generate a reverse index (a `.rev` file) corresponding to the given pack. If `--verify` is given, ensure that the existing diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc index b6f3d92c435f..e304739c5e80 100644 --- a/Documentation/git-log.adoc +++ b/Documentation/git-log.adoc @@ -73,8 +73,10 @@ used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`, Print out the ref name given on the command line by which each commit was reached. -`--[no-]mailmap`:: -`--[no-]use-mailmap`:: +`--mailmap`:: +`--no-mailmap`:: +`--use-mailmap`:: +`--no-use-mailmap`:: Use mailmap file to map author and committer names and email addresses to canonical real names and email addresses. See linkgit:git-shortlog[1]. diff --git a/Documentation/git-merge-tree.adoc b/Documentation/git-merge-tree.adoc index f824eea61f1e..271ab220e8d7 100644 --- a/Documentation/git-merge-tree.adoc +++ b/Documentation/git-merge-tree.adoc @@ -59,7 +59,8 @@ OPTIONS do not list filenames multiple times if they have multiple conflicting stages). ---[no-]messages:: +--messages:: +--no-messages:: Write any informational messages such as "Auto-merging <path>" or CONFLICT notices to the end of stdout. If unspecified, the default is to include these messages if there are merge diff --git a/Documentation/git-multi-pack-index.adoc b/Documentation/git-multi-pack-index.adoc index b6cd0d7f855d..e8073bc27232 100644 --- a/Documentation/git-multi-pack-index.adoc +++ b/Documentation/git-multi-pack-index.adoc @@ -25,7 +25,8 @@ OPTIONS + `<dir>` must be an alternate of the current repository. ---[no-]progress:: +--progress:: +--no-progress:: Turn progress on/off explicitly. If neither is specified, progress is shown if standard error is connected to a terminal. Supported by sub-commands `write`, `verify`, `expire`, and `repack. diff --git a/Documentation/git-pack-objects.adoc b/Documentation/git-pack-objects.adoc index eba014c40615..71b9682485c3 100644 --- a/Documentation/git-pack-objects.adoc +++ b/Documentation/git-pack-objects.adoc @@ -243,7 +243,8 @@ depth is 4095. Add --no-reuse-object if you want to force a uniform compression level on all data no matter the source. ---[no-]sparse:: +--sparse:: +--no-sparse:: Toggle the "sparse" algorithm to determine which objects to include in the pack, when combined with the "--revs" option. This algorithm only walks trees that appear in paths that introduce new objects. diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc index 3f4ecc47301a..48e924a10a40 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -87,7 +87,8 @@ OPTIONS --verbose:: Pass --verbose to git-fetch and git-merge. ---[no-]recurse-submodules[=(yes|on-demand|no)]:: +--recurse-submodules[=(yes|on-demand|no)]:: +--no-recurse-submodules:: This option controls if new commits of populated submodules should be fetched, and if the working trees of active submodules should be updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index d1978650d60a..5f5408e2c01d 100644 --- a/Documentation/git-push.adoc +++ b/Documentation/git-push.adoc @@ -197,7 +197,8 @@ already exists on the remote side. with configuration variable `push.followTags`. For more information, see `push.followTags` in linkgit:git-config[1]. ---[no-]signed:: +--signed:: +--no-signed:: --signed=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be @@ -208,7 +209,8 @@ already exists on the remote side. will also fail if the actual call to `gpg --sign` fails. See linkgit:git-receive-pack[1] for the details on the receiving end. ---[no-]atomic:: +--atomic:: +--no-atomic:: Use an atomic transaction on the remote side if available. Either all refs are updated, or on error, no refs are updated. If the server does not support atomic pushes the push will fail. @@ -232,7 +234,8 @@ already exists on the remote side. repository over ssh, and you do not have the program in a directory on the default $PATH. ---[no-]force-with-lease:: +--force-with-lease:: +--no-force-with-lease:: --force-with-lease=<refname>:: --force-with-lease=<refname>:<expect>:: Usually, "git push" refuses to update a remote ref that is @@ -350,7 +353,8 @@ one branch, use a `+` in front of the refspec to push (e.g `git push origin +master` to force a push to the `master` branch). See the `<refspec>...` section above for details. ---[no-]force-if-includes:: +--force-if-includes:: +--no-force-if-includes:: Force an update only if the tip of the remote-tracking ref has been integrated locally. + @@ -377,7 +381,8 @@ Specifying `--no-force-if-includes` disables this behavior. linkgit:git-pull[1] and other commands. For more information, see `branch.<name>.merge` in linkgit:git-config[1]. ---[no-]thin:: +--thin:: +--no-thin:: These options are passed to linkgit:git-send-pack[1]. A thin transfer significantly reduces the amount of sent data when the sender and receiver share many of the same objects in common. The default is @@ -419,7 +424,8 @@ When using 'on-demand' or 'only', if a submodule has a "push.recurseSubmodules={on-demand,only}" or "submodule.recurse" configuration, further recursion will occur. In this case, "only" is treated as "on-demand". ---[no-]verify:: +--verify:: +--no-verify:: Toggle the pre-push hook (see linkgit:githooks[5]). The default is --verify, giving the hook a chance to prevent the push. With --no-verify, the hook is bypassed completely. diff --git a/Documentation/git-range-diff.adoc b/Documentation/git-range-diff.adoc index db0e4279b528..b5e85d37f1be 100644 --- a/Documentation/git-range-diff.adoc +++ b/Documentation/git-range-diff.adoc @@ -96,7 +96,8 @@ diff. --remerge-diff:: Convenience option, equivalent to `--diff-merges=remerge`. ---[no-]notes[=<ref>]:: +--notes[=<ref>]:: +--no-notes:: This flag is passed to the `git log` program (see linkgit:git-log[1]) that generates the patches. diff --git a/Documentation/git-read-tree.adoc b/Documentation/git-read-tree.adoc index 1c48c2899630..1c04bba2b7b8 100644 --- a/Documentation/git-read-tree.adoc +++ b/Documentation/git-read-tree.adoc @@ -100,7 +100,8 @@ OPTIONS directories the index file and index output file are located in. ---[no-]recurse-submodules:: +--recurse-submodules:: +--no-recurse-submodules:: Using --recurse-submodules will update the content of all active submodules according to the commit recorded in the superproject by calling read-tree recursively, also setting the submodules' HEAD to be diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc index 50e8a0ba6f66..3b9ba9aee952 100644 --- a/Documentation/git-reset.adoc +++ b/Documentation/git-reset.adoc @@ -90,7 +90,8 @@ but carries forward unmerged index entries. If a file that is different between _<commit>_ and `HEAD` has local changes, reset is aborted. -`--[no-]recurse-submodules`:: +`--recurse-submodules`:: +`--no-recurse-submodules`:: When the working tree is updated, using `--recurse-submodules` will also recursively reset the working tree of all active submodules according to the commit recorded in the superproject, also setting diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc index 5335502d68fc..11b1ab1a070a 100644 --- a/Documentation/git-send-email.adoc +++ b/Documentation/git-send-email.adoc @@ -115,7 +115,8 @@ illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`: Only necessary if `--compose` is also set. If `--compose` is not set, this will be prompted for. ---[no-]outlook-id-fix:: +--outlook-id-fix:: +--no-outlook-id-fix:: Microsoft Outlook SMTP servers discard the Message-ID sent via email and assign a new random Message-ID, thus breaking threads. + @@ -350,7 +351,8 @@ Automating --no-header-cmd:: Disable any header command in use. ---[no-]chain-reply-to:: +--chain-reply-to:: +--no-chain-reply-to:: If this is set, each email will be sent as a reply to the previous email sent. If disabled with `--no-chain-reply-to`, all emails after the first will be sent as replies to the first email sent. When using @@ -364,19 +366,22 @@ Automating values in the `sendemail` section. The default identity is the value of `sendemail.identity`. ---[no-]signed-off-by-cc:: +--signed-off-by-cc:: +--no-signed-off-by-cc:: If this is set, add emails found in the `Signed-off-by` trailer or `Cc:` lines to the cc list. Default is the value of `sendemail.signedOffByCc` configuration value; if that is unspecified, default to `--signed-off-by-cc`. ---[no-]cc-cover:: +--cc-cover:: +--no-cc-cover:: If this is set, emails found in `Cc:` headers in the first patch of the series (typically the cover letter) are added to the cc list for each email set. Default is the value of `sendemail.ccCover` configuration value; if that is unspecified, default to `--no-cc-cover`. ---[no-]to-cover:: +--to-cover:: +--no-to-cover:: If this is set, emails found in `To:` headers in the first patch of the series (typically the cover letter) are added to the to list for each email set. Default is the value of `sendemail.toCover` @@ -407,12 +412,14 @@ Default is the value of `sendemail.suppressCc` configuration value; if that is unspecified, default to `self` if `--suppress-from` is specified, as well as `body` if `--no-signed-off-cc` is specified. ---[no-]suppress-from:: +--suppress-from:: +--no-suppress-from:: If this is set, do not add the `From:` address to the `Cc:` list. Default is the value of `sendemail.suppressFrom` configuration value; if that is unspecified, default to `--no-suppress-from`. ---[no-]thread:: +--thread:: +--no-thread:: If this is set, the `In-Reply-To` and `References` headers will be added to each email sent. Whether each mail refers to the previous email (`deep` threading per `git format-patch` @@ -430,7 +437,8 @@ exists when `git send-email` is asked to add it (especially note that Failure to do so may not produce the expected result in the recipient's MUA. ---[no-]mailmap:: +--mailmap:: +--no-mailmap:: Use the mailmap file (see linkgit:gitmailmap[5]) to map all addresses to their canonical real name and email address. Additional mailmap data specific to `git send-email` may be provided using the @@ -459,7 +467,8 @@ have been specified, in which case default to `compose`. --dry-run:: Do everything except actually send the emails. ---[no-]format-patch:: +--format-patch:: +--no-format-patch:: When an argument may be understood either as a reference or as a file name, choose to understand it as a format-patch argument (`--format-patch`) or as a file name (`--no-format-patch`). By default, when such a conflict @@ -469,7 +478,8 @@ have been specified, in which case default to `compose`. Make `git send-email` less verbose. One line per email should be all that is output. ---[no-]validate:: +--validate:: +--no-validate:: Perform sanity checks on patches. Currently, validation means the following: + diff --git a/Documentation/git-send-pack.adoc b/Documentation/git-send-pack.adoc index b9e73f2e77b1..811193f16c33 100644 --- a/Documentation/git-send-pack.adoc +++ b/Documentation/git-send-pack.adoc @@ -71,7 +71,8 @@ be in a separate packet, and the list must end with a flush packet. fails to update then the entire push will fail without changing any refs. ---[no-]signed:: +--signed:: +--no-signed:: --signed=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be diff --git a/Documentation/git-submodule.adoc b/Documentation/git-submodule.adoc index 87d8e0f0c563..2d6ac92ea450 100644 --- a/Documentation/git-submodule.adoc +++ b/Documentation/git-submodule.adoc @@ -435,7 +435,8 @@ options carefully. clone with a history truncated to the specified number of revisions. See linkgit:git-clone[1] ---[no-]recommend-shallow:: +--recommend-shallow:: +--no-recommend-shallow:: This option is only valid for the update command. The initial clone of a submodule will use the recommended `submodule.<name>.shallow` as provided by the `.gitmodules` file @@ -447,7 +448,8 @@ options carefully. Clone new submodules in parallel with as many jobs. Defaults to the `submodule.fetchJobs` option. ---[no-]single-branch:: +--single-branch:: +--no-single-branch:: This option is only valid for the update command. Clone only one branch during update: HEAD or one specified by --branch. diff --git a/Documentation/git-update-index.adoc b/Documentation/git-update-index.adoc index 7128aed54058..9bea9fab9ad1 100644 --- a/Documentation/git-update-index.adoc +++ b/Documentation/git-update-index.adoc @@ -86,7 +86,8 @@ OPTIONS --chmod=(+|-)x:: Set the execute permissions on the updated files. ---[no-]assume-unchanged:: +--assume-unchanged:: +--no-assume-unchanged:: When this flag is specified, the object names recorded for the paths are not updated. Instead, this option sets/unsets the "assume unchanged" bit for the @@ -108,18 +109,21 @@ you will need to handle the situation manually. Like `--refresh`, but checks stat information unconditionally, without regard to the "assume unchanged" setting. ---[no-]skip-worktree:: +--skip-worktree:: +--no-skip-worktree:: When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "skip-worktree" bit for the paths. See section "Skip-worktree bit" below for more information. ---[no-]ignore-skip-worktree-entries:: +--ignore-skip-worktree-entries:: +--no-ignore-skip-worktree-entries:: Do not remove skip-worktree (AKA "index-only") entries even when the `--remove` option was specified. ---[no-]fsmonitor-valid:: +--fsmonitor-valid:: +--no-fsmonitor-valid:: When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "fsmonitor valid" bit for the paths. See diff --git a/Documentation/git-upload-pack.adoc b/Documentation/git-upload-pack.adoc index 516d1639d9d0..9167a321d08e 100644 --- a/Documentation/git-upload-pack.adoc +++ b/Documentation/git-upload-pack.adoc @@ -25,7 +25,8 @@ repository. For push operations, see 'git send-pack'. OPTIONS ------- ---[no-]strict:: +--strict:: +--no-strict:: Do not try <directory>/.git/ if <directory> is not a Git directory. --timeout=<n>:: diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc index 8340b7f028e6..389e669ac044 100644 --- a/Documentation/git-worktree.adoc +++ b/Documentation/git-worktree.adoc @@ -200,13 +200,15 @@ To remove a locked worktree, specify `--force` twice. With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD" in linkgit:git-checkout[1]. ---[no-]checkout:: +--checkout:: +--no-checkout:: By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can be used to suppress checkout in order to make customizations, such as configuring sparse-checkout. See "Sparse checkout" in linkgit:git-read-tree[1]. ---[no-]guess-remote:: +--guess-remote:: +--no-guess-remote:: With `worktree add <path>`, without `<commit-ish>`, instead of creating a new branch from `HEAD`, if there exists a tracking branch in exactly one remote matching the basename of `<path>`, @@ -216,7 +218,8 @@ To remove a locked worktree, specify `--force` twice. This can also be set up as the default behaviour by using the `worktree.guessRemote` config option. ---[no-]relative-paths:: +--relative-paths:: +--no-relative-paths:: Link worktrees using relative paths or absolute paths (default). Overrides the `worktree.useRelativePaths` config option, see linkgit:git-config[1]. @@ -224,7 +227,8 @@ This can also be set up as the default behaviour by using the With `repair`, the linking files will be updated if there's an absolute/relative mismatch, even if the links are correct. ---[no-]track:: +--track:: +--no-track:: When creating a new branch, if `<commit-ish>` is a branch, mark it as "upstream" from the new branch. This is the default if `<commit-ish>` is a remote-tracking branch. See diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl index 1f35a6a116da..11321a151bca 100755 --- a/Documentation/lint-documentation-style.perl +++ b/Documentation/lint-documentation-style.perl @@ -18,6 +18,9 @@ while (my $line = <>) { report($line, "multiple parameters in a definition list item"); } + if ($line =~ /^`?--\[no-\][a-z0-9-]+.*(::|;;)$/) { + report($line, "definition list item with a `--[no-]` parameter"); + } } diff --git a/Documentation/merge-options.adoc b/Documentation/merge-options.adoc index 95ef491be109..9d433265b298 100644 --- a/Documentation/merge-options.adoc +++ b/Documentation/merge-options.adoc @@ -135,7 +135,8 @@ ifdef::git-pull[] Only useful when merging. endif::git-pull[] -`--[no-]verify`:: +`--verify`:: +`--no-verify`:: By default, the pre-merge and commit-msg hooks are run. When `--no-verify` is given, these are bypassed. See also linkgit:githooks[5]. diff --git a/Documentation/scalar.adoc b/Documentation/scalar.adoc index 4bd5b150e8e1..f81b2832f8df 100644 --- a/Documentation/scalar.adoc +++ b/Documentation/scalar.adoc @@ -71,7 +71,8 @@ HEAD[:<directory>]`. Instead of checking out the branch pointed to by the cloned repository's HEAD, check out the `<name>` branch instead. ---[no-]single-branch:: +--single-branch:: +--no-single-branch:: Clone only the history leading to the tip of a single branch, either specified by the `--branch` option or the primary branch remote's `HEAD` points at. @@ -81,23 +82,27 @@ remote-tracking branch for the branch this option was used for the initial cloning. If the HEAD at the remote did not point at any branch when `--single-branch` clone was made, no remote-tracking branch is created. ---[no-]src:: +--src:: +--no-src:: By default, `scalar clone` places the cloned repository within a `<entlistment>/src` directory. Use `--no-src` to place the cloned repository directly in the `<enlistment>` directory. ---[no-]tags:: +--tags:: +--no-tags:: By default, `scalar clone` will fetch the tag objects advertised by the remote and future `git fetch` commands will do the same. Use `--no-tags` to avoid fetching tags in `scalar clone` and to configure the repository to avoid fetching tags in the future. To fetch tags after cloning with `--no-tags`, run `git fetch --tags`. ---[no-]full-clone:: +--full-clone:: +--no-full-clone:: A sparse-checkout is initialized by default. This behavior can be turned off via `--full-clone`. ---[no-]maintenance:: +--maintenance:: +--no-maintenance:: By default, `scalar clone` configures the enlistment to use Git's background maintenance feature. Use the `--no-maintenance` to skip this configuration. @@ -122,7 +127,8 @@ Note: when this subcommand is called in a worktree that is called `src/`, its parent directory is considered to be the Scalar enlistment. If the worktree is _not_ called `src/`, it itself will be considered to be the Scalar enlistment. ---[no-]maintenance:: +--maintenance:: +--no-maintenance:: By default, `scalar register` configures the enlistment to use Git's background maintenance feature. Use the `--no-maintenance` to skip this configuration. This does not disable any maintenance that may -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH v2 5/6] doc:git-for-each-ref: fix styling and typos 2025-08-05 19:10 ` [PATCH v2 " Jean-Noël Avila via GitGitGadget ` (3 preceding siblings ...) 2025-08-05 19:10 ` [PATCH v2 4/6] doc: check for absence of the form --[no-]parameter Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 ` Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 6/6] doc lint: check that synopsis manpages have synopsis inlines Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget 6 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> This commit fixes the synopsis syntax and changes the wording of a few descriptions to be more consistent with the rest of the documentation. It is a prepartion for the next commit that checks that synopsis style is applied consistently across a manual page. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/git-for-each-ref.adoc | 264 ++++++++++++++-------------- 1 file changed, 132 insertions(+), 132 deletions(-) diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc index 060940904da2..b69080c4a000 100644 --- a/Documentation/git-for-each-ref.adoc +++ b/Documentation/git-for-each-ref.adoc @@ -14,101 +14,98 @@ git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl] [--merged[=<object>]] [--no-merged[=<object>]] [--contains[=<object>]] [--no-contains[=<object>]] [(--exclude=<pattern>)...] [--start-after=<marker>] - [ --stdin | <pattern>... ] + [ --stdin | (<pattern>...)] DESCRIPTION ----------- -Iterate over all refs that match `<pattern>` and show them -according to the given `<format>`, after sorting them according -to the given set of `<key>`. If `<count>` is given, stop after -showing that many refs. The interpolated values in `<format>` +Iterate over all refs that match _<pattern>_ and show them +according to the given _<format>_, after sorting them according +to the given set of _<key>_. If _<count>_ is given, stop after +showing that many refs. The interpolated values in _<format>_ can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language. OPTIONS ------- -<pattern>...:: - If one or more patterns are given, only refs are shown that - match against at least one pattern, either using fnmatch(3) or +`<pattern>...`:: + If one or more _<pattern>_ parameters are given, only refs are shown that + match against at least one pattern, either using `fnmatch`(3) or literally, in the latter case matching completely or from the beginning up to a slash. ---stdin:: - If `--stdin` is supplied, then the list of patterns is read from - standard input instead of from the argument list. +`--stdin`:: + The list of patterns is read from standard input instead of from + the argument list. ---count=<count>:: - By default the command shows all refs that match - `<pattern>`. This option makes it stop after showing - that many refs. +`--count=<count>`:: + Stop after showing _<count>_ refs. ---sort=<key>:: - A field name to sort on. Prefix `-` to sort in +`--sort=<key>`:: + Sort on the field name _<key>_. Prefix `-` to sort in descending order of the value. When unspecified, - `refname` is used. You may use the --sort=<key> option + `refname` is used. You may use the `--sort=<key>` option multiple times, in which case the last key becomes the primary key. ---format=<format>:: +`--format[=<format>]`:: A string that interpolates `%(fieldname)` from a ref being shown and the object it points at. In addition, the string literal `%%` renders as `%` and `%xx` - where `xx` are hex digits - renders as the character with hex code `xx`. For example, `%00` interpolates to - `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF). -+ -When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype) + `\0` (_NUL_), `%09` to `\t` (_TAB_), and `%0a` to `\n` (_LF_). + +When unspecified, _<format>_ defaults to `%(objectname) SPC %(objecttype) TAB %(refname)`. ---color[=<when>]:: +`--color[=<when>]`:: Respect any colors specified in the `--format` option. The - `<when>` field must be one of `always`, `never`, or `auto` (if + _<when__ field must be one of `always`, `never`, or `auto` (if `<when>` is absent, behave as if `always` was given). ---shell:: ---perl:: ---python:: ---tcl:: +`--shell`:: +`--perl`:: +`--python`:: +`--tcl`:: If given, strings that substitute `%(fieldname)` placeholders are quoted as string literals suitable for the specified host language. This is meant to produce - a scriptlet that can directly be `eval`ed. + a scriptlet that can directly be "eval"ed. ---points-at=<object>:: +`--points-at=<object>`:: Only list refs which points at the given object. ---merged[=<object>]:: +`--merged[=<object>]`:: Only list refs whose tips are reachable from the - specified commit (HEAD if not specified). - ---no-merged[=<object>]:: - Only list refs whose tips are not reachable from the - specified commit (HEAD if not specified). + specified commit (`HEAD` if not specified). ---contains[=<object>]:: - Only list refs which contain the specified commit (HEAD if not +`--no-merged[=<object>]`:: + Only list refs whose tips are not reachable from _<object>_(`HEAD` if not specified). ---no-contains[=<object>]:: - Only list refs which don't contain the specified commit (HEAD +`--contains[=<object>]`:: + Only list refs which contain _<object>_(`HEAD` if not specified). + +`--no-contains[=<object>]`:: + Only list refs which don't contain _<object>_ (`HEAD` if not specified). ---ignore-case:: +`--ignore-case`:: Sorting and filtering refs are case insensitive. ---omit-empty:: +`--omit-empty`:: Do not print a newline after formatted refs where the format expands to the empty string. ---exclude=<pattern>:: - If one or more patterns are given, only refs which do not match - any excluded pattern(s) are shown. Matching is done using the - same rules as `<pattern>` above. +`--exclude=<excluded-pattern>`:: + If one or more `--exclude` options are given, only refs which do not + match any _<excluded-pattern>_ parameters are shown. Matching is done + using the same rules as _<pattern>_ above. ---include-root-refs:: - List root refs (HEAD and pseudorefs) apart from regular refs. +`--include-root-refs`:: + List root refs (`HEAD` and pseudorefs) apart from regular refs. ---start-after=<marker>:: +`--start-after=<marker>`:: Allows paginating the output by skipping references up to and including the specified marker. When paging, it should be noted that references may be deleted, modified or added between invocations. Output will only yield those @@ -126,44 +123,44 @@ keys. For all objects, the following names can be used: -refname:: - The name of the ref (the part after $GIT_DIR/). +`refname`:: + The name of the ref (the part after `$GIT_DIR/`). For a non-ambiguous short name of the ref append `:short`. - The option core.warnAmbiguousRefs is used to select the strict - abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>` + The option `core.warnAmbiguousRefs` is used to select the strict + abbreviation mode. If `lstrip=<n>` (`rstrip=<n>`) is appended, strip _<n>_ slash-separated path components from the front (back) of the refname (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`). - If `<N>` is a negative number, strip as many path components as - necessary from the specified end to leave `-<N>` path components + If _<n>_ is a negative number, strip as many path components as + necessary from the specified end to leave `-<n>` path components (e.g. `%(refname:lstrip=-2)` turns `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)` turns `refs/tags/foo` into `refs`). When the ref does not have enough components, the result becomes an empty string if - stripping with positive <N>, or it becomes the full refname if - stripping with negative <N>. Neither is an error. + stripping with positive _<n>_, or it becomes the full refname if + stripping with negative _<N>_. Neither is an error. + `strip` can be used as a synonym to `lstrip`. -objecttype:: +`objecttype`:: The type of the object (`blob`, `tree`, `commit`, `tag`). -objectsize:: +`objectsize`:: The size of the object (the same as 'git cat-file -s' reports). Append `:disk` to get the size, in bytes, that the object takes up on - disk. See the note about on-disk sizes in the `CAVEATS` section below. -objectname:: + disk. See the note about on-disk sizes in the 'CAVEATS' section below. +`objectname`:: The object name (aka SHA-1). For a non-ambiguous abbreviation of the object name append `:short`. For an abbreviation of the object name with desired length append - `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The + `:short=<length>`, where the minimum length is `MINIMUM_ABBREV`. The length may be exceeded to ensure unique object names. -deltabase:: +`deltabase`:: This expands to the object name of the delta base for the given object, if it is stored as a delta. Otherwise it expands to the null object name (all zeroes). -upstream:: +`upstream`:: The name of a local ref which can be considered ``upstream'' from the displayed ref. Respects `:short`, `:lstrip` and `:rstrip` in the same way as `refname` above. Additionally @@ -185,100 +182,103 @@ Has no effect if the ref does not have tracking information associated with it. All the options apart from `nobracket` are mutually exclusive, but if used together the last option is selected. -push:: +`push`:: The name of a local ref which represents the `@{push}` location for the displayed ref. Respects `:short`, `:lstrip`, `:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref` options as `upstream` does. Produces an empty string if no `@{push}` ref is configured. -HEAD:: - '*' if HEAD matches current ref (the checked out branch), ' ' +`HEAD`:: + `*` if `HEAD` matches current ref (the checked out branch), ' ' otherwise. -color:: +`color`:: Change output color. Followed by `:<colorname>`, where color names are described under Values in the "CONFIGURATION FILE" section of linkgit:git-config[1]. For example, `%(color:bold red)`. -align:: +`align`:: Left-, middle-, or right-align the content between - %(align:...) and %(end). The "align:" is followed by + `%(align:...)` and `%(end)`. The "`align:`" is followed by `width=<width>` and `position=<position>` in any order - separated by a comma, where the `<position>` is either left, - right or middle, default being left and `<width>` is the total + separated by a comma, where the _<position>_ is either `left`, + `right` or `middle`, default being `left` and _<width>_ is the total length of the content with alignment. For brevity, the "width=" and/or "position=" prefixes may be omitted, and bare - <width> and <position> used instead. For instance, + _<width>_ and _<position>_ used instead. For instance, `%(align:<width>,<position>)`. If the contents length is more than the width then no alignment is performed. If used with - `--quote` everything in between %(align:...) and %(end) is + `--quote` everything in between `%(align:...)` and `%(end)` is quoted, but if nested then only the topmost level performs quoting. -if:: - Used as %(if)...%(then)...%(end) or - %(if)...%(then)...%(else)...%(end). If there is an atom with - value or string literal after the %(if) then everything after - the %(then) is printed, else if the %(else) atom is used, then +`if`:: + Used as `%(if)...%(then)...%(end)` or + `%(if)...%(then)...%(else)...%(end)`. If there is an atom with + value or string literal after the `%(if)` then everything after + the `%(then)` is printed, else if the `%(else)` atom is used, then everything after %(else) is printed. We ignore space when - evaluating the string before %(then), this is useful when we - use the %(HEAD) atom which prints either "*" or " " and we - want to apply the 'if' condition only on the 'HEAD' ref. - Append ":equals=<string>" or ":notequals=<string>" to compare - the value between the %(if:...) and %(then) atoms with the + evaluating the string before `%(then)`, this is useful when we + use the `%(HEAD)` atom which prints either "`*`" or " " and we + want to apply the 'if' condition only on the `HEAD` ref. + Append "`:equals=<string>`" or "`:notequals=<string>`" to compare + the value between the `%(if:...)` and `%(then)` atoms with the given string. -symref:: +`symref`:: The ref which the given symbolic ref refers to. If not a symbolic ref, nothing is printed. Respects the `:short`, `:lstrip` and `:rstrip` options in the same way as `refname` above. -signature:: +`signature`:: The GPG signature of a commit. -signature:grade:: - Show "G" for a good (valid) signature, "B" for a bad - signature, "U" for a good signature with unknown validity, "X" - for a good signature that has expired, "Y" for a good - signature made by an expired key, "R" for a good signature - made by a revoked key, "E" if the signature cannot be - checked (e.g. missing key) and "N" for no signature. - -signature:signer:: +`signature:grade`:: + Show +`G`;; for a good (valid) signature +`B`;; for a bad signature +`U`;; for a good signature with unknown validity +`X`;; for a good signature that has expired +`Y`;; for a good signature made by an expired key +`R`;; for a good signature made by a revoked key +`E`;; if the signature cannot be checked (e.g. missing key) +`N`;; for no signature. + +`signature:signer`:: The signer of the GPG signature of a commit. -signature:key:: +`signature:key`:: The key of the GPG signature of a commit. -signature:fingerprint:: +`signature:fingerprint`:: The fingerprint of the GPG signature of a commit. -signature:primarykeyfingerprint:: +`signature:primarykeyfingerprint`:: The primary key fingerprint of the GPG signature of a commit. -signature:trustlevel:: +`signature:trustlevel`:: The trust level of the GPG signature of a commit. Possible outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`. -worktreepath:: +`worktreepath`:: The absolute path to the worktree in which the ref is checked out, if it is checked out in any linked worktree. Empty string otherwise. -ahead-behind:<committish>:: +`ahead-behind:<commit-ish>`:: Two integers, separated by a space, demonstrating the number of commits ahead and behind, respectively, when comparing the output - ref to the `<committish>` specified in the format. + ref to the _<committish>_ specified in the format. -is-base:<committish>:: - In at most one row, `(<committish>)` will appear to indicate the ref +`is-base:<commit-ish>`:: + In at most one row, `(<commit-ish>)` will appear to indicate the ref that is most likely the ref used as a starting point for the branch - that produced `<committish>`. This choice is made using a heuristic: + that produced _<commit-ish>_. This choice is made using a heuristic: choose the ref that minimizes the number of commits in the - first-parent history of `<committish>` and not in the first-parent + first-parent history of _<commit-ish>_ and not in the first-parent history of the ref. + For example, consider the following figure of first-parent histories of @@ -312,29 +312,29 @@ common first-parent ancestor of `B` and `C` and ties are broken by the earliest ref in the sorted order. + Note that this token will not appear if the first-parent history of -`<committish>` does not intersect the first-parent histories of the +_<commit-ish>_ does not intersect the first-parent histories of the filtered refs. -describe[:options]:: +`describe[:<option>,...]`:: A human-readable name, like linkgit:git-describe[1]; empty string for undescribable commits. The `describe` string may be followed by a colon and one or more comma-separated options. + -- -tags=<bool-value>;; +`tags=<bool-value>`;; Instead of only considering annotated tags, consider lightweight tags as well; see the corresponding option in linkgit:git-describe[1] for details. -abbrev=<number>;; - Use at least <number> hexadecimal digits; see the corresponding +`abbrev=<number>`;; + Use at least _<number>_ hexadecimal digits; see the corresponding option in linkgit:git-describe[1] for details. -match=<pattern>;; - Only consider tags matching the given `glob(7)` pattern, - excluding the "refs/tags/" prefix; see the corresponding option +`match=<pattern>`;; + Only consider tags matching the `glob`(7) _<pattern>_, + excluding the `refs/tags/` prefix; see the corresponding option in linkgit:git-describe[1] for details. -exclude=<pattern>;; - Do not consider tags matching the given `glob(7)` pattern, - excluding the "refs/tags/" prefix; see the corresponding option +`exclude=<pattern>`;; + Do not consider tags matching the `glob`(7) _<pattern>_, + excluding the `refs/tags/` prefix; see the corresponding option in linkgit:git-describe[1] for details. -- @@ -366,7 +366,7 @@ variable (see linkgit:gitmailmap[5]). The raw data in an object is `raw`. -raw:size:: +`raw:size`:: The raw data size of the object. Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`, @@ -376,10 +376,10 @@ variable type. The message in a commit or a tag object is `contents`, from which `contents:<part>` can be used to extract various parts out of: -contents:size:: +`contents:size`:: The size in bytes of the commit or tag message. -contents:subject:: +`contents:subject`:: The first paragraph of the message, which typically is a single line, is taken as the "subject" of the commit or the tag message. @@ -387,19 +387,19 @@ contents:subject:: obtain same results. `:sanitize` can be appended to `subject` for subject line suitable for filename. -contents:body:: +`contents:body`:: The remainder of the commit or the tag message that follows the "subject". -contents:signature:: +`contents:signature`:: The optional GPG signature of the tag. -contents:lines=N:: - The first `N` lines of the message. +`contents:lines=<n>`:: + The first _<n>_ lines of the message. Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1] -are obtained as `trailers[:options]` (or by using the historical alias -`contents:trailers[:options]`). For valid [:option] values see `trailers` +are obtained as `trailers[:<option>,...]` (or by using the historical alias +`contents:trailers[:<option>,...]`). For valid _<option>_ values see `trailers` section of linkgit:git-log[1]. For sorting purposes, fields with numeric values sort in numeric order @@ -419,8 +419,8 @@ option to linkgit:git-rev-list[1] takes). If this formatting is provided in a `--sort` key, references will be sorted according to the byte-value of the formatted string rather than the numeric value of the underlying timestamp. -Some atoms like %(align) and %(if) always require a matching %(end). -We call them "opening atoms" and sometimes denote them as %($open). +Some atoms like `%(align)` and `%(if)` always require a matching `%(end)`. +We call them "opening atoms" and sometimes denote them as `%($open)`. When a scripting language specific quoting is in effect, everything between a top-level opening atom and its matching %(end) is evaluated @@ -438,7 +438,7 @@ An example directly producing formatted text. Show the most recent #!/bin/sh git for-each-ref --count=3 --sort='-*authordate' \ ---format='From: %(*authorname) %(*authoremail) +`--format='From: %(*authorname) %(*authoremail) Subject: %(*subject) Date: %(*authordate) Ref: %(*refname) @@ -449,7 +449,7 @@ Ref: %(*refname) A simple example showing the use of shell eval on the output, -demonstrating the use of --shell. List the prefixes of all heads: +demonstrating the use of `--shell`. List the prefixes of all heads: ------------ #!/bin/sh @@ -517,7 +517,7 @@ eval "$eval" ------------ -An example to show the usage of %(if)...%(then)...%(else)...%(end). +An example to show the usage of `%(if)...%(then)...%(else)...%(end)`. This prefixes the current branch with a star. ------------ @@ -525,7 +525,7 @@ git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" ------------ -An example to show the usage of %(if)...%(then)...%(end). +An example to show the usage of `%(if)...%(then)...%(end)`. This prints the authorname, if present. ------------ -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH v2 6/6] doc lint: check that synopsis manpages have synopsis inlines 2025-08-05 19:10 ` [PATCH v2 " Jean-Noël Avila via GitGitGadget ` (4 preceding siblings ...) 2025-08-05 19:10 ` [PATCH v2 5/6] doc:git-for-each-ref: fix styling and typos Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 ` Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget 6 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-05 19:10 UTC (permalink / raw) To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> When switching manpages to the synopsis style, the description lists of options need to be switched to inline synopsis for proper formatting. This is done by enclosing the option name in double backticks, e.g. `--option`. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/git-checkout.adoc | 2 +- Documentation/git-refs.adoc | 20 ++++++++++---------- Documentation/lint-documentation-style.perl | 6 ++++++ 3 files changed, 17 insertions(+), 11 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index 40e02cfd6562..ff1cb29bc1f8 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -334,7 +334,7 @@ include::diff-context-options.adoc[] separated with _NUL_ character and all other characters are taken literally (including newlines and quotes). -<branch>:: +`<branch>`:: Branch to checkout; if it refers to a branch (i.e., a name that, when prepended with "refs/heads/", is a valid ref), then that branch is checked out. Otherwise, if it refers to a valid diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc index 4d6dc994f92e..5d26de8acb22 100644 --- a/Documentation/git-refs.adoc +++ b/Documentation/git-refs.adoc @@ -20,41 +20,41 @@ This command provides low-level access to refs. COMMANDS -------- -migrate:: +`migrate`:: Migrate ref store between different formats. -verify:: +`verify`:: Verify reference database consistency. OPTIONS ------- -The following options are specific to 'git refs migrate': +The following options are specific to `git refs migrate`: ---ref-format=<format>:: +`--ref-format=<format>`:: The ref format to migrate the ref store to. Can be one of: + include::ref-storage-format.adoc[] ---dry-run:: +`--dry-run`:: Perform the migration, but do not modify the repository. The migrated refs will be written into a separate directory that can be inspected separately. The name of the directory will be reported on stdout. This can be used to double check that the migration works as expected before performing the actual migration. ---reflog:: ---no-reflog:: +`--reflog`:: +`--no-reflog`:: Choose between migrating the reflog data to the new backend, and discarding them. The default is "--reflog", to migrate. -The following options are specific to 'git refs verify': +The following options are specific to `git refs verify`: ---strict:: +`--strict`:: Enable stricter error checking. This will cause warnings to be reported as errors. See linkgit:git-fsck[1]. ---verbose:: +`--verbose`:: When verifying the reference database consistency, be chatty. KNOWN LIMITATIONS diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl index 11321a151bca..d7ab7322939e 100755 --- a/Documentation/lint-documentation-style.perl +++ b/Documentation/lint-documentation-style.perl @@ -21,6 +21,12 @@ while (my $line = <>) { if ($line =~ /^`?--\[no-\][a-z0-9-]+.*(::|;;)$/) { report($line, "definition list item with a `--[no-]` parameter"); } + if ($line =~ /^\[synopsis\]$/) { + $synopsis_style = 1; + } + if (($line =~ /^(-[-a-z].*|<[-a-z0-9]+>(\.{3})?)(::|;;)$/) && ($synopsis_style)) { + report($line, "synopsis style and definition list item not backquoted"); + } } -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH v3 0/6] Introduce more doc linting 2025-08-05 19:10 ` [PATCH v2 " Jean-Noël Avila via GitGitGadget ` (5 preceding siblings ...) 2025-08-05 19:10 ` [PATCH v2 6/6] doc lint: check that synopsis manpages have synopsis inlines Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 ` Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget ` (6 more replies) 6 siblings, 7 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 UTC (permalink / raw) To: git; +Cc: Ramsay Jones, Collin Funk, Jean-Noël Avila Reviewing the documentation part of the last patches, it turns out that the majority of my comments are related to the latest documentation guidelines which are both easy to forget and almost trivial to automatically check. This series implements the automatic tests for basic doc rules. At the moment it conflicts with "[GSoC][PATCH v6 0/6] Add refs list subcommand" and possibly with "[PATCH v4 0/9] refs: fix migration of reflog entries" Changes since v1: * fix a small typo Changes since v2: * extend range of check files for multiple entries in definition list entries * extend checks for new synopsis styles Jean-Noël Avila (6): doc: test linkgit macros for well-formedness doc: check well-formedness of delimited sections doc: check for absence of multiple terms in each entry of desc list doc: check for absence of the form --[no-]parameter doc:git-for-each-ref: fix styling and typos doc lint: check that synopsis manpages have synopsis inlines Documentation/Makefile | 21 +- Documentation/RelNotes/1.6.2.4.adoc | 1 + Documentation/blame-options.adoc | 3 +- Documentation/diff-format.adoc | 1 + Documentation/diff-options.adoc | 3 +- Documentation/fetch-options.adoc | 15 +- Documentation/git-am.adoc | 3 +- Documentation/git-backfill.adoc | 3 +- Documentation/git-cat-file.adoc | 6 +- Documentation/git-check-attr.adoc | 3 +- Documentation/git-check-ignore.adoc | 9 +- Documentation/git-check-ref-format.adoc | 3 +- Documentation/git-checkout.adoc | 2 +- Documentation/git-clone.adoc | 12 +- Documentation/git-commit-graph.adoc | 3 +- Documentation/git-commit.adoc | 4 +- Documentation/git-config.adoc | 3 +- Documentation/git-difftool.adoc | 9 +- Documentation/git-fast-import.adoc | 5 +- Documentation/git-fmt-merge-msg.adoc | 3 +- Documentation/git-for-each-ref.adoc | 264 +++++++++--------- Documentation/git-format-patch.adoc | 12 +- Documentation/git-fsck.adoc | 9 +- Documentation/git-gc.adoc | 6 +- Documentation/git-http-fetch.adoc | 5 +- Documentation/git-index-pack.adoc | 3 +- Documentation/git-log.adoc | 6 +- Documentation/git-merge-tree.adoc | 3 +- Documentation/git-multi-pack-index.adoc | 3 +- Documentation/git-p4.adoc | 1 + Documentation/git-pack-objects.adoc | 3 +- Documentation/git-pull.adoc | 3 +- Documentation/git-push.adoc | 18 +- Documentation/git-range-diff.adoc | 3 +- Documentation/git-read-tree.adoc | 3 +- Documentation/git-rebase.adoc | 2 +- Documentation/git-refs.adoc | 20 +- Documentation/git-reset.adoc | 3 +- Documentation/git-send-email.adoc | 30 +- Documentation/git-send-pack.adoc | 3 +- Documentation/git-submodule.adoc | 6 +- Documentation/git-svn.adoc | 2 + Documentation/git-update-index.adoc | 12 +- Documentation/git-upload-pack.adoc | 3 +- Documentation/git-worktree.adoc | 12 +- Documentation/gitprotocol-http.adoc | 2 +- Documentation/gitsubmodules.adoc | 3 +- Documentation/gitweb.conf.adoc | 2 +- Documentation/lint-delimited-sections.perl | 48 ++++ Documentation/lint-documentation-style.perl | 33 +++ Documentation/lint-gitlink.perl | 7 + Documentation/merge-options.adoc | 3 +- Documentation/mergetools/vimdiff.adoc | 8 + Documentation/scalar.adoc | 18 +- Documentation/technical/api-path-walk.adoc | 5 +- .../long-running-process-protocol.adoc | 1 + shared.mak | 2 + 57 files changed, 447 insertions(+), 232 deletions(-) create mode 100755 Documentation/lint-delimited-sections.perl create mode 100755 Documentation/lint-documentation-style.perl base-commit: 112648dd6bdd8e4f485cd0ae11636807959d48be Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1945%2Fjnavila%2Fdoc_linting-v3 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1945/jnavila/doc_linting-v3 Pull-Request: https://github.com/gitgitgadget/git/pull/1945 Range-diff vs v2: 1: e79bd6a67ef = 1: e79bd6a67ef doc: test linkgit macros for well-formedness 2: 322df2d8dde = 2: 322df2d8dde doc: check well-formedness of delimited sections 3: 5806390052b ! 3: 4e0178218e8 doc: check for absence of multiple terms in each entry of desc list @@ Metadata ## Commit message ## doc: check for absence of multiple terms in each entry of desc list - Due to portability issues, the script generate-configlist.sh was fixed to - not use carriage returns in the output. However, the result is that it no - longer correctly handles multiple terms in a single entry of the definition - list. + For simplifying automated translation of the documentation, it is better to + only present one term in each entry of a description list of options. This + is because most of these terms can automatically be marked as + notranslatable. - We now check that these entries do not exist in the documentation. + Also, due to portability issues, the script generate-configlist.sh can no + longer insert newlines in the output. However, the result is that it no + longer correctly handles multiple terms in a single entry of definition + lists. + As a result, we now check that these entries do not exist in the + documentation. + + Reviewed-by: Collin Funk <collin.funk1@gmail.com> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> ## Documentation/Makefile ## @@ Documentation/Makefile: $(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimi lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) +## Lint: Documentation style -+LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(MAN_TXT)) ++LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(DOC_DEP_TXT)) +$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl +$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc + $(call mkdir_p_parent_template) @@ Documentation/git-http-fetch.adoc: commit-id:: pull. --a, -c, -t:: -+-a::-c:: ++-a:: ++-c:: +-t:: These options are ignored for historical reasons. + 4: 03a8428849f = 4: 2b43e196ec0 doc: check for absence of the form --[no-]parameter 5: 713c86dae92 = 5: c32e74fad94 doc:git-for-each-ref: fix styling and typos 6: d57478ea5cd = 6: 8ec969fe4bd doc lint: check that synopsis manpages have synopsis inlines -- gitgitgadget ^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH v3 1/6] doc: test linkgit macros for well-formedness 2025-08-11 20:53 ` [PATCH v3 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 ` Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 2/6] doc: check well-formedness of delimited sections Jean-Noël Avila via GitGitGadget ` (5 subsequent siblings) 6 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 UTC (permalink / raw) To: git; +Cc: Ramsay Jones, Collin Funk, Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> Some readers of man pages have reported that they found malformed linkgit macros in the documentation (absence or bad spelling). Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/gitweb.conf.adoc | 2 +- Documentation/lint-gitlink.perl | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/Documentation/gitweb.conf.adoc b/Documentation/gitweb.conf.adoc index 1348e9b12504..64bebb811c97 100644 --- a/Documentation/gitweb.conf.adoc +++ b/Documentation/gitweb.conf.adoc @@ -178,7 +178,7 @@ $export_ok:: Show repository only if this file exists (in repository). Only effective if this variable evaluates to true. Can be set when building gitweb by setting `GITWEB_EXPORT_OK`. This path is - relative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok', + relative to `GIT_DIR`. linkgit:git-daemon[1] uses 'git-daemon-export-ok', unless started with `--export-all`. By default this variable is not set, which means that this feature is turned off. diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl index aea564dad7ed..f183a18df284 100755 --- a/Documentation/lint-gitlink.perl +++ b/Documentation/lint-gitlink.perl @@ -41,6 +41,13 @@ die "BUG: No list of valid linkgit:* files given" unless @ARGV; @ARGV = $to_check; while (<>) { my $line = $_; + while ($line =~ m/(.{,8})((git[-a-z]+|scalar)\[(\d)*\])/g) { + my $pos = pos $line; + my ($macro, $target, $page, $section) = ($1, $2, $3, $4); + if ( $macro ne "linkgit:" && $macro !~ "ifn?def::" && $macro ne "endif::" ) { + report($pos, $line, $target, "linkgit: macro expected"); + } + } while ($line =~ m/linkgit:((.*?)\[(\d)\])/g) { my $pos = pos $line; my ($target, $page, $section) = ($1, $2, $3); -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH v3 2/6] doc: check well-formedness of delimited sections 2025-08-11 20:53 ` [PATCH v3 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 ` Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 3/6] doc: check for absence of multiple terms in each entry of desc list Jean-Noël Avila via GitGitGadget ` (4 subsequent siblings) 6 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 UTC (permalink / raw) To: git; +Cc: Ramsay Jones, Collin Funk, Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> Having an empty line before each delimited sections is not required by asciidoc, but it is a safety measure that prevents generating malformed asciidoc when generating translated documentation. When a delimited section appears just after a paragraph, the asciidoc processor checks that the length of the delimited section header is different from the length of the paragraph. If it is not, the asciidoc processor will generate a title. In the original English documentation, this is not a problem because the authors always check the output of the asciidoc processor and fix the length of the delimited section header if it turns out to be the same as the paragraph length. However, this is not the case for translations, where the authors have no way to check the length of the delimited section header or the output of the asciidoc processor. This can lead to a section title that is not intended. Indeed, this test also checks that titles are correctly formed, that is, the length of the underline is equal to the length of the title (otherwise it would not be a title but a section header). Finally, this test checks that the delimited section are terminated within the same file. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/Makefile | 11 ++++- Documentation/RelNotes/1.6.2.4.adoc | 1 + Documentation/diff-format.adoc | 1 + Documentation/git-commit.adoc | 1 + Documentation/git-fast-import.adoc | 2 + Documentation/git-p4.adoc | 1 + Documentation/git-rebase.adoc | 2 +- Documentation/git-svn.adoc | 2 + Documentation/gitprotocol-http.adoc | 2 +- Documentation/gitsubmodules.adoc | 3 +- Documentation/lint-delimited-sections.perl | 48 +++++++++++++++++++ Documentation/mergetools/vimdiff.adoc | 8 ++++ .../long-running-process-protocol.adoc | 1 + shared.mak | 1 + 14 files changed, 80 insertions(+), 4 deletions(-) create mode 100755 Documentation/lint-delimited-sections.perl diff --git a/Documentation/Makefile b/Documentation/Makefile index df2ce187eb84..76a9e1d02b26 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -497,9 +497,17 @@ $(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.adoc $(call mkdir_p_parent_template) $(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \ ../fsck.h fsck-msgids.adoc $@ - lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) +## Lint: delimited sections +LINT_DOCS_DELIMITED_SECTIONS = $(patsubst %.adoc,.build/lint-docs/delimited-sections/%.ok,$(MAN_TXT)) +$(LINT_DOCS_DELIMITED_SECTIONS): lint-delimited-sections.perl +$(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.adoc + $(call mkdir_p_parent_template) + $(QUIET_LINT_DELIMSEC)$(PERL_PATH) lint-delimited-sections.perl $< >$@ +.PHONY: lint-docs-delimited-sections +lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) + lint-docs-manpages: $(QUIET_GEN)./lint-manpages.sh @@ -528,6 +536,7 @@ lint-docs: lint-docs-fsck-msgids lint-docs: lint-docs-gitlink lint-docs: lint-docs-man-end-blurb lint-docs: lint-docs-man-section-order +lint-docs: lint-docs-delimited-sections lint-docs: lint-docs-manpages lint-docs: lint-docs-meson diff --git a/Documentation/RelNotes/1.6.2.4.adoc b/Documentation/RelNotes/1.6.2.4.adoc index f4bf1d09863c..053dbb604de6 100644 --- a/Documentation/RelNotes/1.6.2.4.adoc +++ b/Documentation/RelNotes/1.6.2.4.adoc @@ -37,3 +37,4 @@ exec >/var/tmp/1 echo O=$(git describe maint) O=v1.6.2.3-38-g318b847 git shortlog --no-merges $O..maint +--- diff --git a/Documentation/diff-format.adoc b/Documentation/diff-format.adoc index 80e36e153dac..9f7e98824183 100644 --- a/Documentation/diff-format.adoc +++ b/Documentation/diff-format.adoc @@ -103,6 +103,7 @@ if the file was renamed on any side of history. With followed by the name of the path in the merge commit. Examples for `-c` and `--cc` without `--combined-all-paths`: + ------------------------------------------------ ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM desc.c ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM bar.sh diff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc index ae988a883b5b..d4d576ce665f 100644 --- a/Documentation/git-commit.adoc +++ b/Documentation/git-commit.adoc @@ -281,6 +281,7 @@ variable (see linkgit:git-config[1]). + -- It is a rough equivalent for: + ------ $ git reset --soft HEAD^ $ ... do something else to come up with the right tree ... diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index 6f9763c11b3c..6490d67fab56 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -605,9 +605,11 @@ Marks must be declared (via `mark`) before they can be used. The special case of restarting an incremental import from the current branch value should be written as: + ---- from refs/heads/branch^0 ---- + The `^0` suffix is necessary as fast-import does not permit a branch to start from itself, and the branch is created in memory before the `from` command is even read from the input. Adding `^0` will force diff --git a/Documentation/git-p4.adoc b/Documentation/git-p4.adoc index f97b786bf98a..59edd241341e 100644 --- a/Documentation/git-p4.adoc +++ b/Documentation/git-p4.adoc @@ -66,6 +66,7 @@ Clone ~~~~~ Generally, 'git p4 clone' is used to create a new Git directory from an existing p4 repository: + ------------ $ git p4 clone //depot/path/project ------------ diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index 956d3048f5a6..727160c6db77 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -687,7 +687,7 @@ In addition, the following pairs of options are incompatible: * --fork-point and --root BEHAVIORAL DIFFERENCES ------------------------ +---------------------- `git rebase` has two primary backends: 'apply' and 'merge'. (The 'apply' backend used to be known as the 'am' backend, but the name led to diff --git a/Documentation/git-svn.adoc b/Documentation/git-svn.adoc index bcf7d84a87d1..c26c12bab37a 100644 --- a/Documentation/git-svn.adoc +++ b/Documentation/git-svn.adoc @@ -1012,9 +1012,11 @@ branch. If you do merge, note the following rule: 'git svn dcommit' will attempt to commit on top of the SVN commit named in + ------------------------------------------------------------------------ git log --grep=^git-svn-id: --first-parent -1 ------------------------------------------------------------------------ + You 'must' therefore ensure that the most recent commit of the branch you want to dcommit to is the 'first' parent of the merge. Chaos will ensue otherwise, especially if the first parent is an older commit on diff --git a/Documentation/gitprotocol-http.adoc b/Documentation/gitprotocol-http.adoc index ec40a550ccab..d024010414aa 100644 --- a/Documentation/gitprotocol-http.adoc +++ b/Documentation/gitprotocol-http.adoc @@ -318,7 +318,7 @@ Extra Parameter. Smart Service git-upload-pack ------------------------------- +----------------------------- This service reads from the repository pointed to by `$GIT_URL`. Clients MUST first perform ref discovery with diff --git a/Documentation/gitsubmodules.adoc b/Documentation/gitsubmodules.adoc index f7b5a25a0caa..20822961999a 100644 --- a/Documentation/gitsubmodules.adoc +++ b/Documentation/gitsubmodules.adoc @@ -8,6 +8,7 @@ gitsubmodules - Mounting one repository inside another SYNOPSIS -------- .gitmodules, $GIT_DIR/config + ------------------ git submodule git <command> --recurse-submodules @@ -240,7 +241,7 @@ Workflow for a third party library Workflow for an artificially split repo --------------------------------------- +--------------------------------------- # Enable recursion for relevant commands, such that # regular commands recurse into submodules by default diff --git a/Documentation/lint-delimited-sections.perl b/Documentation/lint-delimited-sections.perl new file mode 100755 index 000000000000..140b852e5d46 --- /dev/null +++ b/Documentation/lint-delimited-sections.perl @@ -0,0 +1,48 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +my $exit_code = 0; +sub report { + my ($msg) = @_; + print STDERR "$ARGV:$.: $msg\n"; + $exit_code = 1; +} + +my $line_length = 0; +my $in_section = 0; +my $section_header = ""; + + +while (my $line = <>) { + if (($line =~ /^\+?$/) || + ($line =~ /^\[.*\]$/) || + ($line =~ /^ifdef::/)) { + $line_length = 0; + } elsif ($line =~ /^[^-.]/) { + $line_length = length($line); + } elsif (($line =~ /^-{3,}$/) || ($line =~ /^\.{3,}$/)) { + if ($in_section) { + if ($line eq $section_header) { + $in_section = 0; + } + next; + } + if ($line_length == 0) { + $in_section = 1; + $section_header = $line; + next; + } + if (($line_length != 0) && (length($line) != $line_length)) { + report("section delimiter not preceded by an empty line"); + } + $line_length = 0; + } +} + +if ($in_section) { + report("section not finished"); +} + +exit $exit_code; diff --git a/Documentation/mergetools/vimdiff.adoc b/Documentation/mergetools/vimdiff.adoc index abfd426f74a0..b4ab83a510e0 100644 --- a/Documentation/mergetools/vimdiff.adoc +++ b/Documentation/mergetools/vimdiff.adoc @@ -3,6 +3,7 @@ Description When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4 windows layout distributed in the following way: + .... ------------------------------------------ | | | | @@ -56,6 +57,7 @@ needed in this case. The next layout definition is equivalent: + -- If, for some reason, we are not interested in the `BASE` buffer. + .... ------------------------------------------ | | | | @@ -72,6 +74,7 @@ If, for some reason, we are not interested in the `BASE` buffer. Only the `MERGED` buffer will be shown. Note, however, that all the other ones are still loaded in vim, and you can access them with the "buffers" command. + .... ------------------------------------------ | | @@ -88,6 +91,7 @@ command. When `MERGED` is not present in the layout, you must "mark" one of the buffers with an arobase (`@`). That will become the buffer you need to edit and save after resolving the conflicts. + .... ------------------------------------------ | | | @@ -106,6 +110,7 @@ save after resolving the conflicts. Three tabs will open: the first one is a copy of the default layout, while the other two only show the differences between (`BASE` and `LOCAL`) and (`BASE` and `REMOTE`) respectively. + .... ------------------------------------------ | <TAB #1> | TAB #2 | TAB #3 | | @@ -119,6 +124,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and | | ------------------------------------------ .... + .... ------------------------------------------ | TAB #1 | <TAB #2> | TAB #3 | | @@ -132,6 +138,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and | | | ------------------------------------------ .... + .... ------------------------------------------ | TAB #1 | TAB #2 | <TAB #3> | | @@ -151,6 +158,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and -- Same as the previous example, but adds a fourth tab with the same information as the first tab, with a different layout. + .... --------------------------------------------- | TAB #1 | TAB #2 | TAB #3 | <TAB #4> | diff --git a/Documentation/technical/long-running-process-protocol.adoc b/Documentation/technical/long-running-process-protocol.adoc index 6f33654b4288..39bd89d467d6 100644 --- a/Documentation/technical/long-running-process-protocol.adoc +++ b/Documentation/technical/long-running-process-protocol.adoc @@ -24,6 +24,7 @@ After the version negotiation Git sends a list of all capabilities that it supports and a flush packet. Git expects to read a list of desired capabilities, which must be a subset of the supported capabilities list, and a flush packet as response: + ------------------------ packet: git> git-filter-client packet: git> version=2 diff --git a/shared.mak b/shared.mak index 1a99848a9517..57095d6cf96c 100644 --- a/shared.mak +++ b/shared.mak @@ -88,6 +88,7 @@ ifndef V QUIET_LINT_GITLINK = @echo ' ' LINT GITLINK $<; QUIET_LINT_MANSEC = @echo ' ' LINT MAN SEC $<; + QUIET_LINT_DELIMSEC = @echo ' ' LINT DEL SEC $<; QUIET_LINT_MANEND = @echo ' ' LINT MAN END $<; export V -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH v3 3/6] doc: check for absence of multiple terms in each entry of desc list 2025-08-11 20:53 ` [PATCH v3 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 2/6] doc: check well-formedness of delimited sections Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 ` Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 4/6] doc: check for absence of the form --[no-]parameter Jean-Noël Avila via GitGitGadget ` (3 subsequent siblings) 6 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 UTC (permalink / raw) To: git; +Cc: Ramsay Jones, Collin Funk, Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> For simplifying automated translation of the documentation, it is better to only present one term in each entry of a description list of options. This is because most of these terms can automatically be marked as notranslatable. Also, due to portability issues, the script generate-configlist.sh can no longer insert newlines in the output. However, the result is that it no longer correctly handles multiple terms in a single entry of definition lists. As a result, we now check that these entries do not exist in the documentation. Reviewed-by: Collin Funk <collin.funk1@gmail.com> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/Makefile | 10 +++++++++ Documentation/git-check-attr.adoc | 3 ++- Documentation/git-check-ignore.adoc | 9 +++++--- Documentation/git-http-fetch.adoc | 5 ++++- Documentation/lint-documentation-style.perl | 24 +++++++++++++++++++++ Documentation/technical/api-path-walk.adoc | 5 ++++- shared.mak | 1 + 7 files changed, 51 insertions(+), 6 deletions(-) create mode 100755 Documentation/lint-documentation-style.perl diff --git a/Documentation/Makefile b/Documentation/Makefile index 76a9e1d02b26..6fb83d0c6ebf 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -508,6 +508,15 @@ $(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.ado .PHONY: lint-docs-delimited-sections lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) +## Lint: Documentation style +LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(DOC_DEP_TXT)) +$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl +$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc + $(call mkdir_p_parent_template) + $(QUIET_LINT_DOCSTYLE)$(PERL_PATH) lint-documentation-style.perl $< >$@ +.PHONY: lint-docs-doc-style +lint-docs-doc-style: $(LINT_DOCS_DOC_STYLE) + lint-docs-manpages: $(QUIET_GEN)./lint-manpages.sh @@ -537,6 +546,7 @@ lint-docs: lint-docs-gitlink lint-docs: lint-docs-man-end-blurb lint-docs: lint-docs-man-section-order lint-docs: lint-docs-delimited-sections +lint-docs: lint-docs-doc-style lint-docs: lint-docs-manpages lint-docs: lint-docs-meson diff --git a/Documentation/git-check-attr.adoc b/Documentation/git-check-attr.adoc index 503b6446574d..15a37a38e3f7 100644 --- a/Documentation/git-check-attr.adoc +++ b/Documentation/git-check-attr.adoc @@ -19,7 +19,8 @@ For every pathname, this command will list if each attribute is 'unspecified', OPTIONS ------- --a, --all:: +-a:: +--all:: List all attributes that are associated with the specified paths. If this option is used, then 'unspecified' attributes will not be included in the output. diff --git a/Documentation/git-check-ignore.adoc b/Documentation/git-check-ignore.adoc index 3e3b4e344629..a6c6c1b6e5be 100644 --- a/Documentation/git-check-ignore.adoc +++ b/Documentation/git-check-ignore.adoc @@ -25,11 +25,13 @@ subject to exclude rules; but see `--no-index'. OPTIONS ------- --q, --quiet:: +-q:: +--quiet:: Don't output anything, just set exit status. This is only valid with a single pathname. --v, --verbose:: +-v:: +--verbose:: Instead of printing the paths that are excluded, for each path that matches an exclude pattern, print the exclude pattern together with the path. (Matching an exclude pattern usually @@ -49,7 +51,8 @@ linkgit:gitignore[5]. below). If `--stdin` is also given, input paths are separated with a NUL character instead of a linefeed character. --n, --non-matching:: +-n:: +--non-matching:: Show given paths which don't match any pattern. This only makes sense when `--verbose` is enabled, otherwise it would not be possible to distinguish between paths which match a diff --git a/Documentation/git-http-fetch.adoc b/Documentation/git-http-fetch.adoc index 4ec7c68d3b9e..2200f073c471 100644 --- a/Documentation/git-http-fetch.adoc +++ b/Documentation/git-http-fetch.adoc @@ -25,8 +25,11 @@ commit-id:: Either the hash or the filename under [URL]/refs/ to pull. --a, -c, -t:: +-a:: +-c:: +-t:: These options are ignored for historical reasons. + -v:: Report what is downloaded. diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl new file mode 100755 index 000000000000..1f35a6a116da --- /dev/null +++ b/Documentation/lint-documentation-style.perl @@ -0,0 +1,24 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +my $exit_code = 0; +sub report { + my ($line, $msg) = @_; + chomp $line; + print STDERR "$ARGV:$.: '$line' $msg\n"; + $exit_code = 1; +} + +my $synopsis_style = 0; + +while (my $line = <>) { + if ($line =~ /^[ \t]*`?[-a-z0-9.]+`?(, `?[-a-z0-9.]+`?)+(::|;;)$/) { + + report($line, "multiple parameters in a definition list item"); + } +} + + +exit $exit_code; diff --git a/Documentation/technical/api-path-walk.adoc b/Documentation/technical/api-path-walk.adoc index 34c905eb9c31..a67de1b143ab 100644 --- a/Documentation/technical/api-path-walk.adoc +++ b/Documentation/technical/api-path-walk.adoc @@ -39,7 +39,10 @@ It is also important that you do not specify the `--objects` flag for the the objects will be walked in a separate way based on those starting commits. -`commits`, `blobs`, `trees`, `tags`:: +`commits`:: +`blobs`:: +`trees`:: +`tags`:: By default, these members are enabled and signal that the path-walk API should call the `path_fn` on objects of these types. Specialized applications could disable some options to make it simpler to walk diff --git a/shared.mak b/shared.mak index 57095d6cf96c..5c7bc9478544 100644 --- a/shared.mak +++ b/shared.mak @@ -89,6 +89,7 @@ ifndef V QUIET_LINT_GITLINK = @echo ' ' LINT GITLINK $<; QUIET_LINT_MANSEC = @echo ' ' LINT MAN SEC $<; QUIET_LINT_DELIMSEC = @echo ' ' LINT DEL SEC $<; + QUIET_LINT_DOCSTYLE = @echo ' ' LINT DOCSTYLE $<; QUIET_LINT_MANEND = @echo ' ' LINT MAN END $<; export V -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH v3 4/6] doc: check for absence of the form --[no-]parameter 2025-08-11 20:53 ` [PATCH v3 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget ` (2 preceding siblings ...) 2025-08-11 20:53 ` [PATCH v3 3/6] doc: check for absence of multiple terms in each entry of desc list Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 ` Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 5/6] doc:git-for-each-ref: fix styling and typos Jean-Noël Avila via GitGitGadget ` (2 subsequent siblings) 6 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 UTC (permalink / raw) To: git; +Cc: Ramsay Jones, Collin Funk, Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> For better searchability, this commit adds a check to ensure that parameters expressed in the form of `--[no-]parameter` are not used in the documentation. In the place of such parameters, the documentation should list two separate parameters: `--parameter` and `--no-parameter`. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/blame-options.adoc | 3 ++- Documentation/diff-options.adoc | 3 ++- Documentation/fetch-options.adoc | 15 +++++++---- Documentation/git-am.adoc | 3 ++- Documentation/git-backfill.adoc | 3 ++- Documentation/git-cat-file.adoc | 6 +++-- Documentation/git-check-ref-format.adoc | 3 ++- Documentation/git-clone.adoc | 12 ++++++--- Documentation/git-commit-graph.adoc | 3 ++- Documentation/git-commit.adoc | 3 ++- Documentation/git-config.adoc | 3 ++- Documentation/git-difftool.adoc | 9 ++++--- Documentation/git-fast-import.adoc | 3 ++- Documentation/git-fmt-merge-msg.adoc | 3 ++- Documentation/git-format-patch.adoc | 12 ++++++--- Documentation/git-fsck.adoc | 9 ++++--- Documentation/git-gc.adoc | 6 +++-- Documentation/git-index-pack.adoc | 3 ++- Documentation/git-log.adoc | 6 +++-- Documentation/git-merge-tree.adoc | 3 ++- Documentation/git-multi-pack-index.adoc | 3 ++- Documentation/git-pack-objects.adoc | 3 ++- Documentation/git-pull.adoc | 3 ++- Documentation/git-push.adoc | 18 ++++++++----- Documentation/git-range-diff.adoc | 3 ++- Documentation/git-read-tree.adoc | 3 ++- Documentation/git-reset.adoc | 3 ++- Documentation/git-send-email.adoc | 30 ++++++++++++++------- Documentation/git-send-pack.adoc | 3 ++- Documentation/git-submodule.adoc | 6 +++-- Documentation/git-update-index.adoc | 12 ++++++--- Documentation/git-upload-pack.adoc | 3 ++- Documentation/git-worktree.adoc | 12 ++++++--- Documentation/lint-documentation-style.perl | 3 +++ Documentation/merge-options.adoc | 3 ++- Documentation/scalar.adoc | 18 ++++++++----- 36 files changed, 159 insertions(+), 78 deletions(-) diff --git a/Documentation/blame-options.adoc b/Documentation/blame-options.adoc index 19ea1872388f..1fb948fc76f3 100644 --- a/Documentation/blame-options.adoc +++ b/Documentation/blame-options.adoc @@ -75,7 +75,8 @@ include::line-range-format.adoc[] iso format is used. For supported values, see the discussion of the --date option at linkgit:git-log[1]. ---[no-]progress:: +--progress:: +--no-progress:: Progress status is reported on the standard error stream by default when it is attached to a terminal. This flag enables progress reporting even if not attached to a diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc index f3a35d81411f..f19b85142f4e 100644 --- a/Documentation/diff-options.adoc +++ b/Documentation/diff-options.adoc @@ -505,7 +505,8 @@ endif::git-format-patch[] Turn off rename detection, even when the configuration file gives the default to do so. -`--[no-]rename-empty`:: +`--rename-empty`:: +`--no-rename-empty`:: Whether to use empty blobs as rename source. ifndef::git-format-patch[] diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc index b01372e4b3c6..d3ac31f4e2a1 100644 --- a/Documentation/fetch-options.adoc +++ b/Documentation/fetch-options.adoc @@ -1,4 +1,5 @@ ---[no-]all:: +--all:: +--no-all:: Fetch all remotes, except for the ones that has the `remote.<name>.skipFetchAll` configuration variable set. This overrides the configuration variable fetch.all`. @@ -88,7 +89,8 @@ This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes precedence over the `fetch.output` config option. ifndef::git-pull[] ---[no-]write-fetch-head:: +--write-fetch-head:: +--no-write-fetch-head:: Write the list of remote refs fetched in the `FETCH_HEAD` file directly under `$GIT_DIR`. This is the default. Passing `--no-write-fetch-head` from the command line tells @@ -118,13 +120,16 @@ ifndef::git-pull[] Allow several <repository> and <group> arguments to be specified. No <refspec>s may be specified. ---[no-]auto-maintenance:: ---[no-]auto-gc:: +--auto-maintenance:: +--no-auto-maintenance:: +--auto-gc:: +--no-auto-gc:: Run `git maintenance run --auto` at the end to perform automatic repository maintenance if needed. (`--[no-]auto-gc` is a synonym.) This is enabled by default. ---[no-]write-commit-graph:: +--write-commit-graph:: +--no-write-commit-graph:: Write a commit-graph after fetching. This overrides the config setting `fetch.writeCommitGraph`. endif::git-pull[] diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc index 221070de4812..b23b4fba2013 100644 --- a/Documentation/git-am.adoc +++ b/Documentation/git-am.adoc @@ -48,7 +48,8 @@ OPTIONS --keep-non-patch:: Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). ---[no-]keep-cr:: +--keep-cr:: +--no-keep-cr:: With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) with the same option, to prevent it from stripping CR at the end of lines. `am.keepcr` configuration variable can be used to specify the diff --git a/Documentation/git-backfill.adoc b/Documentation/git-backfill.adoc index 95623051f789..b8394dcf22b6 100644 --- a/Documentation/git-backfill.adoc +++ b/Documentation/git-backfill.adoc @@ -57,7 +57,8 @@ OPTIONS blobs seen at a given path. The default minimum batch size is 50,000. -`--[no-]sparse`:: +`--sparse`:: +`--no-sparse`:: Only download objects if they appear at a path that matches the current sparse-checkout. If the sparse-checkout feature is enabled, then `--sparse` is assumed and can be disabled with `--no-sparse`. diff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc index 180d1ad363fd..c139f55a168d 100644 --- a/Documentation/git-cat-file.adoc +++ b/Documentation/git-cat-file.adoc @@ -62,8 +62,10 @@ OPTIONS or to ask for a "blob" with `<object>` being a tag object that points at it. ---[no-]mailmap:: ---[no-]use-mailmap:: +--mailmap:: +--no-mailmap:: +--use-mailmap:: +--no-use-mailmap:: Use mailmap file to map author, committer and tagger names and email addresses to canonical real names and email addresses. See linkgit:git-shortlog[1]. diff --git a/Documentation/git-check-ref-format.adoc b/Documentation/git-check-ref-format.adoc index 2aacfd18088d..0c3abf914657 100644 --- a/Documentation/git-check-ref-format.adoc +++ b/Documentation/git-check-ref-format.adoc @@ -98,7 +98,8 @@ a branch. OPTIONS ------- ---[no-]allow-onelevel:: +--allow-onelevel:: +--no-allow-onelevel:: Controls whether one-level refnames are accepted (i.e., refnames that do not contain multiple `/`-separated components). The default is `--no-allow-onelevel`. diff --git a/Documentation/git-clone.adoc b/Documentation/git-clone.adoc index 222d558290ed..031b56f09824 100644 --- a/Documentation/git-clone.adoc +++ b/Documentation/git-clone.adoc @@ -272,7 +272,8 @@ corresponding `--mirror` and `--no-tags` options instead. reachable from a specified remote branch or tag. This option can be specified multiple times. -`--[no-]single-branch`:: +`--single-branch`:: +`--no-single-branch`:: Clone only the history leading to the tip of a single branch, either specified by the `--branch` option or the primary branch remote's `HEAD` points at. @@ -282,7 +283,8 @@ corresponding `--mirror` and `--no-tags` options instead. branch when `--single-branch` clone was made, no remote-tracking branch is created. -`--[no-]tags`:: +`--tags`:: +`--no-tags`:: Control whether or not tags will be cloned. When `--no-tags` is given, the option will be become permanent by setting the `remote.<remote>.tagOpt=--no-tags` configuration. This ensures that @@ -313,10 +315,12 @@ the clone is finished. This option is ignored if the cloned repository does not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) -`--[no-]shallow-submodules`:: +`--shallow-submodules`:: +`--no-shallow-submodules`:: All submodules which are cloned will be shallow with a depth of 1. -`--[no-]remote-submodules`:: +`--remote-submodules`:: +`--no-remote-submodules`:: All submodules which are cloned will use the status of the submodule's remote-tracking branch to update the submodule, rather than the superproject's recorded SHA-1. Equivalent to passing `--remote` to diff --git a/Documentation/git-commit-graph.adoc b/Documentation/git-commit-graph.adoc index 50b50168045c..e9558173c001 100644 --- a/Documentation/git-commit-graph.adoc +++ b/Documentation/git-commit-graph.adoc @@ -34,7 +34,8 @@ OPTIONS object directory, `git commit-graph ...` will exit with non-zero status. ---[no-]progress:: +--progress:: +--no-progress:: Turn progress on/off explicitly. If neither is specified, progress is shown if standard error is connected to a terminal. diff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc index d4d576ce665f..54c207ad45ea 100644 --- a/Documentation/git-commit.adoc +++ b/Documentation/git-commit.adoc @@ -214,7 +214,8 @@ include::signoff-option.adoc[] each trailer would appear, and other details. `-n`:: -`--[no-]verify`:: +`--verify`:: +`--no-verify`:: Bypass the `pre-commit` and `commit-msg` hooks. See also linkgit:githooks[5]. diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc index 511b2e26bfb0..36d28451528e 100644 --- a/Documentation/git-config.adoc +++ b/Documentation/git-config.adoc @@ -295,7 +295,8 @@ Valid `<type>`'s include: When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---[no-]includes:: +--includes:: +--no-includes:: Respect `include.*` directives in config files when looking up values. Defaults to `off` when a specific file is given (e.g., using `--file`, `--global`, etc) and `on` when searching all diff --git a/Documentation/git-difftool.adoc b/Documentation/git-difftool.adoc index d596205eaf3b..064bc683471f 100644 --- a/Documentation/git-difftool.adoc +++ b/Documentation/git-difftool.adoc @@ -77,7 +77,8 @@ with custom merge tool commands and has the same value as `$MERGED`. --tool-help:: Print a list of diff tools that may be used with `--tool`. ---[no-]symlinks:: +--symlinks:: +--no-symlinks:: 'git difftool''s default behavior is to create symlinks to the working tree when run in `--dir-diff` mode and the right-hand side of the comparison yields the same content as the file in @@ -94,7 +95,8 @@ instead. `--no-symlinks` is the default on Windows. Additionally, `$BASE` is set in the environment. -g:: ---[no-]gui:: +--gui:: +--no-gui:: When 'git-difftool' is invoked with the `-g` or `--gui` option the default diff tool will be read from the configured `diff.guitool` variable instead of `diff.tool`. This may be @@ -104,7 +106,8 @@ instead. `--no-symlinks` is the default on Windows. fallback in the order of `merge.guitool`, `diff.tool`, `merge.tool` until a tool is found. ---[no-]trust-exit-code:: +--trust-exit-code:: +--no-trust-exit-code:: Errors reported by the diff tool are ignored by default. Use `--trust-exit-code` to make 'git-difftool' exit when an invoked diff tool returns a non-zero exit code. diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index 6490d67fab56..3144ffcdb689 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -111,7 +111,8 @@ Locations of Marks Files Like --import-marks but instead of erroring out, silently skips the file if it does not exist. ---[no-]relative-marks:: +--relative-marks:: +--no-relative-marks:: After specifying --relative-marks the paths specified with --import-marks= and --export-marks= are relative to an internal directory in the current repository. diff --git a/Documentation/git-fmt-merge-msg.adoc b/Documentation/git-fmt-merge-msg.adoc index 0f3328956dfd..6d91620be979 100644 --- a/Documentation/git-fmt-merge-msg.adoc +++ b/Documentation/git-fmt-merge-msg.adoc @@ -35,7 +35,8 @@ OPTIONS Do not list one-line descriptions from the actual commits being merged. ---[no-]summary:: +--summary:: +--no-summary:: Synonyms to --log and --no-log; these are deprecated and will be removed in the future. diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc index a8b53db9a663..048d1b981524 100644 --- a/Documentation/git-format-patch.adoc +++ b/Documentation/git-format-patch.adoc @@ -295,7 +295,8 @@ header). Note also that `git send-email` already handles this transformation for you, and this option should not be used if you are feeding the result to `git send-email`. ---[no-]force-in-body-from:: +--force-in-body-from:: +--no-force-in-body-from:: With the e-mail sender specified via the `--from` option, by default, an in-body "From:" to identify the real author of the commit is added at the top of the commit log message if @@ -314,7 +315,8 @@ feeding the result to `git send-email`. `Cc:`, and custom) headers added so far from config or command line. ---[no-]cover-letter:: +--cover-letter:: +--no-cover-letter:: In addition to the patches, generate a cover letter file containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out. @@ -379,7 +381,8 @@ configuration options in linkgit:git-notes[1] to use this workflow). The default is `--no-notes`, unless the `format.notes` configuration is set. ---[no-]signature=<signature>:: +--signature=<signature>:: +--no-signature:: Add a signature to each message produced. Per RFC 3676 the signature is separated from the body by a line with '-- ' on it. If the signature option is omitted the signature defaults to the Git version @@ -411,7 +414,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. Output an all-zero hash in each patch's From header instead of the hash of the commit. ---[no-]base[=<commit>]:: +--no-base:: +--base[=<commit>]:: Record the base tree information to identify the state the patch series applies to. See the BASE TREE INFORMATION section below for details. If <commit> is "auto", a base commit is diff --git a/Documentation/git-fsck.adoc b/Documentation/git-fsck.adoc index 11203ba925c7..1751f692d42b 100644 --- a/Documentation/git-fsck.adoc +++ b/Documentation/git-fsck.adoc @@ -31,7 +31,8 @@ index file, all SHA-1 references in the `refs` namespace, and all reflogs Print out objects that exist but that aren't reachable from any of the reference nodes. ---[no-]dangling:: +--dangling:: +--no-dangling:: Print objects that exist but that are never 'directly' used (default). `--no-dangling` can be used to omit this information from the output. @@ -97,14 +98,16 @@ care about this output and want to speed it up further. compatible with linkgit:git-rev-parse[1], e.g. `HEAD@{1234567890}~25^2:src/`. ---[no-]progress:: +--progress:: +--no-progress:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless --no-progress or --verbose is specified. --progress forces progress status even if the standard error stream is not directed to a terminal. ---[no-]references:: +--references:: +--no-references:: Control whether to check the references database consistency via 'git refs verify'. See linkgit:git-refs[1] for details. The default is to check the references database. diff --git a/Documentation/git-gc.adoc b/Documentation/git-gc.adoc index 526ce01463d7..6fed646dd883 100644 --- a/Documentation/git-gc.adoc +++ b/Documentation/git-gc.adoc @@ -53,11 +53,13 @@ configuration options such as `gc.auto` and `gc.autoPackLimit`, all other housekeeping tasks (e.g. rerere, working trees, reflog...) will be performed as well. ---[no-]detach:: +--detach:: +--no-detach:: Run in the background if the system supports it. This option overrides the `gc.autoDetach` config. ---[no-]cruft:: +--cruft:: +--no-cruft:: When expiring unreachable objects, pack them separately into a cruft pack instead of storing them as loose objects. `--cruft` is on by default. diff --git a/Documentation/git-index-pack.adoc b/Documentation/git-index-pack.adoc index 270056cf6352..18036953c06b 100644 --- a/Documentation/git-index-pack.adoc +++ b/Documentation/git-index-pack.adoc @@ -36,7 +36,8 @@ OPTIONS fails if the name of packed archive does not end with .pack). ---[no-]rev-index:: +--rev-index:: +--no-rev-index:: When this flag is provided, generate a reverse index (a `.rev` file) corresponding to the given pack. If `--verify` is given, ensure that the existing diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc index b6f3d92c435f..e304739c5e80 100644 --- a/Documentation/git-log.adoc +++ b/Documentation/git-log.adoc @@ -73,8 +73,10 @@ used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`, Print out the ref name given on the command line by which each commit was reached. -`--[no-]mailmap`:: -`--[no-]use-mailmap`:: +`--mailmap`:: +`--no-mailmap`:: +`--use-mailmap`:: +`--no-use-mailmap`:: Use mailmap file to map author and committer names and email addresses to canonical real names and email addresses. See linkgit:git-shortlog[1]. diff --git a/Documentation/git-merge-tree.adoc b/Documentation/git-merge-tree.adoc index f824eea61f1e..271ab220e8d7 100644 --- a/Documentation/git-merge-tree.adoc +++ b/Documentation/git-merge-tree.adoc @@ -59,7 +59,8 @@ OPTIONS do not list filenames multiple times if they have multiple conflicting stages). ---[no-]messages:: +--messages:: +--no-messages:: Write any informational messages such as "Auto-merging <path>" or CONFLICT notices to the end of stdout. If unspecified, the default is to include these messages if there are merge diff --git a/Documentation/git-multi-pack-index.adoc b/Documentation/git-multi-pack-index.adoc index b6cd0d7f855d..e8073bc27232 100644 --- a/Documentation/git-multi-pack-index.adoc +++ b/Documentation/git-multi-pack-index.adoc @@ -25,7 +25,8 @@ OPTIONS + `<dir>` must be an alternate of the current repository. ---[no-]progress:: +--progress:: +--no-progress:: Turn progress on/off explicitly. If neither is specified, progress is shown if standard error is connected to a terminal. Supported by sub-commands `write`, `verify`, `expire`, and `repack. diff --git a/Documentation/git-pack-objects.adoc b/Documentation/git-pack-objects.adoc index eba014c40615..71b9682485c3 100644 --- a/Documentation/git-pack-objects.adoc +++ b/Documentation/git-pack-objects.adoc @@ -243,7 +243,8 @@ depth is 4095. Add --no-reuse-object if you want to force a uniform compression level on all data no matter the source. ---[no-]sparse:: +--sparse:: +--no-sparse:: Toggle the "sparse" algorithm to determine which objects to include in the pack, when combined with the "--revs" option. This algorithm only walks trees that appear in paths that introduce new objects. diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc index 3f4ecc47301a..48e924a10a40 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -87,7 +87,8 @@ OPTIONS --verbose:: Pass --verbose to git-fetch and git-merge. ---[no-]recurse-submodules[=(yes|on-demand|no)]:: +--recurse-submodules[=(yes|on-demand|no)]:: +--no-recurse-submodules:: This option controls if new commits of populated submodules should be fetched, and if the working trees of active submodules should be updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index d1978650d60a..5f5408e2c01d 100644 --- a/Documentation/git-push.adoc +++ b/Documentation/git-push.adoc @@ -197,7 +197,8 @@ already exists on the remote side. with configuration variable `push.followTags`. For more information, see `push.followTags` in linkgit:git-config[1]. ---[no-]signed:: +--signed:: +--no-signed:: --signed=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be @@ -208,7 +209,8 @@ already exists on the remote side. will also fail if the actual call to `gpg --sign` fails. See linkgit:git-receive-pack[1] for the details on the receiving end. ---[no-]atomic:: +--atomic:: +--no-atomic:: Use an atomic transaction on the remote side if available. Either all refs are updated, or on error, no refs are updated. If the server does not support atomic pushes the push will fail. @@ -232,7 +234,8 @@ already exists on the remote side. repository over ssh, and you do not have the program in a directory on the default $PATH. ---[no-]force-with-lease:: +--force-with-lease:: +--no-force-with-lease:: --force-with-lease=<refname>:: --force-with-lease=<refname>:<expect>:: Usually, "git push" refuses to update a remote ref that is @@ -350,7 +353,8 @@ one branch, use a `+` in front of the refspec to push (e.g `git push origin +master` to force a push to the `master` branch). See the `<refspec>...` section above for details. ---[no-]force-if-includes:: +--force-if-includes:: +--no-force-if-includes:: Force an update only if the tip of the remote-tracking ref has been integrated locally. + @@ -377,7 +381,8 @@ Specifying `--no-force-if-includes` disables this behavior. linkgit:git-pull[1] and other commands. For more information, see `branch.<name>.merge` in linkgit:git-config[1]. ---[no-]thin:: +--thin:: +--no-thin:: These options are passed to linkgit:git-send-pack[1]. A thin transfer significantly reduces the amount of sent data when the sender and receiver share many of the same objects in common. The default is @@ -419,7 +424,8 @@ When using 'on-demand' or 'only', if a submodule has a "push.recurseSubmodules={on-demand,only}" or "submodule.recurse" configuration, further recursion will occur. In this case, "only" is treated as "on-demand". ---[no-]verify:: +--verify:: +--no-verify:: Toggle the pre-push hook (see linkgit:githooks[5]). The default is --verify, giving the hook a chance to prevent the push. With --no-verify, the hook is bypassed completely. diff --git a/Documentation/git-range-diff.adoc b/Documentation/git-range-diff.adoc index db0e4279b528..b5e85d37f1be 100644 --- a/Documentation/git-range-diff.adoc +++ b/Documentation/git-range-diff.adoc @@ -96,7 +96,8 @@ diff. --remerge-diff:: Convenience option, equivalent to `--diff-merges=remerge`. ---[no-]notes[=<ref>]:: +--notes[=<ref>]:: +--no-notes:: This flag is passed to the `git log` program (see linkgit:git-log[1]) that generates the patches. diff --git a/Documentation/git-read-tree.adoc b/Documentation/git-read-tree.adoc index 1c48c2899630..1c04bba2b7b8 100644 --- a/Documentation/git-read-tree.adoc +++ b/Documentation/git-read-tree.adoc @@ -100,7 +100,8 @@ OPTIONS directories the index file and index output file are located in. ---[no-]recurse-submodules:: +--recurse-submodules:: +--no-recurse-submodules:: Using --recurse-submodules will update the content of all active submodules according to the commit recorded in the superproject by calling read-tree recursively, also setting the submodules' HEAD to be diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc index 50e8a0ba6f66..3b9ba9aee952 100644 --- a/Documentation/git-reset.adoc +++ b/Documentation/git-reset.adoc @@ -90,7 +90,8 @@ but carries forward unmerged index entries. If a file that is different between _<commit>_ and `HEAD` has local changes, reset is aborted. -`--[no-]recurse-submodules`:: +`--recurse-submodules`:: +`--no-recurse-submodules`:: When the working tree is updated, using `--recurse-submodules` will also recursively reset the working tree of all active submodules according to the commit recorded in the superproject, also setting diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc index 5335502d68fc..11b1ab1a070a 100644 --- a/Documentation/git-send-email.adoc +++ b/Documentation/git-send-email.adoc @@ -115,7 +115,8 @@ illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`: Only necessary if `--compose` is also set. If `--compose` is not set, this will be prompted for. ---[no-]outlook-id-fix:: +--outlook-id-fix:: +--no-outlook-id-fix:: Microsoft Outlook SMTP servers discard the Message-ID sent via email and assign a new random Message-ID, thus breaking threads. + @@ -350,7 +351,8 @@ Automating --no-header-cmd:: Disable any header command in use. ---[no-]chain-reply-to:: +--chain-reply-to:: +--no-chain-reply-to:: If this is set, each email will be sent as a reply to the previous email sent. If disabled with `--no-chain-reply-to`, all emails after the first will be sent as replies to the first email sent. When using @@ -364,19 +366,22 @@ Automating values in the `sendemail` section. The default identity is the value of `sendemail.identity`. ---[no-]signed-off-by-cc:: +--signed-off-by-cc:: +--no-signed-off-by-cc:: If this is set, add emails found in the `Signed-off-by` trailer or `Cc:` lines to the cc list. Default is the value of `sendemail.signedOffByCc` configuration value; if that is unspecified, default to `--signed-off-by-cc`. ---[no-]cc-cover:: +--cc-cover:: +--no-cc-cover:: If this is set, emails found in `Cc:` headers in the first patch of the series (typically the cover letter) are added to the cc list for each email set. Default is the value of `sendemail.ccCover` configuration value; if that is unspecified, default to `--no-cc-cover`. ---[no-]to-cover:: +--to-cover:: +--no-to-cover:: If this is set, emails found in `To:` headers in the first patch of the series (typically the cover letter) are added to the to list for each email set. Default is the value of `sendemail.toCover` @@ -407,12 +412,14 @@ Default is the value of `sendemail.suppressCc` configuration value; if that is unspecified, default to `self` if `--suppress-from` is specified, as well as `body` if `--no-signed-off-cc` is specified. ---[no-]suppress-from:: +--suppress-from:: +--no-suppress-from:: If this is set, do not add the `From:` address to the `Cc:` list. Default is the value of `sendemail.suppressFrom` configuration value; if that is unspecified, default to `--no-suppress-from`. ---[no-]thread:: +--thread:: +--no-thread:: If this is set, the `In-Reply-To` and `References` headers will be added to each email sent. Whether each mail refers to the previous email (`deep` threading per `git format-patch` @@ -430,7 +437,8 @@ exists when `git send-email` is asked to add it (especially note that Failure to do so may not produce the expected result in the recipient's MUA. ---[no-]mailmap:: +--mailmap:: +--no-mailmap:: Use the mailmap file (see linkgit:gitmailmap[5]) to map all addresses to their canonical real name and email address. Additional mailmap data specific to `git send-email` may be provided using the @@ -459,7 +467,8 @@ have been specified, in which case default to `compose`. --dry-run:: Do everything except actually send the emails. ---[no-]format-patch:: +--format-patch:: +--no-format-patch:: When an argument may be understood either as a reference or as a file name, choose to understand it as a format-patch argument (`--format-patch`) or as a file name (`--no-format-patch`). By default, when such a conflict @@ -469,7 +478,8 @@ have been specified, in which case default to `compose`. Make `git send-email` less verbose. One line per email should be all that is output. ---[no-]validate:: +--validate:: +--no-validate:: Perform sanity checks on patches. Currently, validation means the following: + diff --git a/Documentation/git-send-pack.adoc b/Documentation/git-send-pack.adoc index b9e73f2e77b1..811193f16c33 100644 --- a/Documentation/git-send-pack.adoc +++ b/Documentation/git-send-pack.adoc @@ -71,7 +71,8 @@ be in a separate packet, and the list must end with a flush packet. fails to update then the entire push will fail without changing any refs. ---[no-]signed:: +--signed:: +--no-signed:: --signed=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be diff --git a/Documentation/git-submodule.adoc b/Documentation/git-submodule.adoc index 87d8e0f0c563..2d6ac92ea450 100644 --- a/Documentation/git-submodule.adoc +++ b/Documentation/git-submodule.adoc @@ -435,7 +435,8 @@ options carefully. clone with a history truncated to the specified number of revisions. See linkgit:git-clone[1] ---[no-]recommend-shallow:: +--recommend-shallow:: +--no-recommend-shallow:: This option is only valid for the update command. The initial clone of a submodule will use the recommended `submodule.<name>.shallow` as provided by the `.gitmodules` file @@ -447,7 +448,8 @@ options carefully. Clone new submodules in parallel with as many jobs. Defaults to the `submodule.fetchJobs` option. ---[no-]single-branch:: +--single-branch:: +--no-single-branch:: This option is only valid for the update command. Clone only one branch during update: HEAD or one specified by --branch. diff --git a/Documentation/git-update-index.adoc b/Documentation/git-update-index.adoc index 7128aed54058..9bea9fab9ad1 100644 --- a/Documentation/git-update-index.adoc +++ b/Documentation/git-update-index.adoc @@ -86,7 +86,8 @@ OPTIONS --chmod=(+|-)x:: Set the execute permissions on the updated files. ---[no-]assume-unchanged:: +--assume-unchanged:: +--no-assume-unchanged:: When this flag is specified, the object names recorded for the paths are not updated. Instead, this option sets/unsets the "assume unchanged" bit for the @@ -108,18 +109,21 @@ you will need to handle the situation manually. Like `--refresh`, but checks stat information unconditionally, without regard to the "assume unchanged" setting. ---[no-]skip-worktree:: +--skip-worktree:: +--no-skip-worktree:: When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "skip-worktree" bit for the paths. See section "Skip-worktree bit" below for more information. ---[no-]ignore-skip-worktree-entries:: +--ignore-skip-worktree-entries:: +--no-ignore-skip-worktree-entries:: Do not remove skip-worktree (AKA "index-only") entries even when the `--remove` option was specified. ---[no-]fsmonitor-valid:: +--fsmonitor-valid:: +--no-fsmonitor-valid:: When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "fsmonitor valid" bit for the paths. See diff --git a/Documentation/git-upload-pack.adoc b/Documentation/git-upload-pack.adoc index 516d1639d9d0..9167a321d08e 100644 --- a/Documentation/git-upload-pack.adoc +++ b/Documentation/git-upload-pack.adoc @@ -25,7 +25,8 @@ repository. For push operations, see 'git send-pack'. OPTIONS ------- ---[no-]strict:: +--strict:: +--no-strict:: Do not try <directory>/.git/ if <directory> is not a Git directory. --timeout=<n>:: diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc index 8340b7f028e6..389e669ac044 100644 --- a/Documentation/git-worktree.adoc +++ b/Documentation/git-worktree.adoc @@ -200,13 +200,15 @@ To remove a locked worktree, specify `--force` twice. With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD" in linkgit:git-checkout[1]. ---[no-]checkout:: +--checkout:: +--no-checkout:: By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can be used to suppress checkout in order to make customizations, such as configuring sparse-checkout. See "Sparse checkout" in linkgit:git-read-tree[1]. ---[no-]guess-remote:: +--guess-remote:: +--no-guess-remote:: With `worktree add <path>`, without `<commit-ish>`, instead of creating a new branch from `HEAD`, if there exists a tracking branch in exactly one remote matching the basename of `<path>`, @@ -216,7 +218,8 @@ To remove a locked worktree, specify `--force` twice. This can also be set up as the default behaviour by using the `worktree.guessRemote` config option. ---[no-]relative-paths:: +--relative-paths:: +--no-relative-paths:: Link worktrees using relative paths or absolute paths (default). Overrides the `worktree.useRelativePaths` config option, see linkgit:git-config[1]. @@ -224,7 +227,8 @@ This can also be set up as the default behaviour by using the With `repair`, the linking files will be updated if there's an absolute/relative mismatch, even if the links are correct. ---[no-]track:: +--track:: +--no-track:: When creating a new branch, if `<commit-ish>` is a branch, mark it as "upstream" from the new branch. This is the default if `<commit-ish>` is a remote-tracking branch. See diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl index 1f35a6a116da..11321a151bca 100755 --- a/Documentation/lint-documentation-style.perl +++ b/Documentation/lint-documentation-style.perl @@ -18,6 +18,9 @@ while (my $line = <>) { report($line, "multiple parameters in a definition list item"); } + if ($line =~ /^`?--\[no-\][a-z0-9-]+.*(::|;;)$/) { + report($line, "definition list item with a `--[no-]` parameter"); + } } diff --git a/Documentation/merge-options.adoc b/Documentation/merge-options.adoc index 95ef491be109..9d433265b298 100644 --- a/Documentation/merge-options.adoc +++ b/Documentation/merge-options.adoc @@ -135,7 +135,8 @@ ifdef::git-pull[] Only useful when merging. endif::git-pull[] -`--[no-]verify`:: +`--verify`:: +`--no-verify`:: By default, the pre-merge and commit-msg hooks are run. When `--no-verify` is given, these are bypassed. See also linkgit:githooks[5]. diff --git a/Documentation/scalar.adoc b/Documentation/scalar.adoc index 4bd5b150e8e1..f81b2832f8df 100644 --- a/Documentation/scalar.adoc +++ b/Documentation/scalar.adoc @@ -71,7 +71,8 @@ HEAD[:<directory>]`. Instead of checking out the branch pointed to by the cloned repository's HEAD, check out the `<name>` branch instead. ---[no-]single-branch:: +--single-branch:: +--no-single-branch:: Clone only the history leading to the tip of a single branch, either specified by the `--branch` option or the primary branch remote's `HEAD` points at. @@ -81,23 +82,27 @@ remote-tracking branch for the branch this option was used for the initial cloning. If the HEAD at the remote did not point at any branch when `--single-branch` clone was made, no remote-tracking branch is created. ---[no-]src:: +--src:: +--no-src:: By default, `scalar clone` places the cloned repository within a `<entlistment>/src` directory. Use `--no-src` to place the cloned repository directly in the `<enlistment>` directory. ---[no-]tags:: +--tags:: +--no-tags:: By default, `scalar clone` will fetch the tag objects advertised by the remote and future `git fetch` commands will do the same. Use `--no-tags` to avoid fetching tags in `scalar clone` and to configure the repository to avoid fetching tags in the future. To fetch tags after cloning with `--no-tags`, run `git fetch --tags`. ---[no-]full-clone:: +--full-clone:: +--no-full-clone:: A sparse-checkout is initialized by default. This behavior can be turned off via `--full-clone`. ---[no-]maintenance:: +--maintenance:: +--no-maintenance:: By default, `scalar clone` configures the enlistment to use Git's background maintenance feature. Use the `--no-maintenance` to skip this configuration. @@ -122,7 +127,8 @@ Note: when this subcommand is called in a worktree that is called `src/`, its parent directory is considered to be the Scalar enlistment. If the worktree is _not_ called `src/`, it itself will be considered to be the Scalar enlistment. ---[no-]maintenance:: +--maintenance:: +--no-maintenance:: By default, `scalar register` configures the enlistment to use Git's background maintenance feature. Use the `--no-maintenance` to skip this configuration. This does not disable any maintenance that may -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH v3 5/6] doc:git-for-each-ref: fix styling and typos 2025-08-11 20:53 ` [PATCH v3 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget ` (3 preceding siblings ...) 2025-08-11 20:53 ` [PATCH v3 4/6] doc: check for absence of the form --[no-]parameter Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 ` Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 6/6] doc lint: check that synopsis manpages have synopsis inlines Jean-Noël Avila via GitGitGadget 2025-08-14 16:34 ` [PATCH v3 0/6] Introduce more doc linting Junio C Hamano 6 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 UTC (permalink / raw) To: git; +Cc: Ramsay Jones, Collin Funk, Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> This commit fixes the synopsis syntax and changes the wording of a few descriptions to be more consistent with the rest of the documentation. It is a prepartion for the next commit that checks that synopsis style is applied consistently across a manual page. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/git-for-each-ref.adoc | 264 ++++++++++++++-------------- 1 file changed, 132 insertions(+), 132 deletions(-) diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc index 060940904da2..b69080c4a000 100644 --- a/Documentation/git-for-each-ref.adoc +++ b/Documentation/git-for-each-ref.adoc @@ -14,101 +14,98 @@ git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl] [--merged[=<object>]] [--no-merged[=<object>]] [--contains[=<object>]] [--no-contains[=<object>]] [(--exclude=<pattern>)...] [--start-after=<marker>] - [ --stdin | <pattern>... ] + [ --stdin | (<pattern>...)] DESCRIPTION ----------- -Iterate over all refs that match `<pattern>` and show them -according to the given `<format>`, after sorting them according -to the given set of `<key>`. If `<count>` is given, stop after -showing that many refs. The interpolated values in `<format>` +Iterate over all refs that match _<pattern>_ and show them +according to the given _<format>_, after sorting them according +to the given set of _<key>_. If _<count>_ is given, stop after +showing that many refs. The interpolated values in _<format>_ can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language. OPTIONS ------- -<pattern>...:: - If one or more patterns are given, only refs are shown that - match against at least one pattern, either using fnmatch(3) or +`<pattern>...`:: + If one or more _<pattern>_ parameters are given, only refs are shown that + match against at least one pattern, either using `fnmatch`(3) or literally, in the latter case matching completely or from the beginning up to a slash. ---stdin:: - If `--stdin` is supplied, then the list of patterns is read from - standard input instead of from the argument list. +`--stdin`:: + The list of patterns is read from standard input instead of from + the argument list. ---count=<count>:: - By default the command shows all refs that match - `<pattern>`. This option makes it stop after showing - that many refs. +`--count=<count>`:: + Stop after showing _<count>_ refs. ---sort=<key>:: - A field name to sort on. Prefix `-` to sort in +`--sort=<key>`:: + Sort on the field name _<key>_. Prefix `-` to sort in descending order of the value. When unspecified, - `refname` is used. You may use the --sort=<key> option + `refname` is used. You may use the `--sort=<key>` option multiple times, in which case the last key becomes the primary key. ---format=<format>:: +`--format[=<format>]`:: A string that interpolates `%(fieldname)` from a ref being shown and the object it points at. In addition, the string literal `%%` renders as `%` and `%xx` - where `xx` are hex digits - renders as the character with hex code `xx`. For example, `%00` interpolates to - `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF). -+ -When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype) + `\0` (_NUL_), `%09` to `\t` (_TAB_), and `%0a` to `\n` (_LF_). + +When unspecified, _<format>_ defaults to `%(objectname) SPC %(objecttype) TAB %(refname)`. ---color[=<when>]:: +`--color[=<when>]`:: Respect any colors specified in the `--format` option. The - `<when>` field must be one of `always`, `never`, or `auto` (if + _<when__ field must be one of `always`, `never`, or `auto` (if `<when>` is absent, behave as if `always` was given). ---shell:: ---perl:: ---python:: ---tcl:: +`--shell`:: +`--perl`:: +`--python`:: +`--tcl`:: If given, strings that substitute `%(fieldname)` placeholders are quoted as string literals suitable for the specified host language. This is meant to produce - a scriptlet that can directly be `eval`ed. + a scriptlet that can directly be "eval"ed. ---points-at=<object>:: +`--points-at=<object>`:: Only list refs which points at the given object. ---merged[=<object>]:: +`--merged[=<object>]`:: Only list refs whose tips are reachable from the - specified commit (HEAD if not specified). - ---no-merged[=<object>]:: - Only list refs whose tips are not reachable from the - specified commit (HEAD if not specified). + specified commit (`HEAD` if not specified). ---contains[=<object>]:: - Only list refs which contain the specified commit (HEAD if not +`--no-merged[=<object>]`:: + Only list refs whose tips are not reachable from _<object>_(`HEAD` if not specified). ---no-contains[=<object>]:: - Only list refs which don't contain the specified commit (HEAD +`--contains[=<object>]`:: + Only list refs which contain _<object>_(`HEAD` if not specified). + +`--no-contains[=<object>]`:: + Only list refs which don't contain _<object>_ (`HEAD` if not specified). ---ignore-case:: +`--ignore-case`:: Sorting and filtering refs are case insensitive. ---omit-empty:: +`--omit-empty`:: Do not print a newline after formatted refs where the format expands to the empty string. ---exclude=<pattern>:: - If one or more patterns are given, only refs which do not match - any excluded pattern(s) are shown. Matching is done using the - same rules as `<pattern>` above. +`--exclude=<excluded-pattern>`:: + If one or more `--exclude` options are given, only refs which do not + match any _<excluded-pattern>_ parameters are shown. Matching is done + using the same rules as _<pattern>_ above. ---include-root-refs:: - List root refs (HEAD and pseudorefs) apart from regular refs. +`--include-root-refs`:: + List root refs (`HEAD` and pseudorefs) apart from regular refs. ---start-after=<marker>:: +`--start-after=<marker>`:: Allows paginating the output by skipping references up to and including the specified marker. When paging, it should be noted that references may be deleted, modified or added between invocations. Output will only yield those @@ -126,44 +123,44 @@ keys. For all objects, the following names can be used: -refname:: - The name of the ref (the part after $GIT_DIR/). +`refname`:: + The name of the ref (the part after `$GIT_DIR/`). For a non-ambiguous short name of the ref append `:short`. - The option core.warnAmbiguousRefs is used to select the strict - abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>` + The option `core.warnAmbiguousRefs` is used to select the strict + abbreviation mode. If `lstrip=<n>` (`rstrip=<n>`) is appended, strip _<n>_ slash-separated path components from the front (back) of the refname (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`). - If `<N>` is a negative number, strip as many path components as - necessary from the specified end to leave `-<N>` path components + If _<n>_ is a negative number, strip as many path components as + necessary from the specified end to leave `-<n>` path components (e.g. `%(refname:lstrip=-2)` turns `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)` turns `refs/tags/foo` into `refs`). When the ref does not have enough components, the result becomes an empty string if - stripping with positive <N>, or it becomes the full refname if - stripping with negative <N>. Neither is an error. + stripping with positive _<n>_, or it becomes the full refname if + stripping with negative _<N>_. Neither is an error. + `strip` can be used as a synonym to `lstrip`. -objecttype:: +`objecttype`:: The type of the object (`blob`, `tree`, `commit`, `tag`). -objectsize:: +`objectsize`:: The size of the object (the same as 'git cat-file -s' reports). Append `:disk` to get the size, in bytes, that the object takes up on - disk. See the note about on-disk sizes in the `CAVEATS` section below. -objectname:: + disk. See the note about on-disk sizes in the 'CAVEATS' section below. +`objectname`:: The object name (aka SHA-1). For a non-ambiguous abbreviation of the object name append `:short`. For an abbreviation of the object name with desired length append - `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The + `:short=<length>`, where the minimum length is `MINIMUM_ABBREV`. The length may be exceeded to ensure unique object names. -deltabase:: +`deltabase`:: This expands to the object name of the delta base for the given object, if it is stored as a delta. Otherwise it expands to the null object name (all zeroes). -upstream:: +`upstream`:: The name of a local ref which can be considered ``upstream'' from the displayed ref. Respects `:short`, `:lstrip` and `:rstrip` in the same way as `refname` above. Additionally @@ -185,100 +182,103 @@ Has no effect if the ref does not have tracking information associated with it. All the options apart from `nobracket` are mutually exclusive, but if used together the last option is selected. -push:: +`push`:: The name of a local ref which represents the `@{push}` location for the displayed ref. Respects `:short`, `:lstrip`, `:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref` options as `upstream` does. Produces an empty string if no `@{push}` ref is configured. -HEAD:: - '*' if HEAD matches current ref (the checked out branch), ' ' +`HEAD`:: + `*` if `HEAD` matches current ref (the checked out branch), ' ' otherwise. -color:: +`color`:: Change output color. Followed by `:<colorname>`, where color names are described under Values in the "CONFIGURATION FILE" section of linkgit:git-config[1]. For example, `%(color:bold red)`. -align:: +`align`:: Left-, middle-, or right-align the content between - %(align:...) and %(end). The "align:" is followed by + `%(align:...)` and `%(end)`. The "`align:`" is followed by `width=<width>` and `position=<position>` in any order - separated by a comma, where the `<position>` is either left, - right or middle, default being left and `<width>` is the total + separated by a comma, where the _<position>_ is either `left`, + `right` or `middle`, default being `left` and _<width>_ is the total length of the content with alignment. For brevity, the "width=" and/or "position=" prefixes may be omitted, and bare - <width> and <position> used instead. For instance, + _<width>_ and _<position>_ used instead. For instance, `%(align:<width>,<position>)`. If the contents length is more than the width then no alignment is performed. If used with - `--quote` everything in between %(align:...) and %(end) is + `--quote` everything in between `%(align:...)` and `%(end)` is quoted, but if nested then only the topmost level performs quoting. -if:: - Used as %(if)...%(then)...%(end) or - %(if)...%(then)...%(else)...%(end). If there is an atom with - value or string literal after the %(if) then everything after - the %(then) is printed, else if the %(else) atom is used, then +`if`:: + Used as `%(if)...%(then)...%(end)` or + `%(if)...%(then)...%(else)...%(end)`. If there is an atom with + value or string literal after the `%(if)` then everything after + the `%(then)` is printed, else if the `%(else)` atom is used, then everything after %(else) is printed. We ignore space when - evaluating the string before %(then), this is useful when we - use the %(HEAD) atom which prints either "*" or " " and we - want to apply the 'if' condition only on the 'HEAD' ref. - Append ":equals=<string>" or ":notequals=<string>" to compare - the value between the %(if:...) and %(then) atoms with the + evaluating the string before `%(then)`, this is useful when we + use the `%(HEAD)` atom which prints either "`*`" or " " and we + want to apply the 'if' condition only on the `HEAD` ref. + Append "`:equals=<string>`" or "`:notequals=<string>`" to compare + the value between the `%(if:...)` and `%(then)` atoms with the given string. -symref:: +`symref`:: The ref which the given symbolic ref refers to. If not a symbolic ref, nothing is printed. Respects the `:short`, `:lstrip` and `:rstrip` options in the same way as `refname` above. -signature:: +`signature`:: The GPG signature of a commit. -signature:grade:: - Show "G" for a good (valid) signature, "B" for a bad - signature, "U" for a good signature with unknown validity, "X" - for a good signature that has expired, "Y" for a good - signature made by an expired key, "R" for a good signature - made by a revoked key, "E" if the signature cannot be - checked (e.g. missing key) and "N" for no signature. - -signature:signer:: +`signature:grade`:: + Show +`G`;; for a good (valid) signature +`B`;; for a bad signature +`U`;; for a good signature with unknown validity +`X`;; for a good signature that has expired +`Y`;; for a good signature made by an expired key +`R`;; for a good signature made by a revoked key +`E`;; if the signature cannot be checked (e.g. missing key) +`N`;; for no signature. + +`signature:signer`:: The signer of the GPG signature of a commit. -signature:key:: +`signature:key`:: The key of the GPG signature of a commit. -signature:fingerprint:: +`signature:fingerprint`:: The fingerprint of the GPG signature of a commit. -signature:primarykeyfingerprint:: +`signature:primarykeyfingerprint`:: The primary key fingerprint of the GPG signature of a commit. -signature:trustlevel:: +`signature:trustlevel`:: The trust level of the GPG signature of a commit. Possible outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`. -worktreepath:: +`worktreepath`:: The absolute path to the worktree in which the ref is checked out, if it is checked out in any linked worktree. Empty string otherwise. -ahead-behind:<committish>:: +`ahead-behind:<commit-ish>`:: Two integers, separated by a space, demonstrating the number of commits ahead and behind, respectively, when comparing the output - ref to the `<committish>` specified in the format. + ref to the _<committish>_ specified in the format. -is-base:<committish>:: - In at most one row, `(<committish>)` will appear to indicate the ref +`is-base:<commit-ish>`:: + In at most one row, `(<commit-ish>)` will appear to indicate the ref that is most likely the ref used as a starting point for the branch - that produced `<committish>`. This choice is made using a heuristic: + that produced _<commit-ish>_. This choice is made using a heuristic: choose the ref that minimizes the number of commits in the - first-parent history of `<committish>` and not in the first-parent + first-parent history of _<commit-ish>_ and not in the first-parent history of the ref. + For example, consider the following figure of first-parent histories of @@ -312,29 +312,29 @@ common first-parent ancestor of `B` and `C` and ties are broken by the earliest ref in the sorted order. + Note that this token will not appear if the first-parent history of -`<committish>` does not intersect the first-parent histories of the +_<commit-ish>_ does not intersect the first-parent histories of the filtered refs. -describe[:options]:: +`describe[:<option>,...]`:: A human-readable name, like linkgit:git-describe[1]; empty string for undescribable commits. The `describe` string may be followed by a colon and one or more comma-separated options. + -- -tags=<bool-value>;; +`tags=<bool-value>`;; Instead of only considering annotated tags, consider lightweight tags as well; see the corresponding option in linkgit:git-describe[1] for details. -abbrev=<number>;; - Use at least <number> hexadecimal digits; see the corresponding +`abbrev=<number>`;; + Use at least _<number>_ hexadecimal digits; see the corresponding option in linkgit:git-describe[1] for details. -match=<pattern>;; - Only consider tags matching the given `glob(7)` pattern, - excluding the "refs/tags/" prefix; see the corresponding option +`match=<pattern>`;; + Only consider tags matching the `glob`(7) _<pattern>_, + excluding the `refs/tags/` prefix; see the corresponding option in linkgit:git-describe[1] for details. -exclude=<pattern>;; - Do not consider tags matching the given `glob(7)` pattern, - excluding the "refs/tags/" prefix; see the corresponding option +`exclude=<pattern>`;; + Do not consider tags matching the `glob`(7) _<pattern>_, + excluding the `refs/tags/` prefix; see the corresponding option in linkgit:git-describe[1] for details. -- @@ -366,7 +366,7 @@ variable (see linkgit:gitmailmap[5]). The raw data in an object is `raw`. -raw:size:: +`raw:size`:: The raw data size of the object. Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`, @@ -376,10 +376,10 @@ variable type. The message in a commit or a tag object is `contents`, from which `contents:<part>` can be used to extract various parts out of: -contents:size:: +`contents:size`:: The size in bytes of the commit or tag message. -contents:subject:: +`contents:subject`:: The first paragraph of the message, which typically is a single line, is taken as the "subject" of the commit or the tag message. @@ -387,19 +387,19 @@ contents:subject:: obtain same results. `:sanitize` can be appended to `subject` for subject line suitable for filename. -contents:body:: +`contents:body`:: The remainder of the commit or the tag message that follows the "subject". -contents:signature:: +`contents:signature`:: The optional GPG signature of the tag. -contents:lines=N:: - The first `N` lines of the message. +`contents:lines=<n>`:: + The first _<n>_ lines of the message. Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1] -are obtained as `trailers[:options]` (or by using the historical alias -`contents:trailers[:options]`). For valid [:option] values see `trailers` +are obtained as `trailers[:<option>,...]` (or by using the historical alias +`contents:trailers[:<option>,...]`). For valid _<option>_ values see `trailers` section of linkgit:git-log[1]. For sorting purposes, fields with numeric values sort in numeric order @@ -419,8 +419,8 @@ option to linkgit:git-rev-list[1] takes). If this formatting is provided in a `--sort` key, references will be sorted according to the byte-value of the formatted string rather than the numeric value of the underlying timestamp. -Some atoms like %(align) and %(if) always require a matching %(end). -We call them "opening atoms" and sometimes denote them as %($open). +Some atoms like `%(align)` and `%(if)` always require a matching `%(end)`. +We call them "opening atoms" and sometimes denote them as `%($open)`. When a scripting language specific quoting is in effect, everything between a top-level opening atom and its matching %(end) is evaluated @@ -438,7 +438,7 @@ An example directly producing formatted text. Show the most recent #!/bin/sh git for-each-ref --count=3 --sort='-*authordate' \ ---format='From: %(*authorname) %(*authoremail) +`--format='From: %(*authorname) %(*authoremail) Subject: %(*subject) Date: %(*authordate) Ref: %(*refname) @@ -449,7 +449,7 @@ Ref: %(*refname) A simple example showing the use of shell eval on the output, -demonstrating the use of --shell. List the prefixes of all heads: +demonstrating the use of `--shell`. List the prefixes of all heads: ------------ #!/bin/sh @@ -517,7 +517,7 @@ eval "$eval" ------------ -An example to show the usage of %(if)...%(then)...%(else)...%(end). +An example to show the usage of `%(if)...%(then)...%(else)...%(end)`. This prefixes the current branch with a star. ------------ @@ -525,7 +525,7 @@ git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" ------------ -An example to show the usage of %(if)...%(then)...%(end). +An example to show the usage of `%(if)...%(then)...%(end)`. This prints the authorname, if present. ------------ -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH v3 6/6] doc lint: check that synopsis manpages have synopsis inlines 2025-08-11 20:53 ` [PATCH v3 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget ` (4 preceding siblings ...) 2025-08-11 20:53 ` [PATCH v3 5/6] doc:git-for-each-ref: fix styling and typos Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 ` Jean-Noël Avila via GitGitGadget 2025-08-14 16:34 ` [PATCH v3 0/6] Introduce more doc linting Junio C Hamano 6 siblings, 0 replies; 28+ messages in thread From: Jean-Noël Avila via GitGitGadget @ 2025-08-11 20:53 UTC (permalink / raw) To: git; +Cc: Ramsay Jones, Collin Funk, Jean-Noël Avila, Jean-Noël Avila From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr> When switching manpages to the synopsis style, the description lists of options need to be switched to inline synopsis for proper formatting. This is done by enclosing the option name in double backticks, e.g. `--option`. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/git-checkout.adoc | 2 +- Documentation/git-refs.adoc | 20 ++++++++++---------- Documentation/lint-documentation-style.perl | 6 ++++++ 3 files changed, 17 insertions(+), 11 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index 40e02cfd6562..ff1cb29bc1f8 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -334,7 +334,7 @@ include::diff-context-options.adoc[] separated with _NUL_ character and all other characters are taken literally (including newlines and quotes). -<branch>:: +`<branch>`:: Branch to checkout; if it refers to a branch (i.e., a name that, when prepended with "refs/heads/", is a valid ref), then that branch is checked out. Otherwise, if it refers to a valid diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc index 4d6dc994f92e..5d26de8acb22 100644 --- a/Documentation/git-refs.adoc +++ b/Documentation/git-refs.adoc @@ -20,41 +20,41 @@ This command provides low-level access to refs. COMMANDS -------- -migrate:: +`migrate`:: Migrate ref store between different formats. -verify:: +`verify`:: Verify reference database consistency. OPTIONS ------- -The following options are specific to 'git refs migrate': +The following options are specific to `git refs migrate`: ---ref-format=<format>:: +`--ref-format=<format>`:: The ref format to migrate the ref store to. Can be one of: + include::ref-storage-format.adoc[] ---dry-run:: +`--dry-run`:: Perform the migration, but do not modify the repository. The migrated refs will be written into a separate directory that can be inspected separately. The name of the directory will be reported on stdout. This can be used to double check that the migration works as expected before performing the actual migration. ---reflog:: ---no-reflog:: +`--reflog`:: +`--no-reflog`:: Choose between migrating the reflog data to the new backend, and discarding them. The default is "--reflog", to migrate. -The following options are specific to 'git refs verify': +The following options are specific to `git refs verify`: ---strict:: +`--strict`:: Enable stricter error checking. This will cause warnings to be reported as errors. See linkgit:git-fsck[1]. ---verbose:: +`--verbose`:: When verifying the reference database consistency, be chatty. KNOWN LIMITATIONS diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl index 11321a151bca..d7ab7322939e 100755 --- a/Documentation/lint-documentation-style.perl +++ b/Documentation/lint-documentation-style.perl @@ -21,6 +21,12 @@ while (my $line = <>) { if ($line =~ /^`?--\[no-\][a-z0-9-]+.*(::|;;)$/) { report($line, "definition list item with a `--[no-]` parameter"); } + if ($line =~ /^\[synopsis\]$/) { + $synopsis_style = 1; + } + if (($line =~ /^(-[-a-z].*|<[-a-z0-9]+>(\.{3})?)(::|;;)$/) && ($synopsis_style)) { + report($line, "synopsis style and definition list item not backquoted"); + } } -- gitgitgadget ^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH v3 0/6] Introduce more doc linting 2025-08-11 20:53 ` [PATCH v3 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget ` (5 preceding siblings ...) 2025-08-11 20:53 ` [PATCH v3 6/6] doc lint: check that synopsis manpages have synopsis inlines Jean-Noël Avila via GitGitGadget @ 2025-08-14 16:34 ` Junio C Hamano 2025-08-14 17:23 ` Jean-Noël AVILA 6 siblings, 1 reply; 28+ messages in thread From: Junio C Hamano @ 2025-08-14 16:34 UTC (permalink / raw) To: Jean-Noël Avila via GitGitGadget Cc: git, Ramsay Jones, Collin Funk, Jean-Noël Avila "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes: > Reviewing the documentation part of the last patches, it turns out that the > majority of my comments are related to the latest documentation guidelines > which are both easy to forget and almost trivial to automatically check. > > This series implements the automatic tests for basic doc rules. At the > moment it conflicts with "[GSoC][PATCH v6 0/6] Add refs list subcommand" and > possibly with "[PATCH v4 0/9] refs: fix migration of reflog entries" > > Changes since v1: > > * fix a small typo > > Changes since v2: > > * extend range of check files for multiple entries in definition list > entries > * extend checks for new synopsis styles This round has been in 'seen', hasn't triggered any false positives. Let's mark the topic for 'next'? ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v3 0/6] Introduce more doc linting 2025-08-14 16:34 ` [PATCH v3 0/6] Introduce more doc linting Junio C Hamano @ 2025-08-14 17:23 ` Jean-Noël AVILA 0 siblings, 0 replies; 28+ messages in thread From: Jean-Noël AVILA @ 2025-08-14 17:23 UTC (permalink / raw) To: Jean-Noël Avila via GitGitGadget, Junio C Hamano Cc: git, Ramsay Jones, Collin Funk On Thursday, 14 August 2025 18:34:47 CEST Junio C Hamano wrote: > "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes: > > Reviewing the documentation part of the last patches, it turns out that the > > majority of my comments are related to the latest documentation guidelines > > which are both easy to forget and almost trivial to automatically check. > > > > This series implements the automatic tests for basic doc rules. At the > > moment it conflicts with "[GSoC][PATCH v6 0/6] Add refs list subcommand" and > > possibly with "[PATCH v4 0/9] refs: fix migration of reflog entries" > > > > Changes since v1: > > * fix a small typo > > > > Changes since v2: > > * extend range of check files for multiple entries in definition list > > > > entries > > > > * extend checks for new synopsis styles > > This round has been in 'seen', hasn't triggered any false positives. > Let's mark the topic for 'next'? I'm OK with this. ^ permalink raw reply [flat|nested] 28+ messages in thread
end of thread, other threads:[~2025-08-14 17:23 UTC | newest] Thread overview: 28+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2025-08-05 13:03 [PATCH 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 2/6] doc: check well-formedness of delimited sections Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 3/6] doc: check for absence of multiple terms in each entry of desc list Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 4/6] doc: check for absence of the form --[no-]parameter Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 5/6] doc:git-for-each-ref: fix styling and typos Jean-Noël Avila via GitGitGadget 2025-08-05 13:03 ` [PATCH 6/6] doc lint: check that synopsis manpages have synopsis inlines Jean-Noël Avila via GitGitGadget 2025-08-05 16:56 ` [PATCH 0/6] Introduce more doc linting Junio C Hamano 2025-08-05 19:10 ` [PATCH v2 " Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 2/6] doc: check well-formedness of delimited sections Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 3/6] doc: check for absence of multiple terms in each entry of desc list Jean-Noël Avila via GitGitGadget 2025-08-05 20:30 ` [-SPAM-] " Ramsay Jones 2025-08-08 13:00 ` Jean-Noël AVILA 2025-08-06 1:02 ` Collin Funk 2025-08-08 21:52 ` Jean-Noël AVILA 2025-08-05 19:10 ` [PATCH v2 4/6] doc: check for absence of the form --[no-]parameter Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 5/6] doc:git-for-each-ref: fix styling and typos Jean-Noël Avila via GitGitGadget 2025-08-05 19:10 ` [PATCH v2 6/6] doc lint: check that synopsis manpages have synopsis inlines Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 0/6] Introduce more doc linting Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 1/6] doc: test linkgit macros for well-formedness Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 2/6] doc: check well-formedness of delimited sections Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 3/6] doc: check for absence of multiple terms in each entry of desc list Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 4/6] doc: check for absence of the form --[no-]parameter Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 5/6] doc:git-for-each-ref: fix styling and typos Jean-Noël Avila via GitGitGadget 2025-08-11 20:53 ` [PATCH v3 6/6] doc lint: check that synopsis manpages have synopsis inlines Jean-Noël Avila via GitGitGadget 2025-08-14 16:34 ` [PATCH v3 0/6] Introduce more doc linting Junio C Hamano 2025-08-14 17:23 ` Jean-Noël AVILA
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).