git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v2 09/12] fast-import: use struct option for usage string

From
Christian Couder <christian.couder@gmail.com>
Date
Aug 4, 2026, 10:03 UTC
Message-ID
<20260804100355.1299498-10-christian.couder@gmail.com>
In-Reply-To
<20260804100355.1299498-1-christian.couder@gmail.com>
Currently `git fast-import -h` shows the following on a single line:
  usage : git fast-import [--date-format=<f>] [--max-pack-size=<n>] \
                          [--big-file-threshold=<n>] [--depth=<n>] \
                          [--active-branches=<n>] \
                          [--export-marks=<marks.file>]
This output has a number of issues like:
  - It's missing a lot of options.
  - It's not consistent with the SYNOPSIS section of the doc.
  - With `--help-all` instead of `-h` additional hidden options should
    be shown, but that's not the case.
  - It's not standard style anymore.
  - Most other Git commands show additional lines for most of the
    options they support.

Also while most commands use the parse-options API to handle their options, "builtin/fast-import.c" still doesn't use it.

Let's improve on that by using the parse-options API to display the options when `-h` and `--help-all` are used.

While at it, let's make the SYNOPSIS section of "Documentation/git-fast-import.adoc" consistent with the new usage string.

This deliberately leaves it to future work to also use the parse-options API to actually parse the options.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 Documentation/git-fast-import.adoc |  2 +-
 builtin/fast-import.c              | 83 +++++++++++++++++++++++++++---
 t/t0450/adoc-help-mismatches       |  1 -
 3 files changed, 78 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc
index d68bc52b7e..7c5900e048 100644
--- a/Documentation/git-fast-import.adoc
+++ b/Documentation/git-fast-import.adoc
@@ -9,7 +9,7 @@ git-fast-import - Backend for fast Git data importers
 SYNOPSIS
 --------
 [verse]
-frontend | 'git fast-import' [<options>]
+'git fast-import' [<options>]
 
 DESCRIPTION
 -----------
diff --git a/builtin/fast-import.c b/builtin/fast-import.c
index 926afde954..bf72adf62b 100644
--- a/builtin/fast-import.c
+++ b/builtin/fast-import.c
@@ -30,6 +30,7 @@
 #include "khash.h"
 #include "date.h"
 #include "gpg-interface.h"
+#include "parse-options.h"
 
 #define PACK_ID_BITS 16
 #define MAX_PACK_ID ((1<<PACK_ID_BITS)-1)
@@ -277,16 +278,18 @@ struct fast_import_state {
 	const char *prefix;
 	int seen_data_command;
 	int allow_unsafe_features;
+	struct option *option;
 };
 
 static void fast_import_state_init(struct fast_import_state *state,
 				   int argc, const char **argv,
-				   const char *prefix)
+				   const char *prefix, struct option *option)
 {
 	memset(state, 0, sizeof(*state));
 	state->argc = argc;
 	state->argv = argv;
 	state->prefix = prefix;
+	state->option = option;
 }
 
 static void parse_argv(struct fast_import_state *state);
@@ -3935,8 +3938,10 @@ static void git_pack_config(void)
 	repo_config(the_repository, git_default_config, NULL);
 }
 
-static const char fast_import_usage[] =
-"git fast-import [--date-format=<f>] [--max-pack-size=<n>] [--big-file-threshold=<n>] [--depth=<n>] [--active-branches=<n>] [--export-marks=<marks.file>]";
+static const char *const fast_import_usage[] = {
+	N_("git fast-import [<options>]"),
+	NULL
+};
 
 static void parse_argv(struct fast_import_state *state)
 {
@@ -3965,7 +3970,7 @@ static void parse_argv(struct fast_import_state *state)
 		die(_("unknown option --%s"), a);
 	}
 	if (i != state->argc)
-		usage(fast_import_usage);
+		usage_with_options(fast_import_usage, state->option);
 
 	state->seen_data_command = 1;
 	if (import_marks_file)
