Volume XXII, number 279Tuesday, October 6, 2026Latest message 38 minutes ago

The Git List

News and archive of git@vger.kernel.org, since April 2005

patchfast-export: standardize usage string and SYNOPSIS

3 messages between Jul 13, 2026 and Jul 14, 2026, from Christian Couder, Junio C Hamano, Patrick Steinhardt.

Plain Markdown or JSON for tools and agents. Diffs are folded; open one to read it.

Christian CouderJul 13, 2026, 12:41 UTC on lore
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".

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
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(-)
Show changes to 3 files +2 −3

Documentation/git-fast-export.adoc, builtin/fast-export.c, t/t0450/adoc-help-mismatches

diff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc
index 297b57bb2e..719aeca244 100644
--- a/Documentation/git-fast-export.adoc
+++ b/Documentation/git-fast-export.adoc
@@ -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
 -----------
diff --git a/builtin/fast-export.c b/builtin/fast-export.c
index 0be43104dc..629d7c591a 100644
--- a/builtin/fast-export.c
+++ b/builtin/fast-export.c
@@ -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
 };
 
diff --git a/t/t0450/adoc-help-mismatches b/t/t0450/adoc-help-mismatches
index e8d6c13ccd..c4a55ff4e3 100644
--- a/t/t0450/adoc-help-mismatches
+++ b/t/t0450/adoc-help-mismatches
@@ -12,7 +12,6 @@ column
 credential
 credential-cache
 credential-store
-fast-export
 fast-import
 fetch-pack
 fmt-merge-msg

-- 
2.55.0.124.gac3b7a3d2d
Junio C HamanoJul 13, 2026, 15:54 UTC in reply to Christian Couder on lore

Re: [PATCH] fast-export: standardize usage string and SYNOPSIS

Christian Couder <christian.couder@gmail.com> writes:
> The output of `git fast-export -h` currently 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.

Show 9 quoted lines
> diff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc
> index 297b57bb2e..719aeca244 100644
> --- a/Documentation/git-fast-export.adoc
> +++ b/Documentation/git-fast-export.adoc
> @@ -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.

> +'git fast-export' [<options>] [<revision-range>] [[--] <path>...]

This updated version is much more consistent with other manual pages.

Nice.  Will queue.  Thanks.
Patrick SteinhardtJul 14, 2026, 08:54 UTC in reply to Christian Couder on lore

Re: [PATCH] fast-export: standardize usage string and SYNOPSIS

On Mon, Jul 13, 2026 at 02:41:53PM +0200, Christian Couder wrote:
Show 13 quoted lines
> diff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc
> index 297b57bb2e..719aeca244 100644
> --- a/Documentation/git-fast-export.adoc
> +++ b/Documentation/git-fast-export.adoc
> @@ -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 "|".

Show 13 quoted lines
> diff --git a/builtin/fast-export.c b/builtin/fast-export.c
> index 0be43104dc..629d7c591a 100644
> --- a/builtin/fast-export.c
> +++ b/builtin/fast-export.c
> @@ -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.
Show 12 quoted lines
> diff --git a/t/t0450/adoc-help-mismatches b/t/t0450/adoc-help-mismatches
> index e8d6c13ccd..c4a55ff4e3 100644
> --- a/t/t0450/adoc-help-mismatches
> +++ b/t/t0450/adoc-help-mismatches
> @@ -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

Back to recent threads