[PATCH v2 00/35] doc/UX: make txt & -h output more consistent
- From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- Date
- Sep 28, 2022, 08:38 UTC
- Message-ID
- <cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com>
- In-Reply-To
- <cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com>
We are currently wildly inconsistent in whether the SYNOPSIS in the manual page matches the first line of the -h output, and as we add new options we routinely forget to add them to one or the other (or both).
Without a more complex approach it's hard to do something about the "or both" case. But we can rather easily test whether the -h output matches the *.txt version, and report differences.
As this series shows that allows us to fix a lot of issues we've effectively already "fixed", we just fixed them in one version, but not the other.
For the rest of the general overview (the first paragraphs are copy/pasted) see the v1 at: https://lore.kernel.org/git/cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com/
Changes since v1:
* Clarified the CodingGuidelines update with Junio's suggested wording/changes.
* Fixed a mention to a "preceding" commit noted by Victoria.
* Made one minor bit of "sed" syntax in 34/35 consistent with the rest.
* Added an assertion that "-h" output only has SP whitespace, not TABs.
* 20/35 shows a bug in v1 of this. I compared the -h and *.txt output, but because I normalized (stripped away) the whitespace I didn't notice that "git tag" was left unindented.
There's now a new test in 35/35 to test for that.
Victoria: I decided not to go for your suggestion of trimming this series down in [1]. Reasons:
* It would take me time I don't have to spend on this, as some of it isn't easy to cleanly re-arrange. E.g. the later "make consistent" commits rely on earlier whitespace/basic syntax fixes.
* A major advantage of reviewing this in one go is that the 34-35/35 tests at the end are asserting everything that came before it.
That's what I meant re the "mostly trust" comment you replied to in [1]. I.e. I aimed to make it easy for reviewers to trust that the "doc txt & -h consistency" patches were only altering one side of either -h or *.txt, with the other side being in-tree already.
* I originally hacked this up with 34/35 coming first, but then to make the commits atomic I needed to update the test with each change to alter the list of built-ins expected to pass.
I think that original approach is arguably better, as you can assert each commit in isolation, and it would certainly make it easier to split this up. But to re-do it again at this point would be more work & churn than I think this is worth.
I'm attaching a "Documentation/doc-diff @{u} HEAD" below the range diff, to make it easy to see what the end result of the *.txt changes here is.
1. https://lore.kernel.org/git/af319ab4-2351-2d74-e0c7-6153f229d88c@github.com/
Ævar Arnfjörð Bjarmason (35): CodingGuidelines: update and clarify command-line conventions builtin/bundle.c: use \t, not fix indentation 2-SP indentation bundle: define subcommand -h in terms of command -h blame: use a more detailed usage_msg_optf() error on bad -L doc SYNOPSIS: don't use ' for subcommands doc SYNOPSIS: consistently use ' for commands doc SYNOPSIS & -h: fix incorrect alternates syntax built-ins: consistently add "\n" between "usage" and options doc txt & -h consistency: word-wrap doc txt & -h consistency: fix incorrect alternates syntax doc txt & -h consistency: add "-z" to cat-file "-h" doc txt & -h consistency: add missing "]" to bugreport "-h" doc txt & -h consistency: correct padding around "[]()" stash doc SYNOPSIS & -h: correct padding around "[]()" doc txt & -h consistency: use "<options>", not "<options>..." t/helper/test-proc-receive.c: use "<options>", not "<options>..." doc txt & -h consistency: fix mismatching labels doc txt & -h consistency: add or fix optional "--" syntax doc txt & -h consistency: make output order consistent doc txt & -h consistency: add missing options and labels doc txt & -h consistency: make "rerere" consistent doc txt & -h consistency: make "read-tree" consistent doc txt & -h consistency: make "bundle" consistent doc txt & -h consistency: use "git foo" form, not "git-foo" doc txt & -h consistency: add missing options doc txt & -h consistency: make "stash" consistent doc txt & -h consistency: make "annotate" consistent doc txt & -h consistency: use "[<label>...]" for "zero or more" doc txt & -h consistency: make "diff-tree" consistent doc txt & -h consistency: make "commit" consistent reflog doc: list real subcommands up-front worktree: define subcommand -h in terms of command -h doc txt & -h consistency: make "worktree" consistent tests: start asserting that *.txt SYNOPSIS matches -h output tests: assert consistent whitespace in -h output
Documentation/CodingGuidelines | 17 +- Documentation/git-annotate.txt | 2 +- Documentation/git-clean.txt | 6 +- Documentation/git-commit-graph.txt | 5 +- .../git-credential-cache--daemon.txt | 2 +- Documentation/git-diff-files.txt | 2 +- Documentation/git-fast-export.txt | 2 +- Documentation/git-hash-object.txt | 3 +- Documentation/git-interpret-trailers.txt | 5 +- Documentation/git-merge-base.txt | 4 +- Documentation/git-mv.txt | 2 +- Documentation/git-pack-redundant.txt | 2 +- Documentation/git-prune-packed.txt | 2 +- Documentation/git-read-tree.txt | 2 +- Documentation/git-receive-pack.txt | 2 +- Documentation/git-reflog.txt | 17 +- Documentation/git-rerere.txt | 2 +- Documentation/git-send-pack.txt | 3 +- Documentation/git-show-branch.txt | 4 +- Documentation/git-show-ref.txt | 4 +- Documentation/git-sparse-checkout.txt | 2 +- Documentation/git-stash.txt | 17 +- Documentation/git-status.txt | 2 +- Documentation/git-tag.txt | 2 +- Documentation/git-update-server-info.txt | 8 +- Documentation/git-upload-archive.txt | 4 +- Documentation/git-var.txt | 2 +- Documentation/git-verify-commit.txt | 2 +- Documentation/git-verify-pack.txt | 2 +- Documentation/git-verify-tag.txt | 2 +- Documentation/git-worktree.txt | 3 +- builtin/blame.c | 26 ++- builtin/bugreport.c | 3 +- builtin/bundle.c | 38 ++-- builtin/cat-file.c | 2 +- builtin/clean.c | 2 +- builtin/commit-graph.c | 10 +- builtin/commit-tree.c | 5 +- builtin/commit.c | 11 +- builtin/credential-cache--daemon.c | 4 +- builtin/describe.c | 5 +- builtin/diagnose.c | 3 +- builtin/diff-files.c | 1 + builtin/diff-index.c | 3 +- builtin/diff-tree.c | 6 +- builtin/diff.c | 3 +- builtin/for-each-repo.c | 2 +- builtin/fsck.c | 5 +- builtin/hash-object.c | 5 +- builtin/help.c | 2 +- builtin/init-db.c | 5 +- builtin/interpret-trailers.c | 4 +- builtin/ls-remote.c | 2 +- builtin/merge-base.c | 2 +- builtin/pack-objects.c | 4 +- builtin/pack-redundant.c | 2 +- builtin/pack-refs.c | 2 +- builtin/read-tree.c | 4 +- builtin/rerere.c | 2 +- builtin/rev-list.c | 3 +- builtin/revert.c | 9 +- builtin/rm.c | 4 +- builtin/send-pack.c | 1 + builtin/show-branch.c | 3 +- builtin/show-ref.c | 4 +- builtin/sparse-checkout.c | 2 +- builtin/stash.c | 73 ++++--- builtin/symbolic-ref.c | 5 +- builtin/tag.c | 10 +- builtin/unpack-file.c | 2 +- builtin/update-server-info.c | 2 +- builtin/upload-archive.c | 2 +- builtin/upload-pack.c | 3 +- builtin/verify-pack.c | 2 +- builtin/worktree.c | 110 +++++++--- help.c | 2 +- t/helper/test-proc-receive.c | 2 +- t/t0450-txt-doc-vs-help.sh | 199 ++++++++++++++++++ 78 files changed, 550 insertions(+), 185 deletions(-) create mode 100755 t/t0450-txt-doc-vs-help.sh
Range-diff against v1:
1: b8cbd443987 ! 1: aecd3ff41f2 CodingGuidelines: update and clarify command-line conventions
@@ Documentation/CodingGuidelines: Writing Documentation:
[-q | --quiet]
[--utf8 | --no-utf8]
-+ Use spacing around "|" token(s), but not on the inside of "[]()"
-+ tokens:
++ Use spacing around "|" token(s), but not immediately after opening or
++ before closing a [] or () pair:
+ Do: [-q | --quiet]
+ Don't: [-q|--quiet]
+
2: 66286fa3af7 = 2: 63145b58504 builtin/bundle.c: use \t, not fix indentation 2-SP indentation
3: b49268615c3 = 3: 6bcfab04cbe bundle: define subcommand -h in terms of command -h
4: 22c3d1a73dc = 4: 707cf48a900 blame: use a more detailed usage_msg_optf() error on bad -L
5: dc66db38a62 = 5: ad0216f798e doc SYNOPSIS: don't use ' for subcommands
6: 0b946d60fcc = 6: adc18d392b5 doc SYNOPSIS: consistently use ' for commands
7: a070c97f29b ! 7: 3531d531a3f doc SYNOPSIS & -h: fix incorrect alternates syntax
@@ Commit message
"[(-o | --option) <argument>]", we were previously claiming that only
the long option accepted the "<argument>", which isn't what we meant.
- Unlike a preceding commit where this was fixed for commands which had
- inconsistent "-h" and *.txt, for "stash" it's been with us in both the
- "-h" and *.txt since bd514cada4b (stash: introduce 'git stash store',
- 2013-06-15).
+ This issue has been with us in both the "-h" and *.txt versions since
+ bd514cada4b (stash: introduce 'git stash store', 2013-06-15).
+
+ There are also issues with the alternates syntax for "bugreport" and
+ "diagnose", but in those cases only for one of *.c or *.txt, not
+ both. Those issues will be fixed in a subsequent "consistency" commit.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
8: 75c39a2ff83 = 8: 4c68003904f built-ins: consistently add "\n" between "usage" and options
9: f79a6ead8b0 = 9: a7d57827067 doc txt & -h consistency: word-wrap
10: 965f6b3b3cb = 10: 93e63821bc6 doc txt & -h consistency: fix incorrect alternates syntax
11: 698d8d3d53a = 11: aaa36012fa2 doc txt & -h consistency: add "-z" to cat-file "-h"
12: 55ce0f8632f = 12: 6501b9d1ecc doc txt & -h consistency: add missing "]" to bugreport "-h"
13: d88690fa849 = 13: 5f421314536 doc txt & -h consistency: correct padding around "[]()"
14: 12ec2627504 = 14: 6354bfea1b2 stash doc SYNOPSIS & -h: correct padding around "[]()"
15: 33d47a8a827 = 15: 28e1edaf68e doc txt & -h consistency: use "<options>", not "<options>..."
16: 1adbe9b7d12 = 16: 8cc40e09124 t/helper/test-proc-receive.c: use "<options>", not "<options>..."
17: 517f9f9a53f = 17: 97873747a1e doc txt & -h consistency: fix mismatching labels
18: df312ad3ceb = 18: 301280c9c3a doc txt & -h consistency: add or fix optional "--" syntax
19: 77cf58aa9c7 = 19: 1b51906fa07 doc txt & -h consistency: make output order consistent
20: f6ecf6a38af ! 20: 1c2bc223c5d doc txt & -h consistency: add missing options and labels
@@ builtin/tag.c
- " [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]"),
+ N_("git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\n"
+ " [--points-at <object>] [--column[=<options>] | --no-column]\n"
-+ "[--create-reflog] [--sort=<key>] [--format=<format>]\n"
-+ "[--merged <commit>] [--no-merged <commit>] [<pattern>...]"),
++ " [--create-reflog] [--sort=<key>] [--format=<format>]\n"
++ " [--merged <commit>] [--no-merged <commit>] [<pattern>...]"),
N_("git tag -v [--format=<format>] <tagname>..."),
NULL
};
21: 50e1a8c2b1e = 21: 5785ed1d667 doc txt & -h consistency: make "rerere" consistent
22: 92c178d5303 = 22: fde75be474a doc txt & -h consistency: make "read-tree" consistent
23: dee17f861b2 = 23: a6a43d0b3fd doc txt & -h consistency: make "bundle" consistent
24: 8cc52c68b67 = 24: a4feebc5434 doc txt & -h consistency: use "git foo" form, not "git-foo"
25: 3b0295e3467 = 25: a4d75ea691c doc txt & -h consistency: add missing options
26: 3907f349948 = 26: ac62cda1ab2 doc txt & -h consistency: make "stash" consistent
27: f6c9fb63a08 = 27: 42415194e3f doc txt & -h consistency: make "annotate" consistent
28: 6607ed3e343 = 28: 42076626a08 doc txt & -h consistency: use "[<label>...]" for "zero or more"
29: dc32043b203 = 29: a57b00648dc doc txt & -h consistency: make "diff-tree" consistent
30: 0aea4ee2e03 = 30: 7289ab9e09b doc txt & -h consistency: make "commit" consistent
31: 5da768a04bc = 31: 61a3c002690 reflog doc: list real subcommands up-front
32: 5fa403db45a = 32: a59f78d80c8 worktree: define subcommand -h in terms of command -h
33: 280c3b56d97 = 33: a63d8017381 doc txt & -h consistency: make "worktree" consistent
34: c15c1422055 ! 34: aef2b7356dc tests: start asserting that *.txt SYNOPSIS matches -h output
@@ t/t0450-txt-doc-vs-help.sh (new)
+ /^$/d;
+ s/^usage: //;
+ s/^ *or: //;
-+ p
++ p;
+ }' <out
+}
+
@@ t/t0450-txt-doc-vs-help.sh (new)
+test_debug '>failing'
+while read builtin
+do
++ test_expect_success "$builtin -h output has no \t" '
++ builtin_to_synopsis "$builtin" >help.raw &&
++ ! grep "$HT" help.raw
++ '
++
+ txt="$(builtin_to_txt "$builtin")" &&
+ preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
+
-: ----------- > 35: c92a4f52a8c tests: assert consistent whitespace in -h outputA manually produced doc-diff, as noted above:
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-annotate.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-annotate.1
index e1098d7841e..e696e5a03c7 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-annotate.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-annotate.1
@@ -4,7 +4,7 @@ NAME
git-annotate - Annotate file lines with commit information
SYNOPSIS
- git annotate [<options>] <file> [<revision>]
+ git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>
DESCRIPTION
Annotates each line in the given file with information from the commit
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-clean.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-clean.1
index cd823d5c176..13e20af3996 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-clean.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-clean.1
@@ -4,7 +4,7 @@ NAME
git-clean - Remove untracked files from the working tree
SYNOPSIS
- git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...
+ git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]
DESCRIPTION
Cleans the working tree by recursively removing files that are not
@@ -14,16 +14,16 @@ DESCRIPTION
is specified, ignored files are also removed. This can, for example, be
useful to remove all build products.
- If any optional <path>... arguments are given, only those paths are
+ If any optional <pathspec>... arguments are given, only those paths are
affected.
OPTIONS
-d
- Normally, when no <path> is specified, git clean will not recurse
- into untracked directories to avoid removing too much. Specify -d
- to have it recurse into such directories as well. If any paths are
- specified, -d is irrelevant; all untracked files matching the
- specified paths (with exceptions for nested git directories
+ Normally, when no <pathspec> is specified, git clean will not
+ recurse into untracked directories to avoid removing too much.
+ Specify -d to have it recurse into such directories as well. If any
+ paths are specified, -d is irrelevant; all untracked files matching
+ the specified paths (with exceptions for nested git directories
mentioned under --force) will be removed.
-f, --force
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-commit-graph.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-commit-graph.1
index 919c4015a5b..10e5b7f1fb9 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-commit-graph.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-commit-graph.1
@@ -5,7 +5,10 @@ NAME
SYNOPSIS
git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]
- git commit-graph write <options> [--object-dir <dir>] [--[no-]progress]
+ git commit-graph write [--object-dir <dir>] [--append]
+ [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]
+ [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]
+ <split options>
DESCRIPTION
Manage the serialized commit-graph file.
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-credential-cache--daemon.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-credential-cache--daemon.1
index 6199b539d04..e81cabc3e9a 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-credential-cache--daemon.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-credential-cache--daemon.1
@@ -5,7 +5,7 @@ NAME
memory
SYNOPSIS
- git credential-cache--daemon [--debug] <socket>
+ git credential-cache--daemon [--debug] <socket-path>
DESCRIPTION
Note
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-diff-files.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-diff-files.1
index b0f4ed10de0..91c261e610d 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-diff-files.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-diff-files.1
@@ -4,7 +4,7 @@ NAME
git-diff-files - Compares files in the working tree and the index
SYNOPSIS
- git diff-files [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]
+ git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]
DESCRIPTION
Compares the files in the working tree and the index. When paths are
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-hash-object.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-hash-object.1
index c7627bbf999..674c62143c8 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-hash-object.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-hash-object.1
@@ -5,7 +5,8 @@ NAME
a file
SYNOPSIS
- git hash-object [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...
+ git hash-object [-t <type>] [-w] [--path=<file>|--no-filters]
+ [--stdin [--literally]] [--] <file>...
git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]
DESCRIPTION
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-interpret-trailers.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-interpret-trailers.1
index 1eaf26fec4c..ac4dfeaa0cf 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-interpret-trailers.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-interpret-trailers.1
@@ -5,8 +5,9 @@ NAME
messages
SYNOPSIS
- git interpret-trailers [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]
- git interpret-trailers [<options>] [--parse] [<file>...]
+ git interpret-trailers [--in-place] [--trim-empty]
+ [(--trailer <token>[(=|:)<value>])...]
+ [--parse] [<file>...]
DESCRIPTION
Help parsing or adding trailers lines, that look similar to RFC 822
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-merge-base.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-merge-base.1
index bb77c49baed..700d00f5e86 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-merge-base.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-merge-base.1
@@ -4,8 +4,8 @@ NAME
git-merge-base - Find as good common ancestors as possible for a merge
SYNOPSIS
- git merge-base [-a|--all] <commit> <commit>...
- git merge-base [-a|--all] --octopus <commit>...
+ git merge-base [-a | --all] <commit> <commit>...
+ git merge-base [-a | --all] --octopus <commit>...
git merge-base --is-ancestor <commit> <commit>
git merge-base --independent <commit>...
git merge-base --fork-point <ref> [<commit>]
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-mv.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-mv.1
index 68bd3298b6d..c608c146efc 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-mv.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-mv.1
@@ -4,7 +4,7 @@ NAME
git-mv - Move or rename a file, a directory, or a symlink
SYNOPSIS
- git mv <options>... <args>...
+ git mv [<options>] <source>... <destination>
DESCRIPTION
Move or rename a file, directory or symlink.
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-pack-redundant.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-pack-redundant.1
index 6336769ea00..36e19089eda 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-pack-redundant.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-pack-redundant.1
@@ -4,7 +4,7 @@ NAME
git-pack-redundant - Find redundant pack files
SYNOPSIS
- git pack-redundant [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )
+ git pack-redundant [--verbose] [--alt-odb] (--all | <pack-filename>...)
DESCRIPTION
This program computes which packs in your repository are redundant. The
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-prune-packed.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-prune-packed.1
index 2de5e6f2ddf..542cbe2780c 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-prune-packed.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-prune-packed.1
@@ -4,7 +4,7 @@ NAME
git-prune-packed - Remove extra objects that are already in pack files
SYNOPSIS
- git prune-packed [-n|--dry-run] [-q|--quiet]
+ git prune-packed [-n | --dry-run] [-q | --quiet]
DESCRIPTION
This program searches the $GIT_OBJECT_DIRECTORY for all objects that
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-read-tree.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-read-tree.1
index 2d7366df2dc..0d08a46f13b 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-read-tree.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-read-tree.1
@@ -4,7 +4,7 @@ NAME
git-read-tree - Reads tree information into the index
SYNOPSIS
- git read-tree [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]
+ git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)
[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]
(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-receive-pack.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-receive-pack.1
index 557b090b02e..bcd953a65f7 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-receive-pack.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-receive-pack.1
@@ -4,7 +4,7 @@ NAME
git-receive-pack - Receive what is pushed into the repository
SYNOPSIS
- git-receive-pack <directory>
+ git receive-pack <git-dir>
DESCRIPTION
Invoked by git send-pack and updates the repository with the
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-reflog.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-reflog.1
index 78f0c8969d6..97101386014 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-reflog.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-reflog.1
@@ -4,19 +4,16 @@ NAME
git-reflog - Manage reflog information
SYNOPSIS
- git reflog <subcommand> <options>
+ git reflog [show] [<log-options>] [<ref>]
+ git reflog expire [--expire=<time>] [--expire-unreachable=<time>]
+ [--rewrite] [--updateref] [--stale-fix]
+ [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
+ git reflog delete [--rewrite] [--updateref]
+ [--dry-run | -n] [--verbose] <ref>@{<specifier>}...
+ git reflog exists <ref>
DESCRIPTION
- The command takes various subcommands, and different options depending
- on the subcommand:
-
- git reflog [show] [<log-options>] [<ref>]
- git reflog expire [--expire=<time>] [--expire-unreachable=<time>]
- [--rewrite] [--updateref] [--stale-fix]
- [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
- git reflog delete [--rewrite] [--updateref]
- [--dry-run | -n] [--verbose] <ref>@{<specifier>}...
- git reflog exists <ref>
+ This command manages the information recorded in the reflogs.
Reference logs, or "reflogs", record when the tips of branches and
other references were updated in the local repository. Reflogs are
@@ -26,7 +23,8 @@ DESCRIPTION
week ago in this local repository", and so on. See gitrevisions(7) for
more details.
- This command manages the information recorded in the reflogs.
+ The command takes various subcommands, and different options depending
+ on the subcommand:
The "show" subcommand (which is also the default, in the absence of any
subcommands) shows the log of the reference provided in the
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-rerere.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-rerere.1
index 92b7d74d266..7fe89de8d53 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-rerere.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-rerere.1
@@ -4,7 +4,7 @@ NAME
git-rerere - Reuse recorded resolution of conflicted merges
SYNOPSIS
- git rerere [clear|forget <pathspec>|diff|remaining|status|gc]
+ git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]
DESCRIPTION
In a workflow employing relatively long lived topic branches, the
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-send-pack.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-send-pack.1
index 56700af6311..f727babc314 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-send-pack.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-send-pack.1
@@ -4,7 +4,8 @@ NAME
git-send-pack - Push objects over Git protocol to another repository
SYNOPSIS
- git send-pack [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
+ git send-pack [--mirror] [--dry-run] [--force]
+ [--receive-pack=<git-receive-pack>]
[--verbose] [--thin] [--atomic]
[--[no-]signed|--signed=(true|false|if-asked)]
[<host>:]<directory> (--all | <ref>...)
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-show-branch.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-show-branch.1
index b81c4999fa8..29480d4f8d7 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-show-branch.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-show-branch.1
@@ -4,12 +4,12 @@ NAME
git-show-branch - Show branches and their commits
SYNOPSIS
- git show-branch [-a|--all] [-r|--remotes] [--topo-order | --date-order]
+ git show-branch [-a | --all] [-r | --remotes] [--topo-order | --date-order]
[--current] [--color[=<when>] | --no-color] [--sparse]
[--more=<n> | --list | --independent | --merge-base]
[--no-name | --sha1-name] [--topics]
[(<rev> | <glob>)...]
- git show-branch (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]
+ git show-branch (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]
DESCRIPTION
Shows the commit ancestry graph starting from the commits named with
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-show-ref.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-show-ref.1
index 05008ff520e..c9cb2839742 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-show-ref.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-show-ref.1
@@ -4,8 +4,8 @@ NAME
git-show-ref - List references in a local repository
SYNOPSIS
- git show-ref [-q|--quiet] [--verify] [--head] [-d|--dereference]
- [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]
+ git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference]
+ [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]
[--heads] [--] [<pattern>...]
git show-ref --exclude-existing[=<pattern>]
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-sparse-checkout.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-sparse-checkout.1
index 93c601af41d..42f20178480 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-sparse-checkout.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-sparse-checkout.1
@@ -5,7 +5,7 @@ NAME
files
SYNOPSIS
- git sparse-checkout <subcommand> [<options>]
+ git sparse-checkout (init | list | set | add | reapply | disable) [<options>]
DESCRIPTION
This command is used to create sparse checkouts, which change the
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-stash.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-stash.1
index 27123a702e3..e56c0d42f00 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-stash.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-stash.1
@@ -5,17 +5,20 @@ NAME
SYNOPSIS
git stash list [<log-options>]
- git stash show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]
- git stash drop [-q|--quiet] [<stash>]
- git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>]
+ git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
+ git stash drop [-q | --quiet] [<stash>]
+ git stash pop [--index] [-q | --quiet] [<stash>]
+ git stash apply [--index] [-q | --quiet] [<stash>]
git stash branch <branchname> [<stash>]
- git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]
- [-u|--include-untracked] [-a|--all] [-m|--message <message>]
+ git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+ [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]]
+ git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+ [-u | --include-untracked] [-a | --all] [<message>]
git stash clear
git stash create [<message>]
- git stash store [-m|--message <message>] [-q|--quiet] <commit>
+ git stash store [(-m | --message) <message>] [-q | --quiet] <commit>
DESCRIPTION
Use git stash when you want to record the current state of the working
@@ -39,7 +42,7 @@ DESCRIPTION
COMMANDS
push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index]
- [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message
+ [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message)
<message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--]
[<pathspec>...]
Save your local modifications to a new stash entry and roll them
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-status.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-status.1
index 40481e33502..def2218250f 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-status.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-status.1
@@ -4,7 +4,7 @@ NAME
git-status - Show the working tree status
SYNOPSIS
- git status [<options>...] [--] [<pathspec>...]
+ git status [<options>] [--] [<pathspec>...]
DESCRIPTION
Displays paths that have differences between the index file and the
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-tag.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-tag.1
index 7b8a1f7121c..72082aade13 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-tag.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-tag.1
@@ -4,7 +4,7 @@ NAME
git-tag - Create, list, delete or verify a tag object signed with GPG
SYNOPSIS
- git tag [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
+ git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
<tagname> [<commit> | <object>]
git tag -d <tagname>...
git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-update-server-info.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-update-server-info.1
index 8453bc47398..5495562a6d7 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-update-server-info.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-update-server-info.1
@@ -5,7 +5,7 @@ NAME
servers
SYNOPSIS
- git update-server-info
+ git update-server-info [-f | --force]
DESCRIPTION
A dumb server that does not do on-the-fly pack generations must have
@@ -14,6 +14,10 @@ DESCRIPTION
references and packs the server has. This command generates such
auxiliary files.
+OPTIONS
+ -f, --force
+ Allow adding otherwise ignored files.
+
OUTPUT
Currently the command updates the following files. Please see
gitrepository-layout(5) for description of what they are for:
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-upload-archive.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-upload-archive.1
index 95e69407775..4f81618976a 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-upload-archive.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-upload-archive.1
@@ -4,7 +4,7 @@ NAME
git-upload-archive - Send archive back to git-archive
SYNOPSIS
- git upload-archive <directory>
+ git upload-archive <repository>
DESCRIPTION
Invoked by git archive --remote and sends a generated archive to the
@@ -46,7 +46,7 @@ SECURITY
non-smart-http.
OPTIONS
- <directory>
+ <repository>
The repository to get a tar archive from.
GIT
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-var.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-var.1
index e8981b47f97..dc25589cc08 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-var.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-var.1
@@ -4,7 +4,7 @@ NAME
git-var - Show a Git logical variable
SYNOPSIS
- git var ( -l | <variable> )
+ git var (-l | <variable>)
DESCRIPTION
Prints a Git logical variable.
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-commit.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-commit.1
index 0d7dd5135b6..e7884d403a4 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-commit.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-commit.1
@@ -4,7 +4,7 @@ NAME
git-verify-commit - Check the GPG signature of commits
SYNOPSIS
- git verify-commit <commit>...
+ git verify-commit [-v | --verbose] <commit>...
DESCRIPTION
Validates the GPG signature created by git commit -S.
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-pack.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-pack.1
index 7dc7eac065c..4c8cc24ab06 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-pack.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-pack.1
@@ -4,7 +4,7 @@ NAME
git-verify-pack - Validate packed Git archive files
SYNOPSIS
- git verify-pack [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ...
+ git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...
DESCRIPTION
Reads given idx file for packed Git archive created with the git
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-tag.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-tag.1
index 58d3d9ad5dd..02b8f38db8d 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-tag.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-tag.1
@@ -4,7 +4,7 @@ NAME
git-verify-tag - Check the GPG signature of tags
SYNOPSIS
- git verify-tag [--format=<format>] <tag>...
+ git verify-tag [-v | --verbose] [--format=<format>] <tag>...
DESCRIPTION
Validates the gpg signature created by git tag.
diff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-worktree.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-worktree.1
index 40ba511d7a8..cb5aebfca95 100644
--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-worktree.1
+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-worktree.1
@@ -4,7 +4,8 @@ NAME
git-worktree - Manage multiple working trees
SYNOPSIS
- git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]
+ git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]
+ [-b <new-branch>] <path> [<commit-ish>]
git worktree list [-v | --porcelain [-z]]
git worktree lock [--reason <string>] <worktree>
git worktree move <worktree> <new-path>-- 2.38.0.rc1.925.gb61c5ccd7da