[PATCH v3 00/36] doc/UX: make txt & -h output more consistent
- From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- Date
- Sep 30, 2022, 18:07 UTC
- Message-ID
- <cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com>
- In-Reply-To
- <cover-v2-00.35-00000000000-20220928T082458Z-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/; For v2 see: https://lore.kernel.org/git/cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com/
Changes since v2:
* Numerous issues raised by Eric Sunshine, thanks a lot! I believe this re-roll addresses all of them.
* The 1/36 commit message attempts to explain the --foo=(x|y) v.s. (--foo | --bar) whitespace inconsistency.
* The list of command mismatches is now a file at t/t0450/txt-help-mismatches, instead of being embedded in the test (per Junio's request).
Ævar Arnfjörð Bjarmason (36): CodingGuidelines: update and clarify command-line conventions builtin/bundle.c: indent with tabs 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 SYNOPSIS & -h: word-wrap 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: balance unbalanced "[" and "]" 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 | 14 +- 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 | 5 +- 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 | 136 ++++++++++++++++++ t/t0450/txt-help-mismatches | 58 ++++++++ 79 files changed, 544 insertions(+), 185 deletions(-) create mode 100755 t/t0450-txt-doc-vs-help.sh create mode 100644 t/t0450/txt-help-mismatches
Range-diff against v2:
1: aecd3ff41f2 ! 1: 1611913e321 CodingGuidelines: update and clarify command-line conventions
@@ Commit message
alternatives, this is not a new policy, but just codifies what's
already the pattern in the most wide use in the documentation.
+ Having a space around " | " for flags, but not for flag values is
+ inconsistent, but this style guide codifies existing
+ patterns. Grepping shows that we don't have any instance matching the
+ second "Don't" example:
+
+ git grep -E -h -o '=\([^)]+\)' -- builtin Documentation/
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/CodingGuidelines ##
2: 63145b58504 ! 2: b2d76494a34 builtin/bundle.c: use \t, not fix indentation 2-SP indentation
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Commit message ##
- builtin/bundle.c: use \t, not fix indentation 2-SP indentation
+ builtin/bundle.c: indent with tabs
Fix indentation issues introduced with 73c3253d75e (bundle: framework
for options before bundle file, 2019-11-10), and carried forward in
3: 6bcfab04cbe = 3: 953a72abee1 bundle: define subcommand -h in terms of command -h
4: 707cf48a900 = 4: a8312c50f01 blame: use a more detailed usage_msg_optf() error on bad -L
5: ad0216f798e = 5: ec977f7c8fe doc SYNOPSIS: don't use ' for subcommands
6: adc18d392b5 = 6: b0ae035500c doc SYNOPSIS: consistently use ' for commands
7: 3531d531a3f = 7: 829bdf58499 doc SYNOPSIS & -h: fix incorrect alternates syntax
8: 4c68003904f ! 8: e9924890620 built-ins: consistently add "\n" between "usage" and options
@@ Commit message
As we'll see in a subsequent commit this also helps to make the "git
<cmd> -h" output more easily machine-readable, as we can assume that
- the usage usage information is separated from the options by an empty
- line.
+ the usage information is separated from the options by an empty line.
+
+ Note that "COMMON_DIFF_OPTIONS_HELP" starts with a "\n", so the
+ seeming omission of a "\n" here is correct, the second one is provided
+ by the macro.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
-: ----------- > 9: 516af07e8a8 doc SYNOPSIS & -h: word-wrap
9: a7d57827067 ! 10: 1a02f7c76cd doc txt & -h consistency: word-wrap
@@ Commit message
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- ## Documentation/git-hash-object.txt ##
-@@ Documentation/git-hash-object.txt: git-hash-object - Compute object ID and optionally creates a blob from a file
- SYNOPSIS
- --------
- [verse]
--'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
-
## Documentation/git-worktree.txt ##
@@ Documentation/git-worktree.txt: git-worktree - Manage multiple working trees
SYNOPSIS
10: 93e63821bc6 = 11: 7794c3d6ef5 doc txt & -h consistency: fix incorrect alternates syntax
11: aaa36012fa2 = 12: 357a228000c doc txt & -h consistency: add "-z" to cat-file "-h"
12: 6501b9d1ecc ! 13: 57cbaee9826 doc txt & -h consistency: add missing "]" to bugreport "-h"
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Commit message ##
- doc txt & -h consistency: add missing "]" to bugreport "-h"
+ doc txt & -h consistency: balance unbalanced "[" and "]"
Fix a "-h" output syntax issue introduced when "--diagnose" was added
in aac0e8ffeee (builtin/bugreport.c: create '--diagnose' option,
2022-08-12): We need to close the "[" we opened. The
corresponding *.txt change did not have the same issue.
+ The "help -h" output then had one "]" too many, which is an issue
+ introduced in b40845293b5 (help: correct the usage string in -h and
+ documentation, 2021-09-10).
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## builtin/bugreport.c ##
@@ builtin/bugreport.c: static void get_populated_hooks(struct strbuf *hook_info, i
NULL
};
+
+ ## builtin/help.c ##
+@@ builtin/help.c: static struct option builtin_help_options[] = {
+ };
+
+ static const char * const builtin_help_usage[] = {
+- "git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]",
++ "git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]",
+ N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
+ "git help [-g|--guides]",
+ "git help [-c|--config]",
13: 5f421314536 ! 14: a29af2dcc4f doc txt & -h consistency: correct padding around "[]()"
@@ Documentation/git-diff-files.txt: git-diff-files - Compares files in the working
DESCRIPTION
-----------
+ ## Documentation/git-hash-object.txt ##
+@@ Documentation/git-hash-object.txt: git-hash-object - Compute object ID and optionally creates a blob from a file
+ SYNOPSIS
+ --------
+ [verse]
+-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]
++'git hash-object' [-t <type>] [-w] [--path=<file> | --no-filters]
+ [--stdin [--literally]] [--] <file>...
+ 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]
+
+
## Documentation/git-merge-base.txt ##
@@ Documentation/git-merge-base.txt: git-merge-base - Find as good common ancestors as possible for a merge
SYNOPSIS
@@ Documentation/git-rerere.txt: git-rerere - Reuse recorded resolution of conflict
DESCRIPTION
-----------
+ ## Documentation/git-send-pack.txt ##
+@@ Documentation/git-send-pack.txt: SYNOPSIS
+ [verse]
+ 'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
+ [--verbose] [--thin] [--atomic]
+- [--[no-]signed|--signed=(true|false|if-asked)]
++ [--[no-]signed | --signed=(true|false|if-asked)]
+ [<host>:]<directory> (--all | <ref>...)
+
+ DESCRIPTION
+
## Documentation/git-show-branch.txt ##
@@ Documentation/git-show-branch.txt: git-show-branch - Show branches and their commits
SYNOPSIS
@@ builtin/bugreport.c: static void get_populated_hooks(struct strbuf *hook_info, i
NULL
};
+ ## builtin/commit-graph.c ##
+@@
+
+ #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
+ N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
+- " [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n" \
++ " [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n" \
+ " [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
+ " <split options>")
+
+
## builtin/diagnose.c ##
@@
#include "diagnose.h"
14: 6354bfea1b2 = 15: 589705cf6fa stash doc SYNOPSIS & -h: correct padding around "[]()"
15: 28e1edaf68e ! 16: db850539d2a doc txt & -h consistency: use "<options>", not "<options>..."
@@ Commit message
"[<options>]" form to indicate an arbitrary number of options, let's
do the same in these cases, which were the odd ones out.
- In the case of "mv" let's add the missing "[]" to indicate that these
- are optional.
+ In the case of "mv" and "sparse-checkout" let's add the missing "[]"
+ to indicate that these are optional.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
@@ builtin/pack-objects.c: static inline void oe_set_delta_size(struct packing_data
NULL
};
+
+ ## builtin/sparse-checkout.c ##
+@@
+ static const char *empty_base = "";
+
+ static char const * const builtin_sparse_checkout_usage[] = {
+- N_("git sparse-checkout (init | list | set | add | reapply | disable) <options>"),
++ N_("git sparse-checkout (init | list | set | add | reapply | disable) [<options>]"),
+ NULL
+ };
+
16: 8cc40e09124 = 17: 041aa64f3c7 t/helper/test-proc-receive.c: use "<options>", not "<options>..."
17: 97873747a1e ! 18: 3a439c4401d doc txt & -h consistency: fix mismatching labels
@@ builtin/commit-graph.c
#define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
- N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
+ N_("git commit-graph write [--object-dir <dir>] [--append]\n" \
- " [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n" \
+ " [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n" \
" [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
" <split options>")
@@ builtin/upload-archive.c
static const char deadchild[] =
"git upload-archive: archiver died with error";
+ ## builtin/verify-pack.c ##
+@@ builtin/verify-pack.c: static int verify_one_pack(const char *path, unsigned int flags, const char *has
+ }
+
+ static const char * const verify_pack_usage[] = {
+- N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>..."),
++ N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx..."),
+ NULL
+ };
+
+
## builtin/worktree.c ##
@@ builtin/worktree.c: static const char * const worktree_usage[] = {
N_("git worktree prune [<options>]"),
18: 301280c9c3a ! 19: 3bfdd3fb79e doc txt & -h consistency: add or fix optional "--" syntax
@@ builtin/rev-list.c
"\n"
" limiting output:\n"
" --max-count=<n>\n"
+
+ ## builtin/verify-pack.c ##
+@@ builtin/verify-pack.c: static int verify_one_pack(const char *path, unsigned int flags, const char *has
+ }
+
+ static const char * const verify_pack_usage[] = {
+- N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx..."),
++ N_("git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx..."),
+ NULL
+ };
+
19: 1b51906fa07 = 20: 98bdd0353cf doc txt & -h consistency: make output order consistent
20: 1c2bc223c5d ! 21: 1713227d497 doc txt & -h consistency: add missing options and labels
@@ Documentation/git-send-pack.txt: git-send-pack - Push objects over Git protocol
+'git send-pack' [--mirror] [--dry-run] [--force]
+ [--receive-pack=<git-receive-pack>]
[--verbose] [--thin] [--atomic]
- [--[no-]signed|--signed=(true|false|if-asked)]
+ [--[no-]signed | --signed=(true|false|if-asked)]
[<host>:]<directory> (--all | <ref>...)
## Documentation/git-sparse-checkout.txt ##
@@ builtin/diff-index.c
"\n"
COMMON_DIFF_OPTIONS_HELP;
- ## builtin/help.c ##
-@@ builtin/help.c: static struct option builtin_help_options[] = {
- };
-
- static const char * const builtin_help_usage[] = {
-- "git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]",
-+ "git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]",
- N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
- "git help [-g|--guides]",
- "git help [-c|--config]",
-
## builtin/ls-remote.c ##
@@
@@ builtin/send-pack.c: static const char * const send_pack_usage[] = {
N_("git send-pack [--mirror] [--dry-run] [--force]\n"
" [--receive-pack=<git-receive-pack>]\n"
" [--verbose] [--thin] [--atomic]\n"
-+ " [--[no-]signed|--signed=(true|false|if-asked)]\n"
++ " [--[no-]signed | --signed=(true|false|if-asked)]\n"
" [<host>:]<directory> (--all | <ref>...)"),
NULL,
};
- ## builtin/sparse-checkout.c ##
-@@
- static const char *empty_base = "";
-
- static char const * const builtin_sparse_checkout_usage[] = {
-- N_("git sparse-checkout (init | list | set | add | reapply | disable) <options>"),
-+ N_("git sparse-checkout (init | list | set | add | reapply | disable) [<options>]"),
- NULL
- };
-
-
## builtin/symbolic-ref.c ##
@@
#include "parse-options.h"
@@ builtin/upload-pack.c
};
- ## builtin/verify-pack.c ##
-@@ builtin/verify-pack.c: static int verify_one_pack(const char *path, unsigned int flags, const char *has
- }
-
- static const char * const verify_pack_usage[] = {
-- N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>..."),
-+ N_("git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx..."),
- NULL
- };
-
-
## help.c ##
@@ help.c: int cmd_version(int argc, const char **argv, const char *prefix)
struct strbuf buf = STRBUF_INIT;
21: 5785ed1d667 = 22: 702eb747c0f doc txt & -h consistency: make "rerere" consistent
22: fde75be474a = 23: 01e20b8e452 doc txt & -h consistency: make "read-tree" consistent
23: a6a43d0b3fd = 24: 7f93da79fee doc txt & -h consistency: make "bundle" consistent
24: a4feebc5434 = 25: ab109f73264 doc txt & -h consistency: use "git foo" form, not "git-foo"
25: a4d75ea691c ! 26: d57635b2707 doc txt & -h consistency: add missing options
@@ Commit message
doc txt & -h consistency: add missing options
Change those built-in commands that were attempting to exhaustively
- the options in the "-h" output to actually do so, and always
+ list the options in the "-h" output to actually do so, and always
have *.txt documentation know about the exhaustive list of options.
Let's also fix the documentation and -h output for those built-in
commands where the *.txt and -h output was a mismatch of missing
options on both sides.
+ In the case of "interpret-trailers" fixing the missing options reveals
+ that the *.txt version was implicitly claiming that the command had
+ two operating modes, which a look at the -h version (and studying the
+ documentation) will show is not the case.
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/git-commit-graph.txt ##
@@ Documentation/git-commit-graph.txt: 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]
++ [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]
+ [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]
+ <split options>
@@ builtin/fsck.c: static int mark_packed_for_connectivity(const struct object_id *
## builtin/hash-object.c ##
-@@ builtin/hash-object.c: static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,
- int cmd_hash_object(int argc, const char **argv, const char *prefix)
+@@ builtin/hash-object.c: int cmd_hash_object(int argc, const char **argv, const char *prefix)
{
static const char * const hash_object_usage[] = {
-- N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>..."),
+ N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\n"
+- " [--stdin] [--] <file>..."),
- "git hash-object --stdin-paths",
-+ N_("git hash-object [-t <type>] [-w] [--path=<file>|--no-filters]\n"
+ " [--stdin [--literally]] [--] <file>..."),
+ N_("git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]"),
NULL
26: ac62cda1ab2 ! 27: ac959d0cfc1 doc txt & -h consistency: make "stash" consistent
@@ Metadata
## Commit message ##
doc txt & -h consistency: make "stash" consistent
- Amend both the the -h output and *.txt to match one another. In this
- case the *.txt didn't list the "save" subcommand, and the "-h" was
+ Amend both the -h output and *.txt to match one another. In this case
+ the *.txt didn't list the "save" subcommand, and the "-h" was
similarly missing some commands.
Let's also convert the *.c code to use a macro definition, similar to
@@ builtin/stash.c
static const char * const git_stash_clear_usage[] = {
- "git stash clear",
-+ BUILTIN_STASH_BRANCH_USAGE,
++ BUILTIN_STASH_CLEAR_USAGE,
NULL
};
27: 42415194e3f = 28: f617375ea9e doc txt & -h consistency: make "annotate" consistent
28: 42076626a08 = 29: c96c3fc6d8d doc txt & -h consistency: use "[<label>...]" for "zero or more"
29: a57b00648dc = 30: 34b778dd176 doc txt & -h consistency: make "diff-tree" consistent
30: 7289ab9e09b = 31: 336fc749f1c doc txt & -h consistency: make "commit" consistent
31: 61a3c002690 = 32: 81024d1c3cd reflog doc: list real subcommands up-front
32: a59f78d80c8 = 33: 76e6b7d296a worktree: define subcommand -h in terms of command -h
33: a63d8017381 = 34: efd0c2c634d doc txt & -h consistency: make "worktree" consistent
34: aef2b7356dc ! 35: 22da68abce3 tests: start asserting that *.txt SYNOPSIS matches -h output
@@ Commit message
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- ## Documentation/CodingGuidelines ##
-@@ Documentation/CodingGuidelines: Writing Documentation:
-
- A few commented examples follow to provide reference when writing or
- modifying command usage strings and synopsis sections in the manual
-- pages:
-+ pages. The two should match, see t/t0450-txt-doc-vs-help.sh for
-+ (partial) regression testing.
-
- Placeholders are spelled in lowercase and enclosed in angle brackets:
- <file>
-
## t/t0450-txt-doc-vs-help.sh (new) ##
@@
+#!/bin/sh
@@ t/t0450-txt-doc-vs-help.sh (new)
+ git --list-cmds=builtins >builtins
+'
+
-+test_expect_success 'setup: list of txt v.s. help' '
-+ cat >list <<-\EOF
-+ add
-+ am
-+ apply
-+ archive
-+ bisect
-+ blame
-+ branch
-+ check-ref-format
-+ checkout
-+ checkout-index
-+ clone
-+ column
-+ config
-+ credential
-+ credential-cache
-+ credential-store
-+ fast-export
-+ fast-import
-+ fetch-pack
-+ fmt-merge-msg
-+ for-each-ref
-+ format-patch
-+ fsck-objects
-+ fsmonitor--daemon
-+ gc
-+ grep
-+ index-pack
-+ init-db
-+ log
-+ ls-files
-+ ls-tree
-+ mailinfo
-+ mailsplit
-+ maintenance
-+ merge
-+ merge-file
-+ merge-index
-+ merge-one-file
-+ multi-pack-index
-+ name-rev
-+ notes
-+ pack-objects
-+ push
-+ range-diff
-+ rebase
-+ remote
-+ remote-ext
-+ remote-fd
-+ repack
-+ reset
-+ restore
-+ rev-parse
-+ show
-+ stage
-+ switch
-+ update-index
-+ update-ref
-+ whatchanged
-+ EOF
-+'
-+
-+test_expect_success 'setup: list of txt v.s. help is sorted' '
-+ sort -u list >list.sorted &&
-+ if ! test_cmp list list.sorted
++test_expect_success 'list of txt and help mismatches is sorted' '
++ sort -u "$TEST_DIRECTORY"/t0450/txt-help-mismatches >expect &&
++ if ! test_cmp expect "$TEST_DIRECTORY"/t0450/txt-help-mismatches
+ then
-+ BUG "please keep the command list sorted"
++ BUG "please keep the list of txt and help mismatches sorted"
+ fi
+'
+
@@ t/t0450-txt-doc-vs-help.sh (new)
+ fi &&
+
+ result=
-+ if grep -q "^$builtin$" list
++ if grep -q "^$builtin$" "$TEST_DIRECTORY"/t0450/txt-help-mismatches
+ then
+ result=failure
+ else
@@ t/t0450-txt-doc-vs-help.sh (new)
+test_debug 'say "$(cat failing)"'
+
+test_done
+
+ ## t/t0450/txt-help-mismatches (new) ##
+@@
++add
++am
++apply
++archive
++bisect
++blame
++branch
++check-ref-format
++checkout
++checkout-index
++clone
++column
++config
++credential
++credential-cache
++credential-store
++fast-export
++fast-import
++fetch-pack
++fmt-merge-msg
++for-each-ref
++format-patch
++fsck-objects
++fsmonitor--daemon
++gc
++grep
++index-pack
++init-db
++log
++ls-files
++ls-tree
++mailinfo
++mailsplit
++maintenance
++merge
++merge-file
++merge-index
++merge-one-file
++multi-pack-index
++name-rev
++notes
++pack-objects
++push
++range-diff
++rebase
++remote
++remote-ext
++remote-fd
++repack
++reset
++restore
++rev-parse
++show
++stage
++switch
++update-index
++update-ref
++whatchanged
35: c92a4f52a8c = 36: b56113dd620 tests: assert consistent whitespace in -h output-- 2.38.0.rc2.935.g6b421ae1592