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

[PATCH v2 00/12] fast-import: standardize usage string and SYNOPSIS

From
Christian Couder <christian.couder@gmail.com>
Date
Aug 4, 2026, 10:03 UTC
Message-ID
<20260804100355.1299498-1-christian.couder@gmail.com>
In-Reply-To
<20260716165517.433849-1-christian.couder@gmail.com>

The goal of this series is to improve on `git fast-import`'s usage string as it is obsolete in many ways.

As it appeared that a good way to reach that goal was to make `git fast-import` use the parse-options API, this series also achieves this secondary goal.

Along the way it modernizes "builtin/fast-import.c" mostly by using `struct option`, by starting to remove global variables and libify that command, and by introducing a new `OPT_HIDDEN_GROUP` macro.

There are still many global variables left, so it's left to future work to finish on that direction.

Anyway the usage string is standardized and consistent with the SYNOPSIS in the docs, so that the command can be removed from "t/t0450/adoc-help-mismatches".

Using the parse-options API also enabled some code standardization and simplification.

Overview of the patches =======================

  - Patch 1/12: Introduces OPT_HIDDEN_GROUP and improves on the hidden
    option tests.
  - Patches 2/12 and 3/12: Improve on the parse-options API docs.
  - Patch 4/12: Cleans up an 'i' loop counter variable in
    cmd_fast_import().
  - Patches 5/12 and 6/12: Prepare for using the parse-option API to
    parse command line options.
  - Patches 7/12 and 8/12: Start libifying "builtin/fast-import.c" by
    introducing a 'struct fast_import_state' and using it to store
    some global variables.
  - Patch 9/12: Improves the usage string and SYNOPSIS by introducing
    `struct option`.
  - Patch 10/12: Further prepares for using the parse-option API to
    actually parse command line options by using OPT_CALLBACK.
  - Patch 11/12: Actually parses the command line options using the
    parse-option API.
  - Patch 12/12: Performs a cleanup of some functions arguments allowed
    by the previous commit.

Changes since v1 ================

Thanks to Junio for reviewing the v1.

The series has been rebased on top of recent master at 5b2471720c (The 10th batch, 2026-08-03) to avoid conflicts with recent changes especially cdaf12f762 (parse-options: exit 0 on -h, 2026-07-08).

The `Signed-off-by:` trailers now use my `christian.couder@gmail.com` address, which is also the address I send patches from, so that they match. A separate patch updating the `.mailmap` entry to make that address my primary one has been sent separately.

  - Patch 1/12 has been changed by removing `test_must_fail` in front
    of `test-tool parse-options` when the latter uses `-h` or
    `--help-all` to adapt this series to the recent changes in master.
  - Patches 5/12 and 6/12 are new and prepare for using the parse-option
    API to parse command line options.
  - Patch 9/12 (previously 7/7) has been changed a lot so that it
    reuses existing variables as much as possible instead of
    introducing a lot of new local variables.
  - Patches 10/12, 11/12 and 12/12 are new and complete the option
    parsing using the parse-option API.

Note that patch 11/12 changes the behavior of a few undocumented command line options: `--alias`, `--get-mark`, `--cat-blob`, `--ls` and `--notes` are not accepted on the command line anymore. See its commit message for details.

CI tests ========