@@ -3980,9 +3985,75 @@ int cmd_fast_import(int argc,
 {
 	struct fast_import_state state;
 
-	show_usage_if_asked(argc, argv, fast_import_usage);
+	unsigned long pack_size_limit, big_file_threshold;
+	char *edges, *signed_commits, *signed_tags, *date_format;
+	char *import_marks_if_exists, *submodules_from, *submodules_to;
 
-	fast_import_state_init(&state, argc, argv, prefix);
+	/*
+	 * NEEDSWORK: For now this is used only to render
+	 * `-h`/`--help-all` usage messages. The actual parsing is
+	 * done by parse_one_option()/parse_one_feature().
+	 */
+	struct option fast_import_options[] = {
+		OPT_GROUP(N_("Common")),
+		OPT_STRING_F(0, "date-format", &date_format, N_("fmt"),
+			   N_("format of the commit/tag dates"), PARSE_OPT_NONEG),
+		OPT_BOOL_F(0, "stats", &show_stats,
+			   N_("display some basic statistics (objects, packfiles and memory)"),
+			   PARSE_OPT_NONEG),
+		OPT_BOOL_F(0, "quiet", &quiet,
+			   N_("disable the output shown by --stats"), PARSE_OPT_NONEG),
+		OPT_BOOL_F(0, "force", &force_update,
+			   N_("force updating modified existing branches"), PARSE_OPT_NONEG),
+		OPT_BOOL_F(0, "done", &require_explicit_termination,
+			   N_("require a terminating 'done' command"), PARSE_OPT_NONEG),
+		OPT_UNSIGNED(0, "max-pack-size", &pack_size_limit,
+			     N_("maximum size of each output pack file")),
+		OPT_UNSIGNED(0, "big-file-threshold", &big_file_threshold,
+			     N_("maximum size of a blob that will be deltified")),
+		OPT_UNSIGNED(0, "depth", &max_depth,
+			     N_("maximum delta depth")),
+		OPT_UNSIGNED(0, "active-branches", &max_active_branches,
+			     N_("maximum number of branches to maintain active")),
+		OPT_GROUP(N_("Marks")),
+		OPT_STRING_F(0, "import-marks", &import_marks_file, N_("file"),
+			     N_("import marks from <file>"), PARSE_OPT_NONEG),
+		OPT_STRING_F(0, "import-marks-if-exists", &import_marks_if_exists, N_("file"),
+			     N_("import marks from <file> if it exists"), PARSE_OPT_NONEG),
+		OPT_STRING_F(0, "export-marks", &export_marks_file, N_("file"),
+			     N_("dump marks to <file>"), PARSE_OPT_NONEG),
+		OPT_BOOL(0, "relative-marks", &relative_marks_paths,
+			 N_("are --(import|export)-marks= paths relative to '.git/info/fast-import'?")),
+		OPT_GROUP(N_("Submodule rewrite")),
+		OPT_STRING_F(0, "rewrite-submodules-from", &submodules_from, N_("name:filename"),
+			     N_("rewrite object IDs for submodule <name> from <filename>"),
+			     PARSE_OPT_NONEG),
+		OPT_STRING_F(0, "rewrite-submodules-to", &submodules_to, N_("name:filename"),
+			     N_("rewrite object IDs for submodule <name> to <filename>"),
+			     PARSE_OPT_NONEG),
+		OPT_GROUP(N_("Signing")),
+		OPT_STRING_F(0, "signed-commits", &signed_commits, N_("mode"),
+			     N_("how to handle signed commits"),
+			     PARSE_OPT_NONEG),
+		OPT_STRING_F(0, "signed-tags", &signed_tags, N_("mode"),
+			     N_("how to handle signed tags"),
+			     PARSE_OPT_NONEG),
+		OPT_HIDDEN_GROUP(N_("Advanced")),
+		OPT_BOOL_F(0, "allow-unsafe-features", &state.allow_unsafe_features,
+			   N_("allow unsafe mark commands from the stream"),
+			   PARSE_OPT_HIDDEN | PARSE_OPT_NONEG),
+		OPT_STRING_F(0, "export-pack-edges", &edges, N_("file"),
+			     N_("dump edge commits to <file>"),
+			     PARSE_OPT_HIDDEN | PARSE_OPT_NONEG),
+		OPT_INTEGER_F(0, "cat-blob-fd", &cat_blob_fd,
+			    N_("write some responses to <fd> instead of stdout"),
+			      PARSE_OPT_HIDDEN | PARSE_OPT_NONEG),
+		OPT_END()
+	};
+
+	show_usage_with_options_if_asked(argc, argv, fast_import_usage, fast_import_options);
+
+	fast_import_state_init(&state, argc, argv, prefix, fast_import_options);
 
 	reset_pack_idx_option(&pack_idx_opts);
 	git_pack_config();
diff --git a/t/t0450/adoc-help-mismatches b/t/t0450/adoc-help-mismatches
index c4a55ff4e3..baf3b1d809 100644
--- a/t/t0450/adoc-help-mismatches
+++ b/t/t0450/adoc-help-mismatches
@@ -12,7 +12,6 @@ column
 credential
 credential-cache
 credential-store
-fast-import
 fetch-pack
 fmt-merge-msg
 format-patch
-- 
2.55.0.492.g44bba30fd7.dirty
Previous: Christian CouderNext: Christian Couder
Message 28 of 48 in “fast-import: standardize usage string and SYNOPSIS”
  1. 0/7 fast-import: standardize usage string and SYNOPSISChristian Couder, Jul 16, 2026
  2. 1/7 parse-options: introduce OPT_HIDDEN_GROUPChristian Couder, Jul 16, 2026
  3. Junio C HamanoJul 16, 2026
  4. .mailmap etiquette (was "Re: [PATCH 1/7] parse-options: introduce OPT_HIDDEN_GROUP")D. Ben Knoble, Jul 16, 2026
  5. Junio C HamanoJul 16, 2026
  6. Christian CouderAug 3, 2026
  7. 2/7 api-parse-options.adoc: document per-option flagsChristian Couder, Jul 16, 2026
  8. 3/7 api-parse-options.adoc: document hidden and OPT_*_F option macrosChristian Couder, Jul 16, 2026
  9. 4/7 fast-import: localize 'i' into the 'for' loops using itChristian Couder, Jul 16, 2026
  10. 5/7 fast-import: introduce 'struct fast_import_state'Christian Couder, Jul 16, 2026
  11. 6/7 fast-import: move command state globals into 'struct fast_import_state'Christian Couder, Jul 16, 2026
  12. 7/7 fast-import: use struct option for usage stringChristian Couder, Jul 16, 2026
  13. Junio C HamanoJul 16, 2026
  14. Christian CouderAug 3, 2026
  15. 00/12 fast-import: standardize usage string and SYNOPSISChristian Couder, Aug 4, 2026
  16. 01/12 parse-options: introduce OPT_HIDDEN_GROUPChristian Couder, Aug 4, 2026
  17. 02/12 api-parse-options.adoc: document per-option flagsChristian Couder, Aug 4, 2026
  18. Elijah NewrenAug 8, 2026
  19. Christian CouderAug 11, 2026
  20. 03/12 api-parse-options.adoc: document hidden and OPT_*_F option macrosChristian Couder, Aug 4, 2026
  21. 04/12 fast-import: localize 'i' into the 'for' loops using itChristian Couder, Aug 4, 2026
  22. 05/12 fast-import: use int for some bool flagsChristian Couder, Aug 4, 2026
  23. 06/12 fast-import: factor out option_*() functionsChristian Couder, Aug 4, 2026
  24. 07/12 fast-import: introduce 'struct fast_import_state'Christian Couder, Aug 4, 2026
  25. Elijah NewrenAug 8, 2026
  26. Christian CouderAug 11, 2026
  27. 08/12 fast-import: move command state globals into 'struct fast_import_state'Christian Couder, Aug 4, 2026
  28. 09/12 fast-import: use struct option for usage stringChristian Couder, Aug 4, 2026
  29. 10/12 fast-import: use callbacks to parse some optionsChristian Couder, Aug 4, 2026
  30. 11/12 fast-import: use parse_options() for command line optionsChristian Couder, Aug 4, 2026
  31. Elijah NewrenAug 8, 2026
  32. Christian CouderAug 11, 2026
  33. 12/12 fast-import: remove useless from_stream argumentChristian Couder, Aug 4, 2026
  34. Elijah NewrenAug 8, 2026
  35. 00/12 fast-import: standardize usage string and SYNOPSISChristian Couder, Aug 11, 2026
  36. 02/12 api-parse-options.adoc: document per-option flagsChristian Couder, Aug 11, 2026
  37. 03/12 api-parse-options.adoc: document hidden and OPT_*_F option macrosChristian Couder, Aug 11, 2026
  38. 04/12 fast-import: localize 'i' into the 'for' loops using itChristian Couder, Aug 11, 2026
  39. 05/12 fast-import: use int for some bool flagsChristian Couder, Aug 11, 2026
  40. 06/12 fast-import: factor out option_*() functionsChristian Couder, Aug 11, 2026
  41. 07/12 fast-import: introduce 'struct fast_import_state'Christian Couder, Aug 11, 2026
  42. 08/12 fast-import: move command state globals into 'struct fast_import_state'Christian Couder, Aug 11, 2026
  43. 09/12 fast-import: use struct option for usage stringChristian Couder, Aug 11, 2026
  44. 10/12 fast-import: use callbacks to parse some optionsChristian Couder, Aug 11, 2026
  45. 11/12 fast-import: use parse_options() for command line optionsChristian Couder, Aug 11, 2026
  46. 12/12 fast-import: remove useless from_stream argumentChristian Couder, Aug 11, 2026
  47. 01/12 parse-options: introduce OPT_HIDDEN_GROUPChristian Couder, Aug 11, 2026
  48. Elijah NewrenAug 12, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.