fast-export: standardize usage string and SYNOPSIS
PATCH 1/1 fast-export: standardize usage string and SYNOPSIS
The output of git fast-export -h currently starts with:
usage: git fast-export [<rev-list-opts>]
while the SYNOPSIS section in this command's documentation shows:
'git fast-export' [<options>] | 'git fast-import'
Let's make both of these consistent with each other and with other Git commands by describing the arguments with:
[<options>] [<revision-range>] [[--] <path>...]
This takes into account the following:
- git fast-export accepts both rev-list arguments and a number of genuine options of its own (--[no-]progress, --[no-]signed-tags, --[no-]signed-commits, etc).
- git fast-export was the only command using [<rev-list-opts>] while many other commands describe their revision arguments as [<revision-range>] [[--] <path>...].
- In the DESCRIPTION section of the documentation, it's already mentioned several times that the output should eventually be fed to git fast-import.
This also enables us to remove fast-export from
"t/t0450/adoc-help-mismatches".
---
CI tests passed:
https://github.com/chriscool/git/actions/runs/29245342050
Documentation/git-fast-export.adoc | 2 +- builtin/fast-export.c | 2 +- t/t0450/adoc-help-mismatches | 1 - 3 files changed, 2 insertions(+), 3 deletions(-)
Documentation/git-fast-export.adoc +1 -1
@@ -9,7 +9,7 @@ git-fast-export - Git data exporter SYNOPSIS -------- [verse] -'git fast-export' [<options>] | 'git fast-import' +'git fast-export' [<options>] [<revision-range>] [[--] <path>...] DESCRIPTION -----------
builtin/fast-export.c +1 -1
@@ -33,7 +33,7 @@#include "gpg-interface.h" static const char *const fast_export_usage[] = { -N_ ("git fast-export [<rev-list-opts>]" ), +N_ ("git fast-export [<options>] [<revision-range>] [[--] <path>...]" ),NULL };
t/t0450/adoc-help-mismatches +0 -1
@@ -12,7 +12,6 @@ column credential credential-cache credential-store -fast-export fast-import fetch-pack fmt-merge-msg
Signature · 1 line
2.55.0.124.gac3b7a3d2d
Quoted 4 lines · Christian Couder
The output of
git fast-export -hcurrently starts with:
...
This also enables us to remove fast-export from "t/t0450/adoc-help-mismatches".
Improving consistency and eliminating special cases are both positive steps forward. Nice work.
Documentation/git-fast-export.adoc git-fast-export - Git data exporter · line 12
Quoted 9 lines
Documentation/git-fast-export.adoc +0
-1@@ -9,7 +9,7 @@ git-fast-export - Git data exporter SYNOPSIS -------- [verse] -'git fast-export' [<options>] | 'git fast-import'
While this was well-intentioned (demonstrating a typical usage pattern to show readers that the command's output is meant to be consumed by 'fast-import'), it is highly unusual for a synopsis. Examples of this nature are better suited for the body of the manual pages.
Documentation/git-fast-export.adoc git-fast-export - Git data exporter · line 12
Quoted 1 line
Documentation/git-fast-export.adoc +1
-0+'git fast-export' [<options>] [<revision-range>] [[--] <path>...]
This updated version is much more consistent with other manual pages.
Nice. Will queue. Thanks.
Documentation/git-fast-export.adoc git-fast-export - Git data exporter · line 15
Quoted 13 lines · Christian Couder
Documentation/git-fast-export.adoc +1
-1@@ -9,7 +9,7 @@ git-fast-export - Git data exporter SYNOPSIS -------- [verse] -'git fast-export' [<options>] | 'git fast-import' +'git fast-export' [<options>] [<revision-range>] [[--] <path>...] DESCRIPTION -----------
Makes sense, as it is more consistent with all the other commands that we have. I don't recall any other commands that use "|".
builtin/fast-export.c line 39
Quoted 13 lines
builtin/fast-export.c +1
-1@@ -33,7 +33,7 @@#include "gpg-interface.h" static const char *const fast_export_usage[] = { -N_ ("git fast-export [<rev-list-opts>]" ), +N_ ("git fast-export [<options>] [<revision-range>] [[--] <path>...]" ),NULL };
This is being adapted to match.
t/t0450/adoc-help-mismatches column · line 17
Quoted 12 lines
t/t0450/adoc-help-mismatches +0
-1@@ -12,7 +12,6 @@ column credential credential-cache credential-store -fast-export fast-import fetch-pack fmt-merge-msg
And as both match now we can also update t0450. Nice!
Patrick