They all pass, except one (Win+Meson test (0) where tests don't want to start, so likely unrelated), see:

https://github.com/chriscool/git/actions/runs/30894348053
Christian Couder (12):
  parse-options: introduce OPT_HIDDEN_GROUP
  api-parse-options.adoc: document per-option flags
  api-parse-options.adoc: document hidden and OPT_*_F option macros
  fast-import: localize 'i' into the 'for' loops using it
  fast-import: use int for some bool flags
  fast-import: factor out option_*() functions
  fast-import: introduce 'struct fast_import_state'
  fast-import: move command state globals into 'struct
    fast_import_state'
  fast-import: use struct option for usage string
  fast-import: use callbacks to parse some options
  fast-import: use parse_options() for command line options
  fast-import: remove useless from_stream argument
 Documentation/git-fast-import.adoc            |   2 +-
 .../technical/api-parse-options.adoc          |  79 +++
 builtin/fast-import.c                         | 577 ++++++++++++------
 parse-options.c                               |   4 +-
 parse-options.h                               |   5 +
 t/helper/test-parse-options.c                 |   4 +
 t/t0040-parse-options.sh                      |  25 +-
 t/t0450/adoc-help-mismatches                  |   1 -
 t/t9300-fast-import.sh                        |   7 +
 9 files changed, 517 insertions(+), 187 deletions(-)
Range-diff against v1:
 1:  ba4821276c !  1:  b09d727e71 parse-options: introduce OPT_HIDDEN_GROUP
    @@ Commit message
         To test this new macro, let's also improve `test-tool parse-options`
         and test its output with `--help-all`.
     
    -    Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
    +    Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
      ## parse-options.c ##
     @@ parse-options.c: static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t
    @@ t/t0040-parse-options.sh: Alias
     +
      test_expect_success 'test help' '
     +	cat expect-part1 expect-part2 >expect &&
    - 	test_must_fail test-tool parse-options -h >output 2>output.err &&
    + 	test-tool parse-options -h >output 2>output.err &&
      	test_must_be_empty output.err &&
      	test_cmp expect output
      '
      
     +test_expect_success 'test --help-all shows hidden group and options' '
     +	cat expect-part1 expect-noop expect-part2 expect-hidden >expect-help-all &&
    -+	test_must_fail test-tool parse-options --help-all >output 2>output.err &&
    ++	test-tool parse-options --help-all >output 2>output.err &&
     +	test_must_be_empty output.err &&
     +	test_cmp expect-help-all output
     +'
 2:  2690812694 !  2:  fe21471420 api-parse-options.adoc: document per-option flags
    @@ Commit message
         parse_options() flags described earlier, and let's describe the `-h`
         versus `--help-all` behavior for `PARSE_OPT_HIDDEN`.
     
    -    Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
    +    Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
      ## Documentation/technical/api-parse-options.adoc ##
     @@ Documentation/technical/api-parse-options.adoc: Data Structure
 3:  cf4b276019 !  3:  f43d4cefa4 api-parse-options.adoc: document hidden and OPT_*_F option macros
    @@ Commit message
     
           - Document `OPT_HIDDEN_BOOL()` right after `OPT_BOOL()`.
     
    -    Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
    +    Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
      ## Documentation/technical/api-parse-options.adoc ##
     @@ Documentation/technical/api-parse-options.adoc: Macros
 4:  9b051efd9f !  4:  3eb8106ed6 fast-import: localize 'i' into the 'for' loops using it
    @@ Commit message
         To give each loop counter the type matching its bound
         (int/unsigned/size_t), let's localize 'i' into each loop that uses it.
     
    -    Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
    +    Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
      ## builtin/fast-import.c ##
     @@ builtin/fast-import.c: int cmd_fast_import(int argc,
 -:  ---------- >  5:  34514eb2ac fast-import: use int for some bool flags
 -:  ---------- >  6:  336395c70a fast-import: factor out option_*() functions
 5:  2ca7ccafc6 !  7:  45cc2107e2 fast-import: introduce 'struct fast_import_state'
    @@ Commit message
         This is a mostly mechanical refactoring with no intended behavior
         change.
     
    -    Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
    +    Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
      ## builtin/fast-import.c ##
     @@ builtin/fast-import.c: static int failure;
      static FILE *pack_edges;
    - static unsigned int show_stats = 1;
    - static unsigned int quiet;
    + static int show_stats = 1;
    + static int quiet;
     -static int global_argc;
     -static const char **global_argv;
     -static const char *global_prefix;
    @@ builtin/fast-import.c: static void option_rewrite_submodules(const char *arg, st
      	fp = fopen(f, "r");
      	if (!fp)
      		die_errno(_("cannot read '%s'"), f);
    -@@ builtin/fast-import.c: static void option_rewrite_submodules(const char *arg, struct string_list *list)
    - 	free(s);
    +@@ builtin/fast-import.c: static void option_quiet(void)
    + 	quiet = 1;
      }
      
     -static int parse_one_option(const char *option)
     +static int parse_one_option(struct fast_import_state *state, const char *option)
      {
      	if (skip_prefix(option, "max-pack-size=", &option)) {
    - 		unsigned long v;
    + 		option_max_pack_size(option);
     @@ builtin/fast-import.c: static int parse_one_option(const char *option)
      	} else if (skip_prefix(option, "active-branches=", &option)) {
      		option_active_branches(option);
    @@ builtin/fast-import.c: static int parse_one_option(const char *option)
     -		option_export_pack_edges(option);
     +		option_export_pack_edges(state, option);
      	} else if (skip_prefix(option, "signed-commits=", &option)) {
    - 		if (parse_sign_mode(option, &signed_commit_mode, &signed_commit_keyid))
    - 			usagef(_("unknown --signed-commits mode '%s'"), option);
    + 		option_signed_commits(option);
    + 	} else if (skip_prefix(option, "signed-tags=", &option)) {
     @@ builtin/fast-import.c: static int parse_one_option(const char *option)
      	return 1;
      }
 6:  bf25bb3253 !  8:  7f068facc2 fast-import: move command state globals into 'struct fast_import_state'
    @@ Commit message
     
         This is a mechanical refactoring with no intended behavior change.
     
    -    Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
    +    Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
      ## builtin/fast-import.c ##
     @@ builtin/fast-import.c: static struct recent_command *rc_free;
 7:  9120d2b5c0 !  9:  3d6ab86518 fast-import: use struct option for usage string
    @@ Commit message
         This deliberately leaves it to future work to also use the
         parse-options API to actually parse the options.
     
    -    Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
    +    Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
      ## Documentation/git-fast-import.adoc ##
     @@ Documentation/git-fast-import.adoc: git-fast-import - Backend for fast Git data importers
    @@ builtin/fast-import.c: 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, depth, active_branches;
    -+	char *edges, *signed_commits, *signed_tags, *date_format, *import_marks;
    -+	char *import_marks_if_exists, *export_marks, *submodules_from, *submodules_to;
    -+	int opt_quiet, opt_show_stats, opt_relative_marks, opt_force, opt_done;
    -+	int opt_allow_unsafe;
    -+	int cat_blob;
    ++	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);
     +	/*
    @@ builtin/fast-import.c: int cmd_fast_import(int argc,
     +		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", &opt_show_stats,
    ++		OPT_BOOL_F(0, "stats", &show_stats,
     +			   N_("display some basic statistics (objects, packfiles and memory)"),
     +			   PARSE_OPT_NONEG),
    -+		OPT_BOOL_F(0, "quiet", &opt_quiet,
    ++		OPT_BOOL_F(0, "quiet", &quiet,
     +			   N_("disable the output shown by --stats"), PARSE_OPT_NONEG),
    -+		OPT_BOOL_F(0, "force", &opt_force,
    ++		OPT_BOOL_F(0, "force", &force_update,
     +			   N_("force updating modified existing branches"), PARSE_OPT_NONEG),
    -+		OPT_BOOL_F(0, "done", &opt_done,
    ++		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", &depth,
    ++		OPT_UNSIGNED(0, "depth", &max_depth,
     +			     N_("maximum delta depth")),
    -+		OPT_UNSIGNED(0, "active-branches", &active_branches,
    ++		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, N_("file"),
    ++		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, N_("file"),
    ++		OPT_STRING_F(0, "export-marks", &export_marks_file, N_("file"),
     +			     N_("dump marks to <file>"), PARSE_OPT_NONEG),
    -+		OPT_BOOL(0, "relative-marks", &opt_relative_marks,
    ++		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"),
    @@ builtin/fast-import.c: int cmd_fast_import(int argc,
     +			     N_("how to handle signed tags"),
     +			     PARSE_OPT_NONEG),
     +		OPT_HIDDEN_GROUP(N_("Advanced")),
    -+		OPT_BOOL_F(0, "allow-unsafe-features", &opt_allow_unsafe,
    ++		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,
    ++		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()
    @@ builtin/fast-import.c: int cmd_fast_import(int argc,
      	git_pack_config();
     
      ## t/t0450/adoc-help-mismatches ##
    -@@ t/t0450/adoc-help-mismatches: credential
    +@@ t/t0450/adoc-help-mismatches: column
    + credential
      credential-cache
      credential-store
    - fast-export
     -fast-import
      fetch-pack
      fmt-merge-msg
 -:  ---------- > 10:  3208937f13 fast-import: use callbacks to parse some options
 -:  ---------- > 11:  202a50beec fast-import: use parse_options() for command line options
 -:  ---------- > 12:  99ff791a62 fast-import: remove useless from_stream argument
-- 
2.55.0.492.g44bba30fd7.dirty
Previous: Christian CouderNext: Christian Couder
Message 15 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.