threads / patch / 66257

patch, 6 partsStandardize early option scanning to fix argument parsing bugs

Subject: [PATCH 0/6] Standardize early option scanning to fix argument parsing bugs

## tl;dr

The series adds an early-scan sub-API to parse-options so commands stop mis-handling option values and "--" in hand-rolled scans. Read the story.

replies: 40people: 4as markdown or json

Christian Couder· Sep 2, 2026, 16:10 UTC · lore

A number of commands perform an early scan of their arguments to look for specific flags or structural separators (like `--`).

These hand-rolled early scans are often fragile. They especially fail to account for options that take their value as a separate argument. This leads to disagreements between the early scan and the actual parse_options() pass. For example, the early scanner might miss a special option entirely, or mistakenly treat an option's value as the `--` path separator.

To allow these commands to safely skip option values during their early scans, this series introduces a new "early-scan" sub-API into the existing "parse-options" API.

This is deliberately implemented as a new simple and fast scan, which has some limitations, instead of a full refactor and reuse of the parse_options() code, because the limitations are not very significant in practice, while a full refactor and reuse of the parse_options() code would be much more complex.

The current limitations of the new early scan code are:
 1. short options are ignored,
 2. options with PARSE_OPT_LASTARG_DEFAULT or PARSE_OPT_OPTARG are
 treated as not taking a separate value,
 3. negated options ("--no-...") are not automatically generated,
 4. abbreviated options will not be matched.

Note that while the others could be real issues for some commands, "3. negated options" is not a practical issue because negated options never consume a separate argument.

The early scan is performed by a new early_scan_options() function which takes a `const struct early_scan_option *options` array as argument. That array can be built either by hand or by a new early_scan_options_from_options() function, which takes a `const struct option *options` array, when the command already uses `struct option`.

This allows us to use the new early-scan API even for commands that don't use the parse-options API yet, and which are the majority of commands performing an early scan.

In this series, only `git bisect`, `git rev-parse` and `git fast-import` are converted to the early-scan API, which fixes bugs in those commands:

 - `git bisect start --term-good -- <not-a-rev>` mistook the term name
   `--` for the revision/path separator, so <not-a-rev> was rejected
   as an invalid revision instead of being treated as a path.
 - `git rev-parse --default -- <not-a-rev>` did the same, reporting
   "bad revision <notarev>" while any other default value gives the
   usual more helpful "ambiguous argument" error.
 - `git fast-import --depth 5 --allow-unsafe-features` silently
   ignored `--allow-unsafe-features`, refusing unsafe features from
   the stream.

All of these commands call parse_options(), but for `git bisect` and `git rev-parse`, the specific functions doing the early scan (bisect_start() and cmd_rev_parse()'s main loop) parse their own options by hand after the early scan and have no `struct option` array for those options.

If bisect_start() and cmd_rev_parse() were converted to use `struct option`, they could use early_scan_options_from_options() and would not be affected by limitations 1), 2) and 3) above, as both use the early scan only to locate `--`.

Note that using early_scan_options_from_options() rather than a hand-written table does not change how abbreviations are handled: the scan matches long names exactly either way. Limitation 4) would nevertheless become relevant to those commands, because such a conversion would also make parse_options() the parser for the options after the early scan has first inspected them, and parse_options() resolves abbreviations while their current hand-rolled loops do not.

`git diff`, `git column`, `git rev-list` and setup_revisions() in "revision.c" could also be converted to the early-scan API but aren't in this series for different reasons:

 - `git diff` has a number of short options like `-S`, `-G`, `-O`
   taking separate values.
 - `git column` scans `argv[1]` for `--command=` before reading the
   configuration. Because `--command` is an OPT_STRING,
   parse_options() also accepts `--command <name>` and abbreviations,
   so the two passes disagree. Converting it would fix that, but it
   changes user-visible behaviour in a command this series does not
   otherwise touch.
 - `git rev-list` and "revision.c" are about converting
   setup_revisions(), but converting it to `struct option` first is
   likely the better way forward.

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

 - Patch 1/6 introduces early_scan_options(), the early scanner that
   will be used instead of hand-rolled ones, along with its
   infrastructure.
 - Patches 2/6 and 3/6 use this scanner to fix bugs in `git bisect`
   and `git rev-parse` respectively.
 - Patch 4/6 refactors some existing code into a new
   parse_options_takes_argument() helper that will be used in the next
   patch.
 - Patch 5/6 introduces the new early_scan_options_from_options() as a
   bridge between the parse-options API and the early-scan API.
 - Patch 6/6 uses early_scan_options_from_options() to fix the early
   scan for `--allow-unsafe-features` in `git fast-import`.

CI tests: =========

They all pass, see:
https://github.com/chriscool/git/actions/runs/33612974808
Christian Couder (6):
  parse-options: add early_scan_options()
  bisect: fix "--" detection when a term name is "--"
  rev-parse: fix "--" detection when it is an option value
  parse-options: add parse_options_takes_argument()
  parse-options: build early scan options from a struct option array
  fast-import: use early_scan_options() for --allow-unsafe-features
 Documentation/git-fast-import.adoc |  10 +-
 builtin/bisect.c                   |  27 ++++--
 builtin/fast-import.c              |  46 +++++----
 builtin/rev-parse.c                |  26 ++++--
 parse-options.c                    | 144 ++++++++++++++++++++++++++---
 parse-options.h                    |  92 ++++++++++++++++++
 t/helper/test-parse-options.c      |  71 ++++++++++++++
 t/helper/test-tool.c               |   2 +
 t/helper/test-tool.h               |   2 +
 t/t0040-parse-options.sh           | 103 +++++++++++++++++++++
 t/t1500-rev-parse.sh               |   5 +
 t/t6030-bisect-porcelain.sh        |   8 ++
 t/t9300-fast-import.sh             |  14 +++
 13 files changed, 503 insertions(+), 47 deletions(-)
-- 
2.55.0.787.g3f9e2241eb.dirty
Christian Couder· Sep 2, 2026, 16:10 UTC · re: Christian Couder · lore

[PATCH 1/6] parse-options: add early_scan_options()

Some commands need to look at a few of their options before they can parse their command line for real, for example because the result decides whether a repository is needed at all, or how the beginning of their input should be interpreted.

Such an early scan has to know which options take their value as a separate argument, or it mistakes such a value for an option. Several commands get this wrong, as they just walk their arguments comparing them to the few option names they care about.

Let's add early_scan_options() to help with this. Its callers describe the options to look for, but also the ones that merely have to be skipped along with their value, so that the scan can walk the arguments without being fooled by option values.

Note that abbreviated options are deliberately not recognized, as a scan cannot know about the options it hasn't been told about, and would then resolve abbreviations differently from the actual option parsing.

So users must spell these specific options in full. This restriction could be lifted in the future though, once the scanner is adapted to accept a command's full option array, as this would give it the complete context needed for safe abbreviation matching.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 parse-options.c               | 70 +++++++++++++++++++++++++++++++
 parse-options.h               | 60 +++++++++++++++++++++++++++
 t/helper/test-parse-options.c | 39 ++++++++++++++++++
 t/helper/test-tool.c          |  1 +
 t/helper/test-tool.h          |  1 +
 t/t0040-parse-options.sh      | 77 +++++++++++++++++++++++++++++++++++
 6 files changed, 248 insertions(+)
Show changes to 6 files +248 −0

parse-options.c, parse-options.h, t/helper/test-parse-options.c, t/helper/test-tool.c, t/helper/test-tool.h, t/t0040-parse-options.sh

diff --git a/parse-options.c b/parse-options.c
index 4519ead9dc..b3d19446cd 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -1244,6 +1244,76 @@ int parse_options(int argc, const char **argv,
 	return parse_options_end(&ctx);
 }
 
+/*
+ * Look for `arg` among `options`. On success, return the matching option
+ * and set `value` to the value stuck to it, if any, or to NULL.
+ */
+static const struct early_scan_option *
+find_early_scan_option(const char *arg,
+		       const struct early_scan_option *options,
+		       const char **value)
+{
+	if (!skip_prefix(arg, "--", &arg))
+		return NULL;
+
+	for (; options->name; options++) {
+		const char *rest;
+
+		if (!skip_prefix(arg, options->name, &rest))
+			continue;
+		if (!*rest) {
+			*value = NULL;
+			return options;
+		}
+		/* Only an option taking a value can be stuck to one. */
+		if (*rest == '=' && options->takes_value) {
+			*value = rest + 1;
+			return options;
+		}
+	}
+
+	return NULL;
+}
+
+int early_scan_options(int argc, const char **argv,
+		       const struct early_scan_option *options,
+		       enum early_scan_flags flags,
+		       early_scan_fn *fn, void *data)
+{
+	for (int i = 0; i < argc; i++) {
+		const char *arg = argv[i];
+		const char *value;
+		const struct early_scan_option *opt;
+		int pos = i;
+
+		if ((flags & EARLY_SCAN_STOP_AT_DASHDASH) &&
+		    !strcmp(arg, "--"))
+			return i;
+
+		opt = find_early_scan_option(arg, options, &value);
+		if (!opt) {
+			if ((flags & EARLY_SCAN_STOP_AT_NON_OPTION) &&
+			    (*arg != '-' || !arg[1]))
+				return i;
+			continue;
+		}
+
+		/*
+		 * When an option takes a value, but that value is not
+		 * stuck to it with '=', then the next argument is the
+		 * value and it has to be skipped so that it isn't
+		 * taken for an option itself.
+		 */
+		if (opt->takes_value && !value && i + 1 < argc)
+			value = argv[++i];
+
+		if (opt->wanted && fn(opt, value, pos, data))
+			return i;
+	}
+
+	return argc;
+}
+
 static int usage_argh(const struct option *opts, FILE *outfile)
 {
 	const char *s;
diff --git a/parse-options.h b/parse-options.h
index d7f896a933..abc73d8399 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -491,6 +491,66 @@ static inline void die_for_incompatible_opt2(int opt1, const char *opt1_name,
 		BUG("option callback expects an argument"); \
 } while(0)
 
+/*----- Early scan: scanning argv before the actual option parsing -----*/
+
+/*
+ * Some commands need to look at a few options before they can parse
+ * their command line for real, for example because the result decides
+ * whether a repository is needed at all.
+ *
+ * Such an early scan has to know which options take their value as a
+ * separate argument, or it could mistake such a value for an option. The
+ * `struct early_scan_option` array passed to early_scan_options() below
+ * describes the options to look for, as well as the ones that only need
+ * to be skipped along with their value.
+ */
+struct early_scan_option {
+	const char *name; 	/* Option name, without the leading dashes */
+	unsigned takes_value:1; /* "--option=value" or "--option value" expected? */
+	unsigned wanted:1;      /* Report option to callback? */
+};
+
+#define EARLY_SCAN_SKIP_VALUE(n) { .name = (n), .takes_value = 1 }
+#define EARLY_SCAN_WANT(n) { .name = (n), .wanted = 1 }
+#define EARLY_SCAN_WANT_VALUE(n) { .name = (n), .takes_value = 1, .wanted = 1 }
+#define EARLY_SCAN_END() { NULL }
+
+/*
+ * Called by early_scan_options() for each argument matching a
+ * `struct early_scan_option` that has its `wanted` bit set.
+ *
+ * `option` is the matching option, `value` its value or NULL if it
+ * doesn't take one, and `pos` the index of the option in argv.
+ *
+ * Returning a non-zero value stops the scan.
+ */
+typedef int early_scan_fn(const struct early_scan_option *option,
+			  const char *value, int pos, void *data);
+
+enum early_scan_flags {
+	EARLY_SCAN_STOP_AT_DASHDASH = 1 << 0, /* Stop at "--" */
+	EARLY_SCAN_STOP_AT_NON_OPTION = 1 << 1,
+};
+
+/*
+ * Scan `argv` for the options described by `options`, calling `fn`
+ * for each of those that are `wanted`. `argv` is not modified.
+ *
+ * `fn` may be NULL when no option is `wanted`, which is useful to only
+ * find out where the scan stops.
+ *
+ * Note that abbreviated options are not recognized, as a scan cannot
+ * know about the options it hasn't been told about, and would then
+ * resolve abbreviations differently from the actual option parsing.
+ *
+ * Returns the index at which the scan stopped, which is `argc` when the
+ * whole array was scanned.
+ */
+int early_scan_options(int argc, const char **argv,
+		       const struct early_scan_option *options,
+		       enum early_scan_flags flags,
+		       early_scan_fn *fn, void *data);
+
 /*----- incremental advanced APIs -----*/
 
 struct parse_opt_cmdmode_list;
diff --git a/t/helper/test-parse-options.c b/t/helper/test-parse-options.c
index f181f0c02d..96ab941d29 100644
--- a/t/helper/test-parse-options.c
+++ b/t/helper/test-parse-options.c
@@ -383,3 +383,42 @@ int cmd__parse_subcommand(int argc, const char **argv)
 
 	return parse_subcommand__cmd(argc, argv, test_flags);
 }
+
+static int show_early_option(const struct early_scan_option *opt,
+			     const char *value, int pos, void *data UNUSED)
+{
+	printf("found: %s at %d", opt->name, pos);
+	if (value)
+		printf(" value: %s", value);
+	putchar('\n');
+	return 0;
+}
+
+int cmd__early_scan_options(int argc, const char **argv)
+{
+	static const struct early_scan_option options[] = {
+		EARLY_SCAN_WANT("wanted"),
+		EARLY_SCAN_WANT_VALUE("wanted-value"),
+		EARLY_SCAN_SKIP_VALUE("skipped-value"),
+		EARLY_SCAN_END()
+	};
+	enum early_scan_flags flags = 0;
+	int stopped;
+
+	while (argc > 1 && *argv[1] == '-') {
+		if (!strcmp(argv[1], "--stop-at-dashdash"))
+			flags |= EARLY_SCAN_STOP_AT_DASHDASH;
+		else if (!strcmp(argv[1], "--stop-at-non-option"))
+			flags |= EARLY_SCAN_STOP_AT_NON_OPTION;
+		else
+			break;
+		argc--;
+		argv++;
+	}
+
+	stopped = early_scan_options(argc - 1, argv + 1, options, flags,
+				    show_early_option, NULL);
+	printf("stopped at: %d of %d\n", stopped, argc - 1);
+
+	return 0;
+}
diff --git a/t/helper/test-tool.c b/t/helper/test-tool.c
index b71a22b43b..5d2f5877d9 100644
--- a/t/helper/test-tool.c
+++ b/t/helper/test-tool.c
@@ -50,6 +50,7 @@ static struct test_cmd cmds[] = {
 	{ "pack-mtimes", cmd__pack_mtimes },
 	{ "parse-options", cmd__parse_options },
 	{ "parse-options-flags", cmd__parse_options_flags },
+	{ "early-scan-options", cmd__early_scan_options },
 	{ "parse-pathspec-file", cmd__parse_pathspec_file },
 	{ "parse-subcommand", cmd__parse_subcommand },
 	{ "partial-clone", cmd__partial_clone },
diff --git a/t/helper/test-tool.h b/t/helper/test-tool.h
index f2885b33d5..071306d52d 100644
--- a/t/helper/test-tool.h
+++ b/t/helper/test-tool.h
@@ -43,6 +43,7 @@ int cmd__pack_deltas(int argc, const char **argv);
 int cmd__pack_mtimes(int argc, const char **argv);
 int cmd__parse_options(int argc, const char **argv);
 int cmd__parse_options_flags(int argc, const char **argv);
+int cmd__early_scan_options(int argc, const char **argv);
 int cmd__parse_pathspec_file(int argc, const char** argv);
 int cmd__parse_subcommand(int argc, const char **argv);
 int cmd__partial_clone(int argc, const char **argv);
diff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh
index 449fff4d34..d760d8cfbd 100755
--- a/t/t0040-parse-options.sh
+++ b/t/t0040-parse-options.sh
@@ -845,4 +845,81 @@ test_expect_success 'u16 limits range' '
 	test_grep "value 65536 for option .u16. not in range \[0,65535\]" err
 '
 
+test_expect_success 'early_scan_options() finds a wanted option' '
+	test-tool early-scan-options --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() reads a stuck or separate value' '
+	test-tool early-scan-options --wanted-value=one >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: one
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --wanted-value two >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: two
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() skips the value of other options' '
+	test-tool early-scan-options --skipped-value --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --skipped-value one --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() can stop at "--"' '
+	test-tool early-scan-options --stop-at-dashdash -- --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-dashdash \
+		--skipped-value -- --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() can stop at a non-option' '
+	test-tool early-scan-options --stop-at-non-option \
+		arg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-non-option \
+		--skipped-value arg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() ignores abbreviated options' '
+	test-tool early-scan-options --want >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
 test_done
-- 
2.55.0.787.g3f9e2241eb.dirty
Junio C Hamano· Sep 2, 2026, 22:11 UTC · re: Christian Couder · lore

Re: [PATCH 1/6] parse-options: add early_scan_options()

Christian Couder <christian.couder@gmail.com> writes:
> So users must spell these specific options in full. This restriction
> could be lifted in the future though, once the scanner is adapted to
> accept a command's full option array, as this would give it the
> complete context needed for safe abbreviation matching.

It is unfortunate that end-users cannot tell if they are dealing with a system before of after "once the scanner is adapted" happened, so they must be trained to always spell the options in full to make use of the commands that use this feature. It at least does not regress relative to the ad-hoc early scanners these selected commands have that do not even understand what they are parsing, so it may not be too bad.

Stepping back a bit, the burden on programmers to use this would be to write in a separate notation what options there are in addition to what they feed the real parse_options(), which cuts both ways in the sense that because this does not take parse_options(), commands that do not use parse_options() can still use it, but those that do already use parse_options() need additional work to use eary_scan.

And then once the scanner is adapted to accept the full option array, the programmers only need to discard the struct early_scan_option[] they wrote and replace it with the struct option[] they already have? Or would the calling convention to the scanner also change when it happens (oother than replacing the pointer to struct early_scan_option[] with another pointer to struct option[])?

> +static const struct early_scan_option *
> +find_early_scan_option(const char *arg,
> +		       const struct early_scan_option *options,
> +		       const char **value)

Because you return one single element from the incoming array of options, it is mildly misleading to call the variable/parameter "options" here and everywhere else. Let's stick to "arrays are named singular, so that option[4] names 4th option" convention.

Show 9 quoted lines
> +{
> +	if (!skip_prefix(arg, "--", &arg))
> +		return NULL;
> +
> +	for (; options->name; options++) {
> +		const char *rest;
> +
> +		if (!skip_prefix(arg, options->name, &rest))
> +			continue;

"--option" on the command line, after getting stripped the leading "--", may begin with "option", and that name may be in the option[] table, in which case ...

> +		if (!*rest) {
> +			*value = NULL;
> +			return options;
> +		}

... we found a hit. But shouldn't option->takes_value be consulted before we return to signal the caller that the next arg is an option value before we return from here? It looks a bit uneven as we do that for stuck form "--option=value" here.

Show 5 quoted lines
> +		/* Only an option taking a value can be stuck to one. */
> +		if (*rest == '=' && options->takes_value) {
> +			*value = rest + 1;
> +			return options;
> +		}

And if the option[] table had "opt", then "--option" on the command line may begin with "--opt" but "ion" is an excess that is not a stuck value, so we do not consider it as a match. OK.

> +	}
> +	return NULL;
> +}

If we are to write a separate function anyway, I wonder how much more work to write a early_scan_option() parser that does take a real "struct option[]" array. Its elements already know if they take a value or not. For expediency, it may be OK to start by simplified parser that does not handle unique prefix and other complexities like callback functions of the real parser, but at least it would reduce the burden on the programmers quite a bit if we used the real struct option[] array, I suspect.

Christian Couder· Sep 23, 2026, 08:10 UTC · re: Junio C Hamano · lore

Re: [PATCH 1/6] parse-options: add early_scan_options()

On Thu, Sep 3, 2026 at 12:11 AM Junio C Hamano <gitster@pobox.com> wrote:
Show 29 quoted lines
>
> Christian Couder <christian.couder@gmail.com> writes:
>
> > So users must spell these specific options in full. This restriction
> > could be lifted in the future though, once the scanner is adapted to
> > accept a command's full option array, as this would give it the
> > complete context needed for safe abbreviation matching.
>
> It is unfortunate that end-users cannot tell if they are dealing
> with a system before of after "once the scanner is adapted"
> happened, so they must be trained to always spell the options in
> full to make use of the commands that use this feature.  It at least
> does not regress relative to the ad-hoc early scanners these selected
> commands have that do not even understand what they are parsing, so
> it may not be too bad.
>
> Stepping back a bit, the burden on programmers to use this would be
> to write in a separate notation what options there are in addition
> to what they feed the real parse_options(), which cuts both ways in
> the sense that because this does not take parse_options(), commands
> that do not use parse_options() can still use it, but those that do
> already use parse_options() need additional work to use eary_scan.
>
> And then once the scanner is adapted to accept the full option array,
> the programmers only need to discard the struct early_scan_option[]
> they wrote and replace it with the struct option[] they already have?
> Or would the calling convention to the scanner also change when it
> happens (oother than replacing the pointer to struct early_scan_option[]
> with another pointer to struct option[])?

I agree that what was implemented in v1 (to be able to accommodate early scans that do not use parse_options()) didn't bring much practical value, was a bit complex and required some churn when the early scan would have been converted to use parse_options(). So, in the v2 I just sent, it addresses only the early scan where parse_options() is used, which simplifies a lot of things.

Show 9 quoted lines
> > +static const struct early_scan_option *
> > +find_early_scan_option(const char *arg,
> > +                    const struct early_scan_option *options,
> > +                    const char **value)
>
> Because you return one single element from the incoming array of
> options, it is mildly misleading to call the variable/parameter
> "options" here and everywhere else.  Let's stick to "arrays are
> named singular, so that option[4] names 4th option" convention.
Right, I have changed the argument to `const struct option *option`.
Show 23 quoted lines
> > +{
> > +     if (!skip_prefix(arg, "--", &arg))
> > +             return NULL;
> > +
> > +     for (; options->name; options++) {
> > +             const char *rest;
> > +
> > +             if (!skip_prefix(arg, options->name, &rest))
> > +                     continue;
>
> "--option" on the command line, after getting stripped the leading
> "--", may begin with "option", and that name may be in the option[]
> table, in which case ...
>
> > +             if (!*rest) {
> > +                     *value = NULL;
> > +                     return options;
> > +             }
>
> ... we found a hit.  But shouldn't option->takes_value be consulted
> before we return to signal the caller that the next arg is an option
> value before we return from here?  It looks a bit uneven as we do
> that for stuck form "--option=value" here.

Yeah, we found that `arg` exactly matches this option whether or not it takes a value, but the value is not here.

Whether the next argument has to be skipped is decided by the caller:
  if (parse_options_takes_argument(opt) && !value && i + 1 < argc)
      value = argv[++i];

find_early_scan_option() cannot do that itself, as it has neither argv, argc nor the current index.

So signalling to the caller would be redundant, because the caller already holds the matched option and can ask directly.

But maybe I should add a comment on the line before `if (!*rest) {` saying that skipping a separate value is the caller's job?

Show 9 quoted lines
> > +             /* Only an option taking a value can be stuck to one. */
> > +             if (*rest == '=' && options->takes_value) {
> > +                     *value = rest + 1;
> > +                     return options;
> > +             }
>
> And if the option[] table had "opt", then "--option" on the command
> line may begin with "--opt" but "ion" is an excess that is not a
> stuck value, so we do not consider it as a match.  OK.

Now using `takes_value` in the `*rest == '='` case wasn't quite right, as parse_options_takes_argument() returns 0 for PARSE_OPT_OPTARG and PARSE_OPT_LASTARG_DEFAULT, but parse_options() does accept a stuck value for both.

So in v2 we use the same condition parse_options() uses:
  /* Only an option that can take a value may have one stuck to it. */
  if (*rest == '=' && !(opt->flags & PARSE_OPT_NOARG)) {
      *value = rest + 1;
      return opt;
  }
Show 12 quoted lines
> > +     }
> > +     return NULL;
> > +}
>
> If we are to write a separate function anyway, I wonder how much
> more work to write a early_scan_option() parser that does take a
> real "struct option[]" array.  Its elements already know if they
> take a value or not.  For expediency, it may be OK to start by
> simplified parser that does not handle unique prefix and other
> complexities like callback functions of the real parser, but at
> least it would reduce the burden on the programmers quite a bit if
> we used the real struct option[] array, I suspect.
This is what v2 does, and I agree that it simplifies things.
Junio C Hamano· Sep 23, 2026, 17:25 UTC · re: Christian Couder · lore

Re: [PATCH 1/6] parse-options: add early_scan_options()

Christian Couder <christian.couder@gmail.com> writes:
Show 13 quoted lines
> Whether the next argument has to be skipped is decided by the caller:
>
>   if (parse_options_takes_argument(opt) && !value && i + 1 < argc)
>       value = argv[++i];
>
> find_early_scan_option() cannot do that itself, as it has neither
> argv, argc nor the current index.
>
> So signalling to the caller would be redundant, because the caller
> already holds the matched option and can ask directly.
>
> But maybe I should add a comment on the line before `if (!*rest) {`
> saying that skipping a separate value is the caller's job?

Not really. I was hinting if it is cleaner to have the callee do the skipping so that caller does not have to worry about it. After all, the job of the early-scan machinery is to scan the options reliably to find something later in the command line argument array. The less the caller needs to do, the easier the machinery is to use.

Show 16 quoted lines
>> > +             /* Only an option taking a value can be stuck to one. */
>> > +             if (*rest == '=' && options->takes_value) {
>> > +                     *value = rest + 1;
>> > +                     return options;
>> > +             }
>>
>> And if the option[] table had "opt", then "--option" on the command
>> line may begin with "--opt" but "ion" is an excess that is not a
>> stuck value, so we do not consider it as a match.  OK.
>
> Now using `takes_value` in the `*rest == '='` case wasn't quite right,
> as parse_options_takes_argument() returns 0 for PARSE_OPT_OPTARG and
> PARSE_OPT_LASTARG_DEFAULT, but parse_options() does accept a stuck
> value for both.
>
> So in v2 we use the same condition parse_options() uses:
My giving an opaque hint pays off sometimes ;-)
Thanks.
Christian Couder· Sep 2, 2026, 16:10 UTC · re: Christian Couder · lore

[PATCH 2/6] bisect: fix "--" detection when a term name is "--"

`bisect_start()` walks its arguments twice. The second loop actually parses the options, and it knows that `--term-good`, `--term-old`, `--term-bad` and `--term-new` take their value as a separate argument, so it skips that value.

The first loop, which only looks for the "--" separating revisions from paths, doesn't know about these options. So when such an option is given "--" as its value, that "--" is mistaken for the separator and `has_double_dash` is wrongly set.

This matters because `has_double_dash` makes the second loop die on an argument that is not a valid revision, instead of treating it as the first path. So:

  $ git bisect start --term-good -- notarev
  fatal: 'notarev' does not appear to be a valid revision

while the very same command line with any other term name happily takes "notarev" as a path.

Let's fix this by using early_scan_options(), telling it about the options taking their value as a separate argument, so that it can skip those values.

Note: One might argue that accepting a term name that looks like an
option (such as "--") is a misfeature and should be forbidden entirely.
However, whether we should tighten the validation rules for bisect
terms is a separate UI issue that can be dealt with independently. For
now, this commit simply ensures the parser correctly implements the
existing rules.
Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 builtin/bisect.c            | 27 +++++++++++++++++++++------
 t/t6030-bisect-porcelain.sh |  8 ++++++++
 2 files changed, 29 insertions(+), 6 deletions(-)
Show changes to 2 files +29 −6

builtin/bisect.c, t/t6030-bisect-porcelain.sh

diff --git a/builtin/bisect.c b/builtin/bisect.c
index 1cfb8a794b..ad089b289f 100644
--- a/builtin/bisect.c
+++ b/builtin/bisect.c
@@ -803,6 +803,19 @@ static enum bisect_error bisect_auto_next(struct bisect_terms *terms,
 	return bisect_next(terms, prefix);
 }
 
+/*
+ * The options "git bisect start" accepts. Only the ones taking their
+ * value as a separate argument matter to the scan looking for "--" below,
+ * as their value has to be skipped along with them.
+ */
+static const struct early_scan_option bisect_start_early_options[] = {
+	EARLY_SCAN_SKIP_VALUE("term-good"),
+	EARLY_SCAN_SKIP_VALUE("term-old"),
+	EARLY_SCAN_SKIP_VALUE("term-bad"),
+	EARLY_SCAN_SKIP_VALUE("term-new"),
+	EARLY_SCAN_END()
+};
+
 static enum bisect_error bisect_start(struct bisect_terms *terms, int argc,
 				      const char **argv)
 {
@@ -825,13 +838,15 @@ static enum bisect_error bisect_start(struct bisect_terms *terms, int argc,
 
 	/*
 	 * Check for one bad and then some good revisions
+	 *
+	 * The scan below has to know about the options taking their value
+	 * as a separate argument, or such a value that happens to be "--"
+	 * would be mistaken for the "--" separating revisions from paths.
 	 */
-	for (i = 0; i < argc; i++) {
-		if (!strcmp(argv[i], "--")) {
-			has_double_dash = 1;
-			break;
-		}
-	}
+	i = early_scan_options(argc, argv, bisect_start_early_options,
+			       EARLY_SCAN_STOP_AT_DASHDASH, NULL, NULL);
+	if (i < argc)
+		has_double_dash = 1;
 
 	for (i = 0; i < argc; i++) {
 		const char *arg = argv[i];
diff --git a/t/t6030-bisect-porcelain.sh b/t/t6030-bisect-porcelain.sh
index a7588222a8..464ca53b42 100755
--- a/t/t6030-bisect-porcelain.sh
+++ b/t/t6030-bisect-porcelain.sh
@@ -1297,6 +1297,14 @@ test_expect_success 'bisect start takes options and revs in any order' '
 	test_cmp expected actual
 '
 
+test_expect_success 'bisect start with "--" as a term name' '
+	git bisect reset &&
+	git bisect start --term-good -- hello &&
+	git bisect terms --term-good >actual &&
+	echo -- >expected &&
+	test_cmp expected actual
+'
+
 # Bisect is started with --term-new and --term-old arguments,
 # then skip. The HEAD should be changed.
 test_expect_success 'bisect skip works with --term*' '
-- 
2.55.0.787.g3f9e2241eb.dirty
Junio C Hamano· Sep 2, 2026, 22:30 UTC · re: Christian Couder · lore

Re: [PATCH 2/6] bisect: fix "--" detection when a term name is "--"

Christian Couder <christian.couder@gmail.com> writes:
Show 9 quoted lines
> `bisect_start()` walks its arguments twice. The second loop actually
> parses the options, and it knows that `--term-good`, `--term-old`,
> `--term-bad` and `--term-new` take their value as a separate argument,
> so it skips that value.
>
> The first loop, which only looks for the "--" separating revisions from
> paths, doesn't know about these options. So when such an option is given
> "--" as its value, that "--" is mistaken for the separator and
> `has_double_dash` is wrongly set.

It may be theoretically true, but I wonder how much practical value it has to correctly parse "--term-good --" as "Ah, the user wants to mark good revisions as '--' instead of 'good' or 'old'"? Even though "refs/bisect/--" is *not* forbidden, how likely is it for users to do that?

This is not like "git grep -e --" which does have much more pracical value.

Show 69 quoted lines
>  builtin/bisect.c            | 27 +++++++++++++++++++++------
>  t/t6030-bisect-porcelain.sh |  8 ++++++++
>  2 files changed, 29 insertions(+), 6 deletions(-)
>
> diff --git a/builtin/bisect.c b/builtin/bisect.c
> index 1cfb8a794b..ad089b289f 100644
> --- a/builtin/bisect.c
> +++ b/builtin/bisect.c
> @@ -803,6 +803,19 @@ static enum bisect_error bisect_auto_next(struct bisect_terms *terms,
>  	return bisect_next(terms, prefix);
>  }
>  
> +/*
> + * The options "git bisect start" accepts. Only the ones taking their
> + * value as a separate argument matter to the scan looking for "--" below,
> + * as their value has to be skipped along with them.
> + */
> +static const struct early_scan_option bisect_start_early_options[] = {
> +	EARLY_SCAN_SKIP_VALUE("term-good"),
> +	EARLY_SCAN_SKIP_VALUE("term-old"),
> +	EARLY_SCAN_SKIP_VALUE("term-bad"),
> +	EARLY_SCAN_SKIP_VALUE("term-new"),
> +	EARLY_SCAN_END()
> +};
> +
>  static enum bisect_error bisect_start(struct bisect_terms *terms, int argc,
>  				      const char **argv)
>  {
> @@ -825,13 +838,15 @@ static enum bisect_error bisect_start(struct bisect_terms *terms, int argc,
>  
>  	/*
>  	 * Check for one bad and then some good revisions
> +	 *
> +	 * The scan below has to know about the options taking their value
> +	 * as a separate argument, or such a value that happens to be "--"
> +	 * would be mistaken for the "--" separating revisions from paths.
>  	 */
> -	for (i = 0; i < argc; i++) {
> -		if (!strcmp(argv[i], "--")) {
> -			has_double_dash = 1;
> -			break;
> -		}
> -	}
> +	i = early_scan_options(argc, argv, bisect_start_early_options,
> +			       EARLY_SCAN_STOP_AT_DASHDASH, NULL, NULL);
> +	if (i < argc)
> +		has_double_dash = 1;
>  
>  	for (i = 0; i < argc; i++) {
>  		const char *arg = argv[i];
> diff --git a/t/t6030-bisect-porcelain.sh b/t/t6030-bisect-porcelain.sh
> index a7588222a8..464ca53b42 100755
> --- a/t/t6030-bisect-porcelain.sh
> +++ b/t/t6030-bisect-porcelain.sh
> @@ -1297,6 +1297,14 @@ test_expect_success 'bisect start takes options and revs in any order' '
>  	test_cmp expected actual
>  '
>  
> +test_expect_success 'bisect start with "--" as a term name' '
> +	git bisect reset &&
> +	git bisect start --term-good -- hello &&
> +	git bisect terms --term-good >actual &&
> +	echo -- >expected &&
> +	test_cmp expected actual
> +'
> +
>  # Bisect is started with --term-new and --term-old arguments,
>  # then skip. The HEAD should be changed.
>  test_expect_success 'bisect skip works with --term*' '
Christian Couder· Sep 23, 2026, 08:11 UTC · re: Junio C Hamano · lore

Re: [PATCH 2/6] bisect: fix "--" detection when a term name is "--"

On Thu, Sep 3, 2026 at 12:30 AM Junio C Hamano <gitster@pobox.com> wrote:
Show 21 quoted lines
>
> Christian Couder <christian.couder@gmail.com> writes:
>
> > `bisect_start()` walks its arguments twice. The second loop actually
> > parses the options, and it knows that `--term-good`, `--term-old`,
> > `--term-bad` and `--term-new` take their value as a separate argument,
> > so it skips that value.
> >
> > The first loop, which only looks for the "--" separating revisions from
> > paths, doesn't know about these options. So when such an option is given
> > "--" as its value, that "--" is mistaken for the separator and
> > `has_double_dash` is wrongly set.
>
> It may be theoretically true, but I wonder how much practical value
> it has to correctly parse "--term-good --" as "Ah, the user wants to
> mark good revisions as '--' instead of 'good' or 'old'"?  Even
> though "refs/bisect/--" is *not* forbidden, how likely is it for
> users to do that?
>
> This is not like "git grep -e --" which does have much more pracical
> value.
Right, this patch and the next one have been removed from v2.

In the future we can still convert bisect_start() to the parse-options API, and then use the early-scan API to look for "--" in a bit cleaner way.

Junio C Hamano· Sep 23, 2026, 17:27 UTC · re: Christian Couder · lore

Re: [PATCH 2/6] bisect: fix "--" detection when a term name is "--"

Christian Couder <christian.couder@gmail.com> writes:
> In the future we can still convert bisect_start() to the parse-options
> API, and then use the early-scan API to look for "--" in a bit cleaner
> way.

Yeah, when that happens, I can imagine that we can make detection of "--" to come for free as a side effect of using parse_options().

Thanks.
Christian Couder· Sep 2, 2026, 16:10 UTC · re: Christian Couder · lore

[PATCH 3/6] rev-parse: fix "--" detection when it is an option value

`cmd_rev_parse()` walks its arguments twice. The second loop actually parses the options, and it knows that `--default`, `--prefix` and `--resolve-git-dir` take their value as a separate argument, so it skips that value.

The first loop, which only looks for the "--" separating revisions from paths, doesn't know about these options. So when such an option is given "--" as its value, that "--" is mistaken for the separator and `has_dashdash` is wrongly set.

This matters because `has_dashdash` makes the second loop die with a "bad revision" error on an argument that is neither a revision nor an existing file, instead of reporting that the argument is ambiguous and telling how to disambiguate it. So:

  $ git rev-parse --default -- notarev
  fatal: bad revision 'notarev'

while the very same command line with any other default value gives the usual, much more helpful, "ambiguous argument" error.

Let's fix this the same way as in a previous commit, by using early_scan_options() and telling it about the options taking their value as a separate argument.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 builtin/rev-parse.c  | 26 ++++++++++++++++++++------
 t/t1500-rev-parse.sh |  5 +++++
 2 files changed, 25 insertions(+), 6 deletions(-)
Show changes to 2 files +25 −6

builtin/rev-parse.c, t/t1500-rev-parse.sh

diff --git a/builtin/rev-parse.c b/builtin/rev-parse.c
index 43693454d5..7ced82e25d 100644
--- a/builtin/rev-parse.c
+++ b/builtin/rev-parse.c
@@ -695,6 +695,17 @@ static void print_path(const char *path, const char *prefix,
 	strbuf_release(&sb);
 }
 
+/*
+ * The options taking their value as a separate argument, which the scan
+ * looking for "--" below has to skip along with their value.
+ */
+static const struct early_scan_option rev_parse_early_options[] = {
+	EARLY_SCAN_SKIP_VALUE("default"),
+	EARLY_SCAN_SKIP_VALUE("prefix"),
+	EARLY_SCAN_SKIP_VALUE("resolve-git-dir"),
+	EARLY_SCAN_END()
+};
+
 int cmd_rev_parse(int argc,
 		  const char **argv,
 		  const char *prefix,
@@ -724,12 +735,15 @@ int cmd_rev_parse(int argc,
 	if (argc > 1 && !strcmp("-h", argv[1]))
 		usage(builtin_rev_parse_usage);
 
-	for (i = 1; i < argc; i++) {
-		if (!strcmp(argv[i], "--")) {
-			has_dashdash = 1;
-			break;
-		}
-	}
+	/*
+	 * The scan below has to know about the options taking their value
+	 * as a separate argument, or such a value that happens to be "--"
+	 * would be mistaken for the "--" separating revisions from paths.
+	 */
+	i = early_scan_options(argc - 1, argv + 1, rev_parse_early_options,
+			       EARLY_SCAN_STOP_AT_DASHDASH, NULL, NULL);
+	if (i < argc - 1)
+		has_dashdash = 1;
 
 	/* No options; just report on whether we're in a git repo or not. */
 	if (argc == 1) {
diff --git a/t/t1500-rev-parse.sh b/t/t1500-rev-parse.sh
index 4174ca40c3..897e9a7735 100755
--- a/t/t1500-rev-parse.sh
+++ b/t/t1500-rev-parse.sh
@@ -383,4 +383,9 @@ test_expect_success ':/ and HEAD^{/} favor more recent matching commits' '
 	)
 '
 
+test_expect_success 'rev-parse with "--" as an option value' '
+	test_must_fail git rev-parse --default -- notarev 2>err &&
+	test_grep "ambiguous argument .notarev." err
+'
+
 test_done
-- 
2.55.0.787.g3f9e2241eb.dirty
Christian Couder· Sep 2, 2026, 16:10 UTC · re: Christian Couder · lore

[PATCH 4/6] parse-options: add parse_options_takes_argument()

Whether an option takes a value, and therefore consumes the next argument when that value is not stuck to it with an '=', is decided by its type and its flags. That rule is currently open-coded in show_gitcomp(), which needs it to decide if it should append an '=' to the option it completes.

A following commit will need the same rule to find out which options an early scan of the command line has to skip along with their value.

So let's factor that rule out into a new parse_options_takes_argument() function, and let's use it in show_gitcomp().

Note that an option with PARSE_OPT_LASTARG_DEFAULT only consumes the next argument when it isn't the last one, so it is not considered as taking a value, which is what show_gitcomp() already did.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 parse-options.c | 35 ++++++++++++++++++++++-------------
 parse-options.h | 10 ++++++++++
 2 files changed, 32 insertions(+), 13 deletions(-)
Show changes to 2 files +32 −13

parse-options.c, parse-options.h

diff --git a/parse-options.c b/parse-options.c
index b3d19446cd..70851a385b 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -841,6 +841,26 @@ static void show_negated_gitcomp(const struct option *opts, int show_all,
 	}
 }
 
+int parse_options_takes_argument(const struct option *opt)
+{
+	switch (opt->type) {
+	case OPTION_STRING:
+	case OPTION_FILENAME:
+	case OPTION_INTEGER:
+	case OPTION_UNSIGNED:
+	case OPTION_CALLBACK:
+		break;
+	default:
+		return 0;
+	}
+
+	if (opt->flags & (PARSE_OPT_NOARG | PARSE_OPT_OPTARG |
+			  PARSE_OPT_LASTARG_DEFAULT))
+		return 0;
+
+	return 1;
+}
+
 static int show_gitcomp(const struct option *opts, int show_all)
 {
 	const struct option *original_opts = opts;
@@ -862,20 +882,9 @@ static int show_gitcomp(const struct option *opts, int show_all)
 			break;
 		case OPTION_GROUP:
 			continue;
-		case OPTION_STRING:
-		case OPTION_FILENAME:
-		case OPTION_INTEGER:
-		case OPTION_UNSIGNED:
-		case OPTION_CALLBACK:
-			if (opts->flags & PARSE_OPT_NOARG)
-				break;
-			if (opts->flags & PARSE_OPT_OPTARG)
-				break;
-			if (opts->flags & PARSE_OPT_LASTARG_DEFAULT)
-				break;
-			suffix = "=";
-			break;
 		default:
+			if (parse_options_takes_argument(opts))
+				suffix = "=";
 			break;
 		}
 		if (opts->flags & PARSE_OPT_COMP_ARG)
diff --git a/parse-options.h b/parse-options.h
index abc73d8399..b96e93508e 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -420,6 +420,16 @@ int parse_options(int argc, const char **argv, const char *prefix,
 		  const char * const usagestr[],
 		  enum parse_opt_flags flags);
 
+/*
+ * Return non-zero if `opt` takes a value, which means that it consumes
+ * the next argument when that value is not stuck to it with an '='.
+ *
+ * Note that an option with PARSE_OPT_LASTARG_DEFAULT only consumes the
+ * next argument when it isn't the last one, so it is not considered as
+ * taking a value here.
+ */
+int parse_options_takes_argument(const struct option *opt);
+
 NORETURN void usage_with_options(const char * const *usagestr,
 				 const struct option *options);
 
-- 
2.55.0.787.g3f9e2241eb.dirty
Christian Couder· Sep 2, 2026, 16:10 UTC · re: Christian Couder · lore

[PATCH 5/6] parse-options: build early scan options from a struct option array

A command that scans its arguments early has to know which options take a value, so that it can skip that value instead of mistaking it for an option. When it also parses its options with the parse-options API, that information is already available in its `struct option` array, and duplicating it by hand in a `struct early_scan_option` array is both tedious and easy to get out of sync when an option is added.

So let's add early_scan_options_from_options() to build the latter array from the former, using parse_options_takes_argument() to find out which options take a value. Its caller only has to name the options it wants to be reported.

Note: This early scanner translation intentionally leaves out a few
complex option types to keep the scan simple and fast:
- Short options are ignored: early_scan_options_from_options()
  explicitly skips options without a `long_name`, and the scanner only
  looks for `--`. Properly handling short options would require parsing
  bundled flags (e.g., `-abc value`), which requires replicating the
  full parse_options() state machine.
- Conditional values: Options with `PARSE_OPT_LASTARG_DEFAULT` or
  `PARSE_OPT_OPTARG` are treated as not taking a separate argument.
  Because the scanner does not evaluate context (like whether an
  argument is the final one in `argv`), it must err on the side of
  caution to avoid accidentally consuming the `--` separator or a path.
- Abbreviated options remain unrecognized: Even though the scanner is
  now provided with the full option array, the underlying
  early_scan_options() engine still relies on exact string matches.
  Safely resolving abbreviations would require duplicating the
  ambiguity-checking logic from the main parser.
- Negated options are not automatically derived: The scanner strictly
  matches the defined long name. It does not automatically recognize
  the `--no-<name>` variants of boolean options. (This is harmless in
  practice for current callers, as negated options do not take values
  to skip, and boolean defaults align with the ignored state).

The above shortcomings can be addressed later, for example, when commands that use short options or options with conditional values need an early scan or are ported to use `struct option`.

Despite these limitations, this abstraction is a significant improvement. It allows commands like `fast-import` to reuse their existing `struct option` array for early scanning, ensuring the scanner and the main parser agree on which options take arguments, and preventing developers from having to maintain a separate, hardcoded list that could drift out of sync.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 parse-options.c               | 39 +++++++++++++++++++++++++++++++++++
 parse-options.h               | 22 ++++++++++++++++++++
 t/helper/test-parse-options.c | 32 ++++++++++++++++++++++++++++
 t/helper/test-tool.c          |  1 +
 t/helper/test-tool.h          |  1 +
 t/t0040-parse-options.sh      | 26 +++++++++++++++++++++++
 6 files changed, 121 insertions(+)
Show changes to 6 files +121 −0

parse-options.c, parse-options.h, t/helper/test-parse-options.c, t/helper/test-tool.c, t/helper/test-tool.h, t/t0040-parse-options.sh

diff --git a/parse-options.c b/parse-options.c
index 70851a385b..6cdc9c64cc 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -1323,6 +1323,45 @@ int early_scan_options(int argc, const char **argv,
 	return argc;
 }
 
+struct early_scan_option *
+early_scan_options_from_options(const struct option *options,
+				const char **wanted)
+{
+	struct early_scan_option *early;
+	size_t nr = 0;
+
+	for (const struct option *opt = options; opt->type != OPTION_END; opt++)
+		if (opt->long_name)
+			nr++;
+
+	CALLOC_ARRAY(early, nr + 1);
+
+	nr = 0;
+	for (const struct option *opt = options; opt->type != OPTION_END; opt++) {
+		if (!opt->long_name)
+			continue;
+		early[nr].name = opt->long_name;
+		early[nr].takes_value = !!parse_options_takes_argument(opt);
+		nr++;
+	}
+
+	for (; wanted && *wanted; wanted++) {
+		size_t i;
+
+		for (i = 0; i < nr; i++) {
+			if (strcmp(early[i].name, *wanted))
+				continue;
+			early[i].wanted = 1;
+			break;
+		}
+		if (i == nr)
+			BUG("wanted option '%s' is not in the options array",
+			    *wanted);
+	}
+
+	return early;
+}
+
 static int usage_argh(const struct option *opts, FILE *outfile)
 {
 	const char *s;
diff --git a/parse-options.h b/parse-options.h
index b96e93508e..fb81f2ed38 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -561,6 +561,28 @@ int early_scan_options(int argc, const char **argv,
 		       enum early_scan_flags flags,
 		       early_scan_fn *fn, void *data);
 
+/*
+ * Build the `struct early_scan_option` array to pass to
+ * early_scan_options() from the `options` array that the actual option
+ * parsing uses, so that both agree on which options take a value.
+ *
+ * Note some intentional limitations to keep the scan simple and fast:
+ * short options are ignored, options with PARSE_OPT_LASTARG_DEFAULT or
+ * PARSE_OPT_OPTARG are treated as not taking a separate value, negated
+ * options ("--no-...") are not automatically generated, and abbreviated
+ * options will not be matched.
+ *
+ * The options named in the NULL terminated `wanted` array get their
+ * `wanted` bit set, the other ones are only there to be skipped along
+ * with their value. It is a BUG() for a name in `wanted` not to appear
+ * in `options`.
+ *
+ * The returned array is allocated and should be free()d by the caller.
+ */
+struct early_scan_option *
+early_scan_options_from_options(const struct option *options,
+				const char **wanted);
+
 /*----- incremental advanced APIs -----*/
 
 struct parse_opt_cmdmode_list;
diff --git a/t/helper/test-parse-options.c b/t/helper/test-parse-options.c
index 96ab941d29..0187a25ccb 100644
--- a/t/helper/test-parse-options.c
+++ b/t/helper/test-parse-options.c
@@ -422,3 +422,35 @@ int cmd__early_scan_options(int argc, const char **argv)
 
 	return 0;
 }
+
+int cmd__early_scan_from_options(int argc, const char **argv)
+{
+	int an_int = 0, a_bool = 0;
+	char *a_string = NULL;
+	const struct option options[] = {
+		OPT_STRING(0, "string", &a_string, "str", "get a string"),
+		OPT_INTEGER(0, "int", &an_int, "get an integer"),
+		OPT_BOOL(0, "bool", &a_bool, "get a boolean"),
+		OPT_STRING_F(0, "optarg", &a_string, "str",
+			     "string with an optional value",
+			     PARSE_OPT_OPTARG),
+		OPT_END()
+	};
+	static const char *wanted[] = { "bool", NULL };
+	struct early_scan_option *early;
+	int stopped;
+
+	early = early_scan_options_from_options(options, wanted);
+
+	for (const struct early_scan_option *o = early; o->name; o++)
+		printf("option: %s takes_value: %d wanted: %d\n",
+		       o->name, o->takes_value, o->wanted);
+
+	stopped = early_scan_options(argc - 1, argv + 1, early, 0,
+				     show_early_option, NULL);
+	printf("stopped at: %d of %d\n", stopped, argc - 1);
+
+	free(early);
+
+	return 0;
+}
diff --git a/t/helper/test-tool.c b/t/helper/test-tool.c
index 5d2f5877d9..f1b208a5af 100644
--- a/t/helper/test-tool.c
+++ b/t/helper/test-tool.c
@@ -51,6 +51,7 @@ static struct test_cmd cmds[] = {
 	{ "parse-options", cmd__parse_options },
 	{ "parse-options-flags", cmd__parse_options_flags },
 	{ "early-scan-options", cmd__early_scan_options },
+	{ "early-scan-from-options", cmd__early_scan_from_options },
 	{ "parse-pathspec-file", cmd__parse_pathspec_file },
 	{ "parse-subcommand", cmd__parse_subcommand },
 	{ "partial-clone", cmd__partial_clone },
diff --git a/t/helper/test-tool.h b/t/helper/test-tool.h
index 071306d52d..97334ce3c6 100644
--- a/t/helper/test-tool.h
+++ b/t/helper/test-tool.h
@@ -44,6 +44,7 @@ int cmd__pack_mtimes(int argc, const char **argv);
 int cmd__parse_options(int argc, const char **argv);
 int cmd__parse_options_flags(int argc, const char **argv);
 int cmd__early_scan_options(int argc, const char **argv);
+int cmd__early_scan_from_options(int argc, const char **argv);
 int cmd__parse_pathspec_file(int argc, const char** argv);
 int cmd__parse_subcommand(int argc, const char **argv);
 int cmd__partial_clone(int argc, const char **argv);
diff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh
index d760d8cfbd..bb72a6544d 100755
--- a/t/t0040-parse-options.sh
+++ b/t/t0040-parse-options.sh
@@ -922,4 +922,30 @@ test_expect_success 'early_scan_options() ignores abbreviated options' '
 	test_cmp expect actual
 '
 
+test_expect_success 'early_scan_options_from_options() derives takes_value' '
+	test-tool early-scan-from-options >actual &&
+	cat >expect <<-\EOF &&
+	option: string takes_value: 1 wanted: 0
+	option: int takes_value: 1 wanted: 0
+	option: bool takes_value: 0 wanted: 1
+	option: optarg takes_value: 0 wanted: 0
+	stopped at: 0 of 0
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options_from_options() skips values' '
+	test-tool early-scan-from-options --string --bool >out &&
+	tail -1 out >actual &&
+	echo "stopped at: 2 of 2" >expect &&
+	test_cmp expect actual &&
+	test-tool early-scan-from-options --string v --bool >out &&
+	tail -2 out >actual &&
+	cat >expect <<-\EOF &&
+	found: bool at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
 test_done
-- 
2.55.0.787.g3f9e2241eb.dirty
Christian Couder· Sep 2, 2026, 16:10 UTC · re: Christian Couder · lore

[PATCH 6/6] fast-import: use early_scan_options() for --allow-unsafe-features

The "feature" lines at the start of the stream are processed before the command line options are parsed, so cmd_fast_import() scans its arguments early to find out if `--allow-unsafe-features` was given.

That scan doesn't know which options take their value as a separate argument, and it stops at the first argument that doesn't start with a dash. So it disagrees with parse_options(), which accepts values separated from their option by a space, for a command line like "--depth 5 --allow-unsafe-features": the scan stops at "5" and never sees the option, so unsafe "feature" commands from the stream are refused even though the option was given.

Let's fix this by building the options for the scan from the same `struct option` array that parse_options() uses, so that both agree on which options take a value.

Note that the scan still only matches the exact option spelling, while parse_options() also accepts unambiguous abbreviations, so the two still disagree for a command line like "--allow-unsafe". This errs on the safe side, and is now documented as a restriction.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 Documentation/git-fast-import.adoc | 10 +++----
 builtin/fast-import.c              | 46 +++++++++++++++++++-----------
 t/t9300-fast-import.sh             | 14 +++++++++
 3 files changed, 48 insertions(+), 22 deletions(-)
Show changes to 3 files +48 −22

Documentation/git-fast-import.adoc, builtin/fast-import.c, t/t9300-fast-import.sh

diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc
index fd165e11d2..9758ba5275 100644
--- a/Documentation/git-fast-import.adoc
+++ b/Documentation/git-fast-import.adoc
@@ -66,12 +66,10 @@ fast-import stream! This option is enabled automatically for
 remote-helpers that use the `import` capability, as they are
 already trusted to run their own code.
 +
-Note that this option has to be spelled in full, and has to appear
-before any option whose value is separated from it by a space, for
-the unsafe `feature` commands in the stream to be allowed. So
-`--allow-unsafe` or `--depth 5 --allow-unsafe-features` still refuse
-them, while `--allow-unsafe-features --depth 5` and
-`--depth=5 --allow-unsafe-features` allow them.
+Note that this option has to be spelled in full for the unsafe
+`feature` commands in the stream to be allowed. So while
+`--allow-unsafe` is accepted as an unambiguous abbreviation of this
+option, it still refuses them.
 
 `--signed-tags=<mode>`::
 	Specify how to handle signed tags. Behaves in the same way as
diff --git a/builtin/fast-import.c b/builtin/fast-import.c
index fbd919982c..cf0504f01c 100644
--- a/builtin/fast-import.c
+++ b/builtin/fast-import.c
@@ -4120,12 +4120,29 @@ static int option_parse_quiet(const struct option *opt UNUSED,
 	return 0;
 }
 
+/*
+ * The only option the early scan below is interested in, as it decides
+ * whether unsafe "feature" commands from the stream are allowed.
+ */
+static const char *early_wanted[] = { "allow-unsafe-features", NULL };
+
+static int option_parse_early_allow_unsafe(
+		const struct early_scan_option *opt UNUSED,
+		const char *value UNUSED, int pos UNUSED, void *data)
+{
+	struct fast_import_state *state = data;
+
+	state->allow_unsafe_features = 1;
+	return 0;
+}
+
 int cmd_fast_import(int argc,
 		    const char **argv,
 		    const char *prefix,
 		    struct repository *repo)
 {
 	struct fast_import_state state;
+	struct early_scan_option *early;
 
 	struct option fast_import_options[] = {
 		OPT_GROUP(N_("Common")),
@@ -4218,23 +4235,20 @@ int cmd_fast_import(int argc,
 	 * line to override stream data). But we must do an early parse of any
 	 * command-line options that impact how we interpret the feature lines.
 	 *
-	 * NEEDSWORK: This scan only matches the exact "--allow-unsafe-features"
-	 * spelling and stops at the first argument that doesn't start with a
-	 * dash. As parse_options() below also accepts unambiguous abbreviations
-	 * and values separated by a space from their option, the two disagree
-	 * for command lines like "--allow-unsafe" or "--depth 5
-	 * --allow-unsafe-features": parse_options() accepts the option, but
-	 * this scan doesn't see it, so unsafe features from the stream are
-	 * still refused. This errs on the safe side, but should be fixed by
-	 * teaching this scan about the options that take a value.
+	 * NEEDSWORK: This scan only matches the exact
+	 * "--allow-unsafe-features" spelling, while parse_options() below
+	 * also accepts unambiguous abbreviations, so the two disagree for
+	 * a command line like "--allow-unsafe": parse_options() accepts
+	 * the option, but this scan doesn't see it, so unsafe features
+	 * from the stream are still refused. This errs on the safe side.
 	 */
-	for (int i = 1; i < argc; i++) {
-		const char *arg = argv[i];
-		if (*arg != '-' || !strcmp(arg, "--"))
-			break;
-		if (!strcmp(arg, "--allow-unsafe-features"))
-			state.allow_unsafe_features = 1;
-	}
+	early = early_scan_options_from_options(fast_import_options,
+						early_wanted);
+	early_scan_options(argc - 1, argv + 1, early,
+			   EARLY_SCAN_STOP_AT_DASHDASH |
+			   EARLY_SCAN_STOP_AT_NON_OPTION,
+			   option_parse_early_allow_unsafe, &state);
+	free(early);
 
 	rc_free = mem_pool_alloc(&fi_mem_pool, cmd_save * sizeof(*rc_free));
 	for (unsigned int i = 0; i < (cmd_save - 1); i++)
diff --git a/t/t9300-fast-import.sh b/t/t9300-fast-import.sh
index d9de2ef0d8..1a37f2b8e6 100755
--- a/t/t9300-fast-import.sh
+++ b/t/t9300-fast-import.sh
@@ -2344,6 +2344,20 @@ test_expect_success 'R: export-marks options can be overridden by commandline op
 	test_path_is_missing feature-sub
 '
 
+test_expect_success 'R: --allow-unsafe-features found after a value' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	git fast-import --allow-unsafe-features <input &&
+	git fast-import --depth=5 --allow-unsafe-features <input &&
+	git fast-import --depth 5 --allow-unsafe-features <input &&
+	git fast-import --date-format raw --allow-unsafe-features <input
+'
+
+test_expect_success 'R: --allow-unsafe-features has to be spelled in full' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	test_must_fail git fast-import --allow-unsafe <input 2>err &&
+	test_grep "forbidden in input without --allow-unsafe-features" err
+'
+
 test_expect_success 'R: catch typo in marks file name' '
 	test_must_fail git fast-import --import-marks=nonexistent.marks </dev/null &&
 	echo "feature import-marks=nonexistent.marks" |
-- 
2.55.0.787.g3f9e2241eb.dirty
Junio C Hamano· Sep 4, 2026, 03:38 UTC · re: Christian Couder · lore

Re: [PATCH 6/6] fast-import: use early_scan_options() for --allow-unsafe-features

Christian Couder <christian.couder@gmail.com> writes:
Show 11 quoted lines
> The "feature" lines at the start of the stream are processed before the
> command line options are parsed, so cmd_fast_import() scans its
> arguments early to find out if `--allow-unsafe-features` was given.
>
> That scan doesn't know which options take their value as a separate
> argument, and it stops at the first argument that doesn't start with a
> dash. So it disagrees with parse_options(), which accepts values
> separated from their option by a space, for a command line like
> "--depth 5 --allow-unsafe-features": the scan stops at "5" and never
> sees the option, so unsafe "feature" commands from the stream are
> refused even though the option was given.
Well explained.
Show 18 quoted lines
> @@ -4218,23 +4235,20 @@ int cmd_fast_import(int argc,
>  	 * line to override stream data). But we must do an early parse of any
>  	 * command-line options that impact how we interpret the feature lines.
>  	 *
> +	 * NEEDSWORK: This scan only matches the exact
> +	 * "--allow-unsafe-features" spelling, while parse_options() below
> +	 * also accepts unambiguous abbreviations, so the two disagree for
> +	 * a command line like "--allow-unsafe": parse_options() accepts
> +	 * the option, but this scan doesn't see it, so unsafe features
> +	 * from the stream are still refused. This errs on the safe side.
>  	 */
> -	for (int i = 1; i < argc; i++) {
> -		const char *arg = argv[i];
> -		if (*arg != '-' || !strcmp(arg, "--"))
> -			break;
> -		if (!strcmp(arg, "--allow-unsafe-features"))
> -			state.allow_unsafe_features = 1;
> -	}

This is the ad-hoc one that does not know --depth takes a value after it.

Show 7 quoted lines
> +	early = early_scan_options_from_options(fast_import_options,
> +						early_wanted);
> +	early_scan_options(argc - 1, argv + 1, early,
> +			   EARLY_SCAN_STOP_AT_DASHDASH |
> +			   EARLY_SCAN_STOP_AT_NON_OPTION,
> +			   option_parse_early_allow_unsafe, &state);
> +	free(early);

Interesting. This one now "knows" enough to skip what comes after "--depth" that takes an option ;-) And it is perfectly fine if we skip over "--depth hello" to find "--allow-unsafe", as such a "oops we require number but hello is not a number" will be caught by the real parser anyway.

Nicely done.
Junio C Hamano· Sep 2, 2026, 18:52 UTC · re: Christian Couder · lore

Re: [PATCH 0/6] Standardize early option scanning to fix argument parsing bugs

Christian Couder <christian.couder@gmail.com> writes:
Show 13 quoted lines
> A number of commands perform an early scan of their arguments to look
> for specific flags or structural separators (like `--`).
>
> These hand-rolled early scans are often fragile. They especially fail
> to account for options that take their value as a separate
> argument. This leads to disagreements between the early scan and the
> actual parse_options() pass. For example, the early scanner might miss
> a special option entirely, or mistakenly treat an option's value as
> the `--` path separator.
>
> To allow these commands to safely skip option values during their
> early scans, this series introduces a new "early-scan" sub-API into
> the existing "parse-options" API.
Yay.
> This is deliberately implemented as a new simple and fast scan, which
> has some limitations, instead of a full refactor and reuse of the
> parse_options() code,

Sigh. In other words, we hate these ad-hoc prescan that are buggy badly enough to replace them all with yet another ad-hoc prescan that is know to behave differently from the real thing?

>  - `git bisect start --term-good -- <not-a-rev>` mistook the term name
>    `--` for the revision/path separator, so <not-a-rev> was rejected
>    as an invalid revision instead of being treated as a path.
Sorry, I fail to see much practical value in this.
>  - `git rev-parse --default -- <not-a-rev>` did the same, reporting
>    "bad revision <notarev>" while any other default value gives the
>    usual more helpful "ambiguous argument" error.
Neither in this one.
>  - `git fast-import --depth 5 --allow-unsafe-features` silently
>    ignored `--allow-unsafe-features`, refusing unsafe features from
>    the stream.
On the other hand, this may be a very good thing.

Is the reason why the ad-hoc pre-scan failed to see it was because it did not realize 5 is a value to the --depth option?

Show 10 quoted lines
> All of these commands call parse_options(), but for `git bisect` and
> `git rev-parse`, the specific functions doing the early scan
> (bisect_start() and cmd_rev_parse()'s main loop) parse their own
> options by hand after the early scan and have no `struct option` array
> for those options.
>
> If bisect_start() and cmd_rev_parse() were converted to use
> `struct option`, they could use early_scan_options_from_options() and
> would not be affected by limitations 1), 2) and 3) above, as both use
> the early scan only to locate `--`.

I imagine that in the long term we would rather see a properly refactored parse-options machinery perform the prescan (perhaps with some kind of "dry-run" option given to the machinery) than yet another ad-hoc parser like this topic introduces. It would be very good if this interim solution at least took the same 'options[]' array so that when we have the real thing in the future we do not have to redo the conversion effort.

By the way, how does this interact with your other topic that has been stalled for quite some time? Would moving this one forward help the other, or do they not have much relevance to each other? I would rather not see two topics of non-trivial size stalled on a single author at the same time, so ...

Thanks.
Christian Couder· Sep 23, 2026, 08:10 UTC · re: Junio C Hamano · lore

Re: [PATCH 0/6] Standardize early option scanning to fix argument parsing bugs

On Wed, Sep 2, 2026 at 8:52 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Christian Couder <christian.couder@gmail.com> writes:
Show 13 quoted lines
> > To allow these commands to safely skip option values during their
> > early scans, this series introduces a new "early-scan" sub-API into
> > the existing "parse-options" API.
>
> Yay.
>
> > This is deliberately implemented as a new simple and fast scan, which
> > has some limitations, instead of a full refactor and reuse of the
> > parse_options() code,
>
> Sigh.  In other words, we hate these ad-hoc prescan that are buggy
> badly enough to replace them all with yet another ad-hoc prescan
> that is know to behave differently from the real thing?

Yes, because the limitations of the new scan are not very significant in practice while refactoring the real thing (so that it can perform an early scan without side effects) would be much more complex.

Show 11 quoted lines
> >  - `git bisect start --term-good -- <not-a-rev>` mistook the term name
> >    `--` for the revision/path separator, so <not-a-rev> was rejected
> >    as an invalid revision instead of being treated as a path.
>
> Sorry, I fail to see much practical value in this.
>
> >  - `git rev-parse --default -- <not-a-rev>` did the same, reporting
> >    "bad revision <notarev>" while any other default value gives the
> >    usual more helpful "ambiguous argument" error.
>
> Neither in this one.
I have removed those from the series in the v2 I just sent.
Show 8 quoted lines
> >  - `git fast-import --depth 5 --allow-unsafe-features` silently
> >    ignored `--allow-unsafe-features`, refusing unsafe features from
> >    the stream.
>
> On the other hand, this may be a very good thing.
>
> Is the reason why the ad-hoc pre-scan failed to see it was because
> it did not realize 5 is a value to the --depth option?
Yes.
Show 18 quoted lines
> > All of these commands call parse_options(), but for `git bisect` and
> > `git rev-parse`, the specific functions doing the early scan
> > (bisect_start() and cmd_rev_parse()'s main loop) parse their own
> > options by hand after the early scan and have no `struct option` array
> > for those options.
> >
> > If bisect_start() and cmd_rev_parse() were converted to use
> > `struct option`, they could use early_scan_options_from_options() and
> > would not be affected by limitations 1), 2) and 3) above, as both use
> > the early scan only to locate `--`.
>
> I imagine that in the long term we would rather see a properly
> refactored parse-options machinery perform the prescan (perhaps with
> some kind of "dry-run" option given to the machinery) than yet
> another ad-hoc parser like this topic introduces.  It would be very
> good if this interim solution at least took the same 'options[]'
> array so that when we have the real thing in the future we do not
> have to redo the conversion effort.

This is what is implemented in the v2 I just sent. So yeah, when a refactored parse-options machinery will be able to perform the prescan, we will be able to use it to replace the early-scan parser without changing or converting the callers.

Show 5 quoted lines
> By the way, how does this interact with your other topic that has
> been stalled for quite some time?  Would moving this one forward
> help the other, or do they not have much relevance to each other?  I
> would rather not see two topics of non-trivial size stalled on a
> single author at the same time, so ...

They are separate topics and I alternate between them. I was recently busy with travelling to the Git Merge and was a bit sick before that, but hopefully I should be able to spend more time on them in the next weeks. Also it seems to me that both topics have advanced to a point where not a lot of big changes are needed. So they should move forward quite fast now.

Christian Couder· Sep 23, 2026, 08:09 UTC · re: Christian Couder · lore

[PATCH v2 0/3] Standardize early option scanning

A number of commands perform an early scan of their arguments to look for specific flags or structural separators (like `--`).

These hand-rolled early scans are often fragile. They especially fail to account for options that take their value as a separate argument. This leads to disagreements between the early scan and the actual parse_options() pass. For example, the early scanner might miss a special option entirely, or mistakenly treat an option's value as the `--` path separator.

To allow these commands to safely skip option values during their early scans, this series introduces a new "early-scan" sub-API into the existing "parse-options" API.

This is deliberately implemented as a new simple and fast scan, which has some limitations, instead of a full refactor and reuse of the parse_options() code, because the limitations are not very significant in practice, while a full refactor and reuse of the parse_options() code would be much more complex.

The current limitations of the new early scan code are:
 1. short options are ignored,
 2. an option with PARSE_OPT_OPTARG or PARSE_OPT_LASTARG_DEFAULT never
 has the following argument skipped as its value. This matches
 parse_options() for PARSE_OPT_OPTARG, but not for
 PARSE_OPT_LASTARG_DEFAULT, which consumes that argument when the
 option isn't the last one,
 3. negated options ("--no-...") are not matched,
 4. abbreviated options will not be matched,
 5. subcommands (OPTION_SUBCOMMAND) are never matched, so an option
 marked with PARSE_OPT_EARLY cannot be a subcommand,
 6. aliases (OPTION_ALIAS) are not resolved to the option they stand
 for, so the separate value of an alias of an option taking a value
 is not skipped.

Note that while the others could be real issues for some commands, "3. negated options" and "5. subcommands" are not practical issues because negated options never consume a separate argument, and parse_options() doesn't match subcommands as "--<name>" either.

The early scan is performed by a new early_scan_options() function which takes a regular `const struct option *options` array as argument.

This requires that the command already uses `struct option` and the parse-options API to parse its arguments. As the majority of commands performing an early scan don't use the parse-options API yet, they will have to be converted to use it before they can use early_scan_options().

In this series, only `git fast-import` is converted to the early-scan API, which fixes a bug as:

  `git fast-import --depth 5 --allow-unsafe-features`

silently ignored `--allow-unsafe-features`, refusing unsafe features from the stream.

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

 - Patch 1/3 refactors some existing code into a new
   parse_options_takes_argument() helper that will be used in the next
   patch.
 - Patch 2/3 introduces early_scan_options(), the early scanner that
   will be used instead of hand-rolled ones, along with its
   infrastructure.
 - Patch 3/3 uses early_scan_options() to fix the early scan for
   `--allow-unsafe-features` in `git fast-import`.

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

Thanks to Junio who reviewed v1.
There are a lot of important changes since v1:
 - Now the early-scan API requires the parse-options API to be already
   used, and early_scan_options() accepts a regular `struct option *`
   instead of a dedicated `struct early_scan_option *`.
   (In v1, early_scan_options() took a dedicated
   `struct early_scan_option *` array, which the caller either wrote by
   hand, when it didn't use the parse-options API, or derived from its
   `struct option *` array with early_scan_options_from_options().)
   This simplifies things significantly, but requires that code doing
   an early scan be ported to the parse-options API if it doesn't use
   it yet.
 - bisect_start() and cmd_rev_parse() are not converted anymore to the
   new early-scan API. Converting them didn't bring much value, and
   they can still be converted in the future after they are converted
   to the parse-options API.
 - Options that should be looked up during the early scan are now
   marked with a new PARSE_OPT_EARLY flag (which is documented with
   the other per-option flags in
   "Documentation/technical/api-parse-options.adoc") in
   `struct option`.
   (In v1, a `wanted` flag in `struct early_scan_option` was used for
   this, and this flag could be set by passing a `const char **wanted`
   to early_scan_options_from_options().)
 - parse_options_check() now rejects PARSE_OPT_EARLY on an option
   without a long name, and on a subcommand, as the scan can never
   match either of them.
   (In v1, early_scan_options_from_options() raised a BUG() when a
   name in `wanted` was not in the option array.)
 - The EARLY_SCAN_STOP_AT_DASHDASH flag has been removed, and the scan
   now always stops at both `--` and `--end-of-options`, as
   parse_options() always stops parsing options at them whatever its
   flags. (PARSE_OPT_KEEP_DASHDASH and PARSE_OPT_KEEP_UNKNOWN_OPT only
   decide if the terminator is left in argv, not if it terminates.)
   (In v1, the scan walked past `--end-of-options`, so
   `git fast-import --end-of-options --allow-unsafe-features` allowed
   unsafe stream features before parse_options() rejected the command
   line.)
 - "--<name>=<value>" is now matched for any option that is not
   PARSE_OPT_NOARG, instead of only for options taking a separate
   value. Whether the next argument is consumed still depends on
   parse_options_takes_argument().
   (In v1, an option with PARSE_OPT_OPTARG or
   PARSE_OPT_LASTARG_DEFAULT was missed entirely in that form, while
   parse_options() accepts it.)
 - The different patches changed in the following way:
   - Patch 4/6 is now patch 1/3.
   - Patches 1/6 and 5/6 have been squashed and heavily modified to
     create patch 2/3.
   - Patches 2/6 and 3/6 have been removed as bisect_start() and
     cmd_rev_parse() are not converted anymore to the new early-scan
     API.
   - Patch 6/6 is now patch 3/3.

CI tests: =========

They all pass, see:
https://github.com/chriscool/git/actions/runs/35749173266

Range-diff since v1 ===================

4:  1ea80545c4 = 1:  32adff46ce parse-options: add parse_options_takes_argument()
1:  acb475f98d ! 2:  82569fa602 parse-options: add early_scan_options()
    @@ Commit message
         commands get this wrong, as they just walk their arguments comparing
         them to the few option names they care about.
     
    -    Let's add early_scan_options() to help with this. Its callers describe
    -    the options to look for, but also the ones that merely have to be
    -    skipped along with their value, so that the scan can walk the arguments
    -    without being fooled by option values.
    +    Let's add early_scan_options() to help with this. It walks the
    +    arguments using the very same `struct option` array that the command
    +    already passes to parse_options(), and uses the
    +    parse_options_takes_argument() helper added in a previous commit, so
    +    that the scan and the actual parsing agree on which options take a
    +    value.
     
    -    Note that abbreviated options are deliberately not recognized, as a
    -    scan cannot know about the options it hasn't been told about, and would
    -    then resolve abbreviations differently from the actual option parsing.
    +    The options the caller wants to be told about are marked with a new
    +    PARSE_OPT_EARLY flag, so that nothing has to be spelled out a second
    +    time, and so that the mark cannot drift away from the option it refers
    +    to.
     
    -    So users must spell these specific options in full. This restriction
    -    could be lifted in the future though, once the scanner is adapted to
    -    accept a command's full option array, as this would give it the
    -    complete context needed for safe abbreviation matching.
    +    Using a per-option flag for this is not new as that flag space already
    +    holds flags that the parsing loop itself ignores, like
    +    PARSE_OPT_NOCOMPLETE and PARSE_OPT_COMP_ARG, which only the completion
    +    helper looks at, or PARSE_OPT_HIDDEN and PARSE_OPT_LITERAL_ARGHELP,
    +    which only the usage output looks at.
    +
    +    The scan is deliberately kept much simpler than parse_options(),
    +    instead of teaching the latter to perform a side effect free "dry
    +    run". Such a dry run would have to avoid writing through `opt->value`,
    +    calling option callbacks, dying on an invalid value, handling `--help`
    +    and tracking command mode conflicts, so it would be a much larger
    +    refactoring. If parse_options() learns to do it in the future though,
    +    the commands converted now would keep both their option array and their
    +    PARSE_OPT_EARLY marks, so their conversion would not have to be redone.
    +
    +    One consequence of staying simple is that abbreviated options are
    +    still not matched, even though the scan is now given the command's
    +    full option array. Resolving them the way parse_options() does would
    +    mean duplicating the ambiguity detection that parse_long_opt()
    +    performs. So the scan can fail to see an option that parse_options()
    +    would accept, and its callers have to cope with that, typically by
    +    erring on the safe side. This and the other differences with
    +    parse_options() are documented in "parse-options.h".
    +
    +    In practice, despite these limitations, early scans using
    +    early_scan_options() should still be safer and cleaner than the
    +    ad-hoc hand-rolled scans they are meant to replace, which don't know
    +    about option values at all and therefore disagree with
    +    parse_options() in ways that create plain bugs.
     
         Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
    + ## Documentation/technical/api-parse-options.adoc ##
    +@@ Documentation/technical/api-parse-options.adoc: are the bitwise-or of:
    + 	Internal flag, set on options that were expanded from a
    + 	configured alias. It should not be set by callers.
    + 
    ++`PARSE_OPT_EARLY`::
    ++	Report this option to `early_scan_options()`, which looks at a
    ++	few options before parsing the command line for real. Ignored
    ++	by `parse_options()` itself.
    ++
    + `PARSE_OPT_NOCOMPLETE`::
    + 	Do not offer this option for completion.
    + 
    +
      ## parse-options.c ##
    +@@ parse-options.c: static void parse_options_check(const struct option *opts)
    + 		     opts->long_name))
    + 			optbug(opts, "uses feature "
    + 			       "not supported for dashless options");
    ++		if ((opts->flags & PARSE_OPT_EARLY) && !opts->long_name)
    ++			optbug(opts, "uses PARSE_OPT_EARLY, which needs a long name");
    + 		if (opts->type == OPTION_SET_INT && !opts->defval &&
    + 		    opts->long_name && !(opts->flags & PARSE_OPT_NONEG))
    + 			optbug(opts, "OPTION_SET_INT 0 should not be negatable");
    +@@ parse-options.c: static void parse_options_check(const struct option *opts)
    + 		case OPTION_SUBCOMMAND:
    + 			if (!opts->value || !opts->subcommand_fn)
    + 				optbug(opts, "OPTION_SUBCOMMAND needs a value and a subcommand function");
    ++			if (opts->flags & PARSE_OPT_EARLY)
    ++				optbug(opts, "OPTION_SUBCOMMAND does not support PARSE_OPT_EARLY");
    + 			if (!subcommand_value)
    + 				subcommand_value = opts->value;
    + 			else if (subcommand_value != opts->value)
     @@ parse-options.c: int parse_options(int argc, const char **argv,
      	return parse_options_end(&ctx);
      }
      
     +/*
    -+ * Look for `arg` among `options`. On success, return the matching option
    ++ * Look for `arg` among `option`. On success, return the matching option
     + * and set `value` to the value stuck to it, if any, or to NULL.
     + */
    -+static const struct early_scan_option *
    -+find_early_scan_option(const char *arg,
    -+		       const struct early_scan_option *options,
    -+		       const char **value)
    ++static const struct option *find_early_scan_option(const char *arg,
    ++						   const struct option *option,
    ++						   const char **value)
     +{
     +	if (!skip_prefix(arg, "--", &arg))
     +		return NULL;
     +
    -+	for (; options->name; options++) {
    ++	for (const struct option *opt = option; opt->type != OPTION_END; opt++) {
     +		const char *rest;
     +
    -+		if (!skip_prefix(arg, options->name, &rest))
    ++		if (opt->type == OPTION_SUBCOMMAND)
    ++			continue;
    ++		if (!opt->long_name)
    ++			continue;
    ++		if (!skip_prefix(arg, opt->long_name, &rest))
     +			continue;
    ++
     +		if (!*rest) {
     +			*value = NULL;
    -+			return options;
    ++			return opt;
     +		}
    -+		/* Only an option taking a value can be stuck to one. */
    -+		if (*rest == '=' && options->takes_value) {
    ++		/* Only an option that can take a value may have one stuck to it. */
    ++		if (*rest == '=' && !(opt->flags & PARSE_OPT_NOARG)) {
     +			*value = rest + 1;
    -+			return options;
    ++			return opt;
     +		}
     +	}
     +
    @@ parse-options.c: int parse_options(int argc, const char **argv,
     +}
     +
     +int early_scan_options(int argc, const char **argv,
    -+		       const struct early_scan_option *options,
    ++		       const struct option *option,
     +		       enum early_scan_flags flags,
     +		       early_scan_fn *fn, void *data)
     +{
     +	for (int i = 0; i < argc; i++) {
     +		const char *arg = argv[i];
     +		const char *value;
    -+		const struct early_scan_option *opt;
    ++		const struct option *opt;
     +		int pos = i;
     +
    -+		if ((flags & EARLY_SCAN_STOP_AT_DASHDASH) &&
    -+		    !strcmp(arg, "--"))
    ++		/*
    ++		 * parse_options() always stops parsing options at these,
    ++		 * whatever its flags, so nothing after them is an option.
    ++		 */
    ++		if (!strcmp(arg, "--") || !strcmp(arg, "--end-of-options"))
     +			return i;
     +
    -+		opt = find_early_scan_option(arg, options, &value);
    ++		opt = find_early_scan_option(arg, option, &value);
     +		if (!opt) {
     +			if ((flags & EARLY_SCAN_STOP_AT_NON_OPTION) &&
     +			    (*arg != '-' || !arg[1]))
    @@ parse-options.c: int parse_options(int argc, const char **argv,
     +		 * value and it has to be skipped so that it isn't
     +		 * taken for an option itself.
     +		 */
    -+		if (opt->takes_value && !value && i + 1 < argc)
    ++		if (parse_options_takes_argument(opt) && !value && i + 1 < argc)
     +			value = argv[++i];
     +
    -+		if (opt->wanted && fn(opt, value, pos, data))
    ++		if (opt->flags & PARSE_OPT_EARLY && fn(opt, value, pos, data))
     +			return i;
     +	}
     +
    @@ parse-options.c: int parse_options(int argc, const char **argv,
      	const char *s;
     
      ## parse-options.h ##
    +@@ parse-options.h: enum parse_opt_option_flags {
    + 	PARSE_OPT_NODASH = 1 << 5,
    + 	PARSE_OPT_LITERAL_ARGHELP = 1 << 6,
    + 	PARSE_OPT_FROM_ALIAS = 1 << 7,
    ++	PARSE_OPT_EARLY = 1 << 8,	/* only for early_scan_options() */
    + 	PARSE_OPT_NOCOMPLETE = 1 << 9,
    + 	PARSE_OPT_COMP_ARG = 1 << 10,
    + 	PARSE_OPT_CMDMODE = 1 << 11,
     @@ parse-options.h: static inline void die_for_incompatible_opt2(int opt1, const char *opt1_name,
      		BUG("option callback expects an argument"); \
      } while(0)
    @@ parse-options.h: static inline void die_for_incompatible_opt2(int opt1, const ch
     + * whether a repository is needed at all.
     + *
     + * Such an early scan has to know which options take their value as a
    -+ * separate argument, or it could mistake such a value for an option. The
    -+ * `struct early_scan_option` array passed to early_scan_options() below
    -+ * describes the options to look for, as well as the ones that only need
    -+ * to be skipped along with their value.
    ++ * separate argument, or it could mistake such a value for an
    ++ * option. The functions below allow performing such early scans
    ++ * without being fooled by option values.
     + */
    -+struct early_scan_option {
    -+	const char *name; 	/* Option name, without the leading dashes */
    -+	unsigned takes_value:1; /* "--option=value" or "--option value" expected? */
    -+	unsigned wanted:1;      /* Report option to callback? */
    -+};
    -+
    -+#define EARLY_SCAN_SKIP_VALUE(n) { .name = (n), .takes_value = 1 }
    -+#define EARLY_SCAN_WANT(n) { .name = (n), .wanted = 1 }
    -+#define EARLY_SCAN_WANT_VALUE(n) { .name = (n), .takes_value = 1, .wanted = 1 }
    -+#define EARLY_SCAN_END() { NULL }
     +
     +/*
     + * Called by early_scan_options() for each argument matching a
    -+ * `struct early_scan_option` that has its `wanted` bit set.
    ++ * `struct option` with PARSE_OPT_EARLY set.
     + *
     + * `option` is the matching option, `value` its value or NULL if it
     + * doesn't take one, and `pos` the index of the option in argv.
     + *
     + * Returning a non-zero value stops the scan.
     + */
    -+typedef int early_scan_fn(const struct early_scan_option *option,
    -+			  const char *value, int pos, void *data);
    ++typedef int early_scan_fn(const struct option *option, const char *value,
    ++			  int pos, void *data);
     +
     +enum early_scan_flags {
    -+	EARLY_SCAN_STOP_AT_DASHDASH = 1 << 0, /* Stop at "--" */
    -+	EARLY_SCAN_STOP_AT_NON_OPTION = 1 << 1,
    ++	EARLY_SCAN_STOP_AT_NON_OPTION = 1 << 0, /* Stop at any non option */
     +};
     +
     +/*
    -+ * Scan `argv` for the options described by `options`, calling `fn`
    -+ * for each of those that are `wanted`. `argv` is not modified.
    ++ * Scan `argv` for the options described by `option`, calling `fn` for
    ++ * each of those that have PARSE_OPT_EARLY set. `argv` is not
    ++ * modified.
     + *
    -+ * `fn` may be NULL when no option is `wanted`, which is useful to only
    -+ * find out where the scan stops.
    ++ * `fn` may be NULL when no option has PARSE_OPT_EARLY set, which is
    ++ * useful to only find out where the scan stops.
     + *
    -+ * Note that abbreviated options are not recognized, as a scan cannot
    -+ * know about the options it hasn't been told about, and would then
    -+ * resolve abbreviations differently from the actual option parsing.
    ++ * The scan always stops at "--" and at "--end-of-options", as
    ++ * parse_options() always stops parsing options there too, whatever its
    ++ * flags. PARSE_OPT_KEEP_DASHDASH and PARSE_OPT_KEEP_UNKNOWN_OPT only
    ++ * decide if the terminator is left in argv, not if it terminates.
     + *
     + * Returns the index at which the scan stopped, which is `argc` when the
     + * whole array was scanned.
    ++ *
    ++ * This scan is for now deliberately much simpler than
    ++ * parse_options(), so it differs from it in the following ways:
    ++ *
    ++ *  - Only the long form of an option is matched, and it has to be
    ++ *    spelled in full: short options and abbreviations are ignored.
    ++ *
    ++ *  - Negated forms ("--no-<name>") are not matched. This is harmless,
    ++ *    as they never take a value to skip.
    ++ *
    ++ *  - Options with PARSE_OPT_OPTARG or PARSE_OPT_LASTARG_DEFAULT are
    ++ *    treated as not taking a separate value.
    ++ *
    ++ *  - OPTION_SUBCOMMAND entries are skipped.
    ++ *
    ++ *  - OPTION_ALIAS entries are not resolved to the option they stand
    ++ *    for.
    ++ *
    ++ * So the scan can fail to see an option that parse_options() would
    ++ * accept, and callers have to cope with that, typically by erring on
    ++ * the safe side.
     + */
     +int early_scan_options(int argc, const char **argv,
    -+		       const struct early_scan_option *options,
    ++		       const struct option *option,
     +		       enum early_scan_flags flags,
     +		       early_scan_fn *fn, void *data);
     +
    @@ t/helper/test-parse-options.c: int cmd__parse_subcommand(int argc, const char **
      	return parse_subcommand__cmd(argc, argv, test_flags);
      }
     +
    -+static int show_early_option(const struct early_scan_option *opt,
    -+			     const char *value, int pos, void *data UNUSED)
    ++static int show_early_option(const struct option *opt, const char *value,
    ++			     int pos, void *data UNUSED)
     +{
    -+	printf("found: %s at %d", opt->name, pos);
    ++	printf("found: %s at %d", opt->long_name, pos);
     +	if (value)
     +		printf(" value: %s", value);
     +	putchar('\n');
    @@ t/helper/test-parse-options.c: int cmd__parse_subcommand(int argc, const char **
     +
     +int cmd__early_scan_options(int argc, const char **argv)
     +{
    -+	static const struct early_scan_option options[] = {
    -+		EARLY_SCAN_WANT("wanted"),
    -+		EARLY_SCAN_WANT_VALUE("wanted-value"),
    -+		EARLY_SCAN_SKIP_VALUE("skipped-value"),
    -+		EARLY_SCAN_END()
    ++	char *a_string = NULL;
    ++	int an_int = 0, a_bool = 0, a_short = 0;
    ++
    ++	const struct option option[] = {
    ++		OPT_GROUP("early scan test options"),
    ++		OPT_BOOL_F(0, "wanted", &a_bool,
    ++			   "wanted option taking no value",
    ++			   PARSE_OPT_EARLY),
    ++		OPT_STRING_F(0, "wanted-value", &a_string, "str",
    ++			     "wanted option taking a value",
    ++			     PARSE_OPT_EARLY),
    ++		OPT_STRING(0, "skipped-value", &a_string, "str",
    ++			   "option whose value has to be skipped"),
    ++		OPT_INTEGER(0, "number", &an_int,
    ++			    "option taking an integer value"),
    ++		OPT_STRING_F(0, "optarg", &a_string, "str",
    ++			     "option with an optional value",
    ++			     PARSE_OPT_OPTARG),
    ++		OPT_STRING_F(0, "lastarg", &a_string, "str",
    ++			     "option with a last argument default",
    ++			     PARSE_OPT_LASTARG_DEFAULT),
    ++		OPT_STRING_F(0, "early-optarg", &a_string, "str",
    ++			     "early option with an optional value",
    ++			     PARSE_OPT_EARLY | PARSE_OPT_OPTARG),
    ++		OPT_STRING_F(0, "early-lastarg", &a_string, "str",
    ++			     "early option with a last argument default",
    ++			     PARSE_OPT_EARLY | PARSE_OPT_LASTARG_DEFAULT),
    ++		OPT_BOOL('s', NULL, &a_short, "short only option"),
    ++		OPT_END()
     +	};
    ++
     +	enum early_scan_flags flags = 0;
     +	int stopped;
     +
     +	while (argc > 1 && *argv[1] == '-') {
    -+		if (!strcmp(argv[1], "--stop-at-dashdash"))
    -+			flags |= EARLY_SCAN_STOP_AT_DASHDASH;
    -+		else if (!strcmp(argv[1], "--stop-at-non-option"))
    ++		if (!strcmp(argv[1], "--stop-at-non-option"))
     +			flags |= EARLY_SCAN_STOP_AT_NON_OPTION;
     +		else
     +			break;
    @@ t/helper/test-parse-options.c: int cmd__parse_subcommand(int argc, const char **
     +		argv++;
     +	}
     +
    -+	stopped = early_scan_options(argc - 1, argv + 1, options, flags,
    -+				    show_early_option, NULL);
    ++	stopped = early_scan_options(argc - 1, argv + 1, option, flags,
    ++				     show_early_option, NULL);
     +	printf("stopped at: %d of %d\n", stopped, argc - 1);
     +
     +	return 0;
    @@ t/t0040-parse-options.sh: test_expect_success 'u16 limits range' '
     +	test_cmp expect actual
     +'
     +
    -+test_expect_success 'early_scan_options() can stop at "--"' '
    -+	test-tool early-scan-options --stop-at-dashdash -- --wanted >actual &&
    ++test_expect_success 'early_scan_options() always stops at "--"' '
    ++	test-tool early-scan-options -- --wanted >actual &&
     +	cat >expect <<-\EOF &&
     +	stopped at: 0 of 2
     +	EOF
     +	test_cmp expect actual &&
    -+	test-tool early-scan-options --stop-at-dashdash \
    -+		--skipped-value -- --wanted >actual &&
    ++	test-tool early-scan-options --stop-at-non-option -- --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 0 of 2
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --skipped-value -- --wanted >actual &&
     +	cat >expect <<-\EOF &&
     +	found: wanted at 2
     +	stopped at: 3 of 3
    @@ t/t0040-parse-options.sh: test_expect_success 'u16 limits range' '
     +	test_cmp expect actual
     +'
     +
    ++test_expect_success 'early_scan_options() always stops at "--end-of-options"' '
    ++	test-tool early-scan-options --end-of-options --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 0 of 2
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --stop-at-non-option \
    ++		--end-of-options --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 0 of 2
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
     +test_expect_success 'early_scan_options() can stop at a non-option' '
     +	test-tool early-scan-options --stop-at-non-option \
     +		arg --wanted >actual &&
    @@ t/t0040-parse-options.sh: test_expect_success 'u16 limits range' '
     +	EOF
     +	test_cmp expect actual
     +'
    ++
    ++test_expect_success 'early_scan_options() takes values from struct option' '
    ++	test-tool early-scan-options --number --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 2 of 2
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --number=5 --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: wanted at 1
    ++	stopped at: 2 of 2
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() does not skip an optional value' '
    ++	test-tool early-scan-options --optarg --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: wanted at 1
    ++	stopped at: 2 of 2
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --lastarg --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: wanted at 1
    ++	stopped at: 2 of 2
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() matches a stuck optional value' '
    ++	test-tool early-scan-options --early-optarg=one >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: early-optarg at 0 value: one
    ++	stopped at: 1 of 1
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --early-lastarg=two >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: early-lastarg at 0 value: two
    ++	stopped at: 1 of 1
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() does not take a separate optional value' '
    ++	test-tool early-scan-options --early-optarg --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: early-optarg at 0
    ++	found: wanted at 1
    ++	stopped at: 2 of 2
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --early-lastarg --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: early-lastarg at 0
    ++	found: wanted at 1
    ++	stopped at: 2 of 2
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() ignores options without a long name' '
    ++	test-tool early-scan-options -s --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: wanted at 1
    ++	stopped at: 2 of 2
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() ignores negated options' '
    ++	test-tool early-scan-options --no-wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 1 of 1
    ++	EOF
    ++	test_cmp expect actual
    ++'
     +
      test_done
2:  2adb3b6229 < -:  ---------- bisect: fix "--" detection when a term name is "--"
3:  8bfbd627a8 < -:  ---------- rev-parse: fix "--" detection when it is an option value
5:  69cb1339c6 < -:  ---------- parse-options: build early scan options from a struct option array
6:  a55b275327 ! 3:  8e5092d421 fast-import: use early_scan_options() for --allow-unsafe-features
    @@ Commit message
         sees the option, so unsafe "feature" commands from the stream are
         refused even though the option was given.
     
    -    Let's fix this by building the options for the scan from the same
    -    `struct option` array that parse_options() uses, so that both agree on
    -    which options take a value.
    +    Let's fix this by using early_scan_options(), which scans the very
    +    same `struct option` array that parse_options() uses, so that both
    +    agree on which options take a value, and by marking
    +    `--allow-unsafe-features` with PARSE_OPT_EARLY so that the scan
    +    reports it.
     
         Note that the scan still only matches the exact option spelling, while
         parse_options() also accepts unambiguous abbreviations, so the two still
    @@ Documentation/git-fast-import.adoc: fast-import stream! This option is enabled a
     -them, while `--allow-unsafe-features --depth 5` and
     -`--depth=5 --allow-unsafe-features` allow them.
     +Note that this option has to be spelled in full for the unsafe
    -+`feature` commands in the stream to be allowed. So while
    -+`--allow-unsafe` is accepted as an unambiguous abbreviation of this
    -+option, it still refuses them.
    ++`feature` commands in the stream to be allowed. So `--allow-unsafe`
    ++is accepted as an unambiguous abbreviation of this option, but the
    ++unsafe `feature` commands are still refused.
      
      `--signed-tags=<mode>`::
      	Specify how to handle signed tags. Behaves in the same way as
    @@ builtin/fast-import.c: static int option_parse_quiet(const struct option *opt UN
      	return 0;
      }
      
    -+/*
    -+ * The only option the early scan below is interested in, as it decides
    -+ * whether unsafe "feature" commands from the stream are allowed.
    -+ */
    -+static const char *early_wanted[] = { "allow-unsafe-features", NULL };
    -+
    -+static int option_parse_early_allow_unsafe(
    -+		const struct early_scan_option *opt UNUSED,
    -+		const char *value UNUSED, int pos UNUSED, void *data)
    ++static int option_parse_early_allow_unsafe(const struct option *option,
    ++					   const char *value UNUSED,
    ++					   int pos UNUSED, void *data)
     +{
     +	struct fast_import_state *state = data;
     +
    -+	state->allow_unsafe_features = 1;
    ++	if (!strcmp(option->long_name, "allow-unsafe-features"))
    ++		state->allow_unsafe_features = 1;
     +	return 0;
     +}
     +
      int cmd_fast_import(int argc,
      		    const char **argv,
      		    const char *prefix,
    - 		    struct repository *repo)
    - {
    - 	struct fast_import_state state;
    -+	struct early_scan_option *early;
    - 
    - 	struct option fast_import_options[] = {
    - 		OPT_GROUP(N_("Common")),
    +@@ builtin/fast-import.c: int cmd_fast_import(int argc,
    + 		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),
    ++			   PARSE_OPT_HIDDEN | PARSE_OPT_NONEG | PARSE_OPT_EARLY),
    + 		OPT_CALLBACK_F(0, "export-pack-edges", &state, N_("file"),
    + 			       N_("dump edge commits to <file>"),
    + 			       PARSE_OPT_HIDDEN | PARSE_OPT_NONEG,
     @@ builtin/fast-import.c: int cmd_fast_import(int argc,
      	 * line to override stream data). But we must do an early parse of any
      	 * command-line options that impact how we interpret the feature lines.
    @@ builtin/fast-import.c: int cmd_fast_import(int argc,
     -		if (!strcmp(arg, "--allow-unsafe-features"))
     -			state.allow_unsafe_features = 1;
     -	}
    -+	early = early_scan_options_from_options(fast_import_options,
    -+						early_wanted);
    -+	early_scan_options(argc - 1, argv + 1, early,
    -+			   EARLY_SCAN_STOP_AT_DASHDASH |
    ++	early_scan_options(argc - 1, argv + 1, fast_import_options,
     +			   EARLY_SCAN_STOP_AT_NON_OPTION,
     +			   option_parse_early_allow_unsafe, &state);
    -+	free(early);
      
      	rc_free = mem_pool_alloc(&fi_mem_pool, cmd_save * sizeof(*rc_free));
      	for (unsigned int i = 0; i < (cmd_save - 1); i++)
Christian Couder (3):
  parse-options: add parse_options_takes_argument()
  parse-options: add early_scan_options()
  fast-import: use early_scan_options() for --allow-unsafe-features
 Documentation/git-fast-import.adoc            |  10 +-
 .../technical/api-parse-options.adoc          |   5 +
 builtin/fast-import.c                         |  38 ++--
 parse-options.c                               | 116 ++++++++++--
 parse-options.h                               |  82 +++++++++
 t/helper/test-parse-options.c                 |  62 +++++++
 t/helper/test-tool.c                          |   1 +
 t/helper/test-tool.h                          |   1 +
 t/t0040-parse-options.sh                      | 173 ++++++++++++++++++
 t/t9300-fast-import.sh                        |  14 ++
 10 files changed, 466 insertions(+), 36 deletions(-)
base-commit: d38352cd43ab9745686d697872408bc3249a153f
-- 
2.56.0.rc2
Christian Couder· Sep 23, 2026, 08:09 UTC · re: Christian Couder · lore

[PATCH v2 1/3] parse-options: add parse_options_takes_argument()

Whether an option takes a value, and therefore consumes the next argument when that value is not stuck to it with an '=', is decided by its type and its flags. That rule is currently open-coded in show_gitcomp(), which needs it to decide if it should append an '=' to the option it completes.

A following commit will need the same rule to find out which options an early scan of the command line has to skip along with their value.

So let's factor that rule out into a new parse_options_takes_argument() function, and let's use it in show_gitcomp().

Note that an option with PARSE_OPT_LASTARG_DEFAULT only consumes the next argument when it isn't the last one, so it is not considered as taking a value, which is what show_gitcomp() already did.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 parse-options.c | 35 ++++++++++++++++++++++-------------
 parse-options.h | 10 ++++++++++
 2 files changed, 32 insertions(+), 13 deletions(-)
Show changes to 2 files +32 −13

parse-options.c, parse-options.h

diff --git a/parse-options.c b/parse-options.c
index 4519ead9dc..a132c1ea12 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -841,6 +841,26 @@ static void show_negated_gitcomp(const struct option *opts, int show_all,
 	}
 }
 
+int parse_options_takes_argument(const struct option *opt)
+{
+	switch (opt->type) {
+	case OPTION_STRING:
+	case OPTION_FILENAME:
+	case OPTION_INTEGER:
+	case OPTION_UNSIGNED:
+	case OPTION_CALLBACK:
+		break;
+	default:
+		return 0;
+	}
+
+	if (opt->flags & (PARSE_OPT_NOARG | PARSE_OPT_OPTARG |
+			  PARSE_OPT_LASTARG_DEFAULT))
+		return 0;
+
+	return 1;
+}
+
 static int show_gitcomp(const struct option *opts, int show_all)
 {
 	const struct option *original_opts = opts;
@@ -862,20 +882,9 @@ static int show_gitcomp(const struct option *opts, int show_all)
 			break;
 		case OPTION_GROUP:
 			continue;
-		case OPTION_STRING:
-		case OPTION_FILENAME:
-		case OPTION_INTEGER:
-		case OPTION_UNSIGNED:
-		case OPTION_CALLBACK:
-			if (opts->flags & PARSE_OPT_NOARG)
-				break;
-			if (opts->flags & PARSE_OPT_OPTARG)
-				break;
-			if (opts->flags & PARSE_OPT_LASTARG_DEFAULT)
-				break;
-			suffix = "=";
-			break;
 		default:
+			if (parse_options_takes_argument(opts))
+				suffix = "=";
 			break;
 		}
 		if (opts->flags & PARSE_OPT_COMP_ARG)
diff --git a/parse-options.h b/parse-options.h
index d7f896a933..f29e73f85c 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -420,6 +420,16 @@ int parse_options(int argc, const char **argv, const char *prefix,
 		  const char * const usagestr[],
 		  enum parse_opt_flags flags);
 
+/*
+ * Return non-zero if `opt` takes a value, which means that it consumes
+ * the next argument when that value is not stuck to it with an '='.
+ *
+ * Note that an option with PARSE_OPT_LASTARG_DEFAULT only consumes the
+ * next argument when it isn't the last one, so it is not considered as
+ * taking a value here.
+ */
+int parse_options_takes_argument(const struct option *opt);
+
 NORETURN void usage_with_options(const char * const *usagestr,
 				 const struct option *options);
 
-- 
2.56.0.rc2
Christian Couder· Sep 23, 2026, 08:09 UTC · re: Christian Couder · lore

[PATCH v2 2/3] parse-options: add early_scan_options()

Some commands need to look at a few of their options before they can parse their command line for real, for example because the result decides whether a repository is needed at all, or how the beginning of their input should be interpreted.

Such an early scan has to know which options take their value as a separate argument, or it mistakes such a value for an option. Several commands get this wrong, as they just walk their arguments comparing them to the few option names they care about.

Let's add early_scan_options() to help with this. It walks the arguments using the very same `struct option` array that the command already passes to parse_options(), and uses the parse_options_takes_argument() helper added in a previous commit, so that the scan and the actual parsing agree on which options take a value.

The options the caller wants to be told about are marked with a new PARSE_OPT_EARLY flag, so that nothing has to be spelled out a second time, and so that the mark cannot drift away from the option it refers to.

Using a per-option flag for this is not new as that flag space already holds flags that the parsing loop itself ignores, like PARSE_OPT_NOCOMPLETE and PARSE_OPT_COMP_ARG, which only the completion helper looks at, or PARSE_OPT_HIDDEN and PARSE_OPT_LITERAL_ARGHELP, which only the usage output looks at.

The scan is deliberately kept much simpler than parse_options(), instead of teaching the latter to perform a side effect free "dry run". Such a dry run would have to avoid writing through `opt->value`, calling option callbacks, dying on an invalid value, handling `--help` and tracking command mode conflicts, so it would be a much larger refactoring. If parse_options() learns to do it in the future though, the commands converted now would keep both their option array and their PARSE_OPT_EARLY marks, so their conversion would not have to be redone.

One consequence of staying simple is that abbreviated options are still not matched, even though the scan is now given the command's full option array. Resolving them the way parse_options() does would mean duplicating the ambiguity detection that parse_long_opt() performs. So the scan can fail to see an option that parse_options() would accept, and its callers have to cope with that, typically by erring on the safe side. This and the other differences with parse_options() are documented in "parse-options.h".

In practice, despite these limitations, early scans using early_scan_options() should still be safer and cleaner than the ad-hoc hand-rolled scans they are meant to replace, which don't know about option values at all and therefore disagree with parse_options() in ways that create plain bugs.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 .../technical/api-parse-options.adoc          |   5 +
 parse-options.c                               |  81 ++++++++
 parse-options.h                               |  72 ++++++++
 t/helper/test-parse-options.c                 |  62 +++++++
 t/helper/test-tool.c                          |   1 +
 t/helper/test-tool.h                          |   1 +
 t/t0040-parse-options.sh                      | 173 ++++++++++++++++++
 7 files changed, 395 insertions(+)
Show changes to 7 files +395 −0

Documentation/technical/api-parse-options.adoc, parse-options.c, parse-options.h, t/helper/test-parse-options.c, t/helper/test-tool.c, t/helper/test-tool.h, t/t0040-parse-options.sh

diff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc
index 95b7924e84..f59d8e90a5 100644
--- a/Documentation/technical/api-parse-options.adoc
+++ b/Documentation/technical/api-parse-options.adoc
@@ -197,6 +197,11 @@ are the bitwise-or of:
 	Internal flag, set on options that were expanded from a
 	configured alias. It should not be set by callers.
 
+`PARSE_OPT_EARLY`::
+	Report this option to `early_scan_options()`, which looks at a
+	few options before parsing the command line for real. Ignored
+	by `parse_options()` itself.
+
 `PARSE_OPT_NOCOMPLETE`::
 	Do not offer this option for completion.
 
diff --git a/parse-options.c b/parse-options.c
index a132c1ea12..559dad9061 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -669,6 +669,8 @@ static void parse_options_check(const struct option *opts)
 		     opts->long_name))
 			optbug(opts, "uses feature "
 			       "not supported for dashless options");
+		if ((opts->flags & PARSE_OPT_EARLY) && !opts->long_name)
+			optbug(opts, "uses PARSE_OPT_EARLY, which needs a long name");
 		if (opts->type == OPTION_SET_INT && !opts->defval &&
 		    opts->long_name && !(opts->flags & PARSE_OPT_NONEG))
 			optbug(opts, "OPTION_SET_INT 0 should not be negatable");
@@ -706,6 +708,8 @@ static void parse_options_check(const struct option *opts)
 		case OPTION_SUBCOMMAND:
 			if (!opts->value || !opts->subcommand_fn)
 				optbug(opts, "OPTION_SUBCOMMAND needs a value and a subcommand function");
+			if (opts->flags & PARSE_OPT_EARLY)
+				optbug(opts, "OPTION_SUBCOMMAND does not support PARSE_OPT_EARLY");
 			if (!subcommand_value)
 				subcommand_value = opts->value;
 			else if (subcommand_value != opts->value)
@@ -1253,6 +1257,83 @@ int parse_options(int argc, const char **argv,
 	return parse_options_end(&ctx);
 }
 
+/*
+ * Look for `arg` among `option`. On success, return the matching option
+ * and set `value` to the value stuck to it, if any, or to NULL.
+ */
+static const struct option *find_early_scan_option(const char *arg,
+						   const struct option *option,
+						   const char **value)
+{
+	if (!skip_prefix(arg, "--", &arg))
+		return NULL;
+
+	for (const struct option *opt = option; opt->type != OPTION_END; opt++) {
+		const char *rest;
+
+		if (opt->type == OPTION_SUBCOMMAND)
+			continue;
+		if (!opt->long_name)
+			continue;
+		if (!skip_prefix(arg, opt->long_name, &rest))
+			continue;
+
+		if (!*rest) {
+			*value = NULL;
+			return opt;
+		}
+		/* Only an option that can take a value may have one stuck to it. */
+		if (*rest == '=' && !(opt->flags & PARSE_OPT_NOARG)) {
+			*value = rest + 1;
+			return opt;
+		}
+	}
+
+	return NULL;
+}
+
+int early_scan_options(int argc, const char **argv,
+		       const struct option *option,
+		       enum early_scan_flags flags,
+		       early_scan_fn *fn, void *data)
+{
+	for (int i = 0; i < argc; i++) {
+		const char *arg = argv[i];
+		const char *value;
+		const struct option *opt;
+		int pos = i;
+
+		/*
+		 * parse_options() always stops parsing options at these,
+		 * whatever its flags, so nothing after them is an option.
+		 */
+		if (!strcmp(arg, "--") || !strcmp(arg, "--end-of-options"))
+			return i;
+
+		opt = find_early_scan_option(arg, option, &value);
+		if (!opt) {
+			if ((flags & EARLY_SCAN_STOP_AT_NON_OPTION) &&
+			    (*arg != '-' || !arg[1]))
+				return i;
+			continue;
+		}
+
+		/*
+		 * When an option takes a value, but that value is not
+		 * stuck to it with '=', then the next argument is the
+		 * value and it has to be skipped so that it isn't
+		 * taken for an option itself.
+		 */
+		if (parse_options_takes_argument(opt) && !value && i + 1 < argc)
+			value = argv[++i];
+
+		if (opt->flags & PARSE_OPT_EARLY && fn(opt, value, pos, data))
+			return i;
+	}
+
+	return argc;
+}
+
 static int usage_argh(const struct option *opts, FILE *outfile)
 {
 	const char *s;
diff --git a/parse-options.h b/parse-options.h
index f29e73f85c..3ef64744a4 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -51,6 +51,7 @@ enum parse_opt_option_flags {
 	PARSE_OPT_NODASH = 1 << 5,
 	PARSE_OPT_LITERAL_ARGHELP = 1 << 6,
 	PARSE_OPT_FROM_ALIAS = 1 << 7,
+	PARSE_OPT_EARLY = 1 << 8,	/* only for early_scan_options() */
 	PARSE_OPT_NOCOMPLETE = 1 << 9,
 	PARSE_OPT_COMP_ARG = 1 << 10,
 	PARSE_OPT_CMDMODE = 1 << 11,
@@ -501,6 +502,77 @@ static inline void die_for_incompatible_opt2(int opt1, const char *opt1_name,
 		BUG("option callback expects an argument"); \
 } while(0)
 
+/*----- Early scan: scanning argv before the actual option parsing -----*/
+
+/*
+ * Some commands need to look at a few options before they can parse
+ * their command line for real, for example because the result decides
+ * whether a repository is needed at all.
+ *
+ * Such an early scan has to know which options take their value as a
+ * separate argument, or it could mistake such a value for an
+ * option. The functions below allow performing such early scans
+ * without being fooled by option values.
+ */
+
+/*
+ * Called by early_scan_options() for each argument matching a
+ * `struct option` with PARSE_OPT_EARLY set.
+ *
+ * `option` is the matching option, `value` its value or NULL if it
+ * doesn't take one, and `pos` the index of the option in argv.
+ *
+ * Returning a non-zero value stops the scan.
+ */
+typedef int early_scan_fn(const struct option *option, const char *value,
+			  int pos, void *data);
+
+enum early_scan_flags {
+	EARLY_SCAN_STOP_AT_NON_OPTION = 1 << 0, /* Stop at any non option */
+};
+
+/*
+ * Scan `argv` for the options described by `option`, calling `fn` for
+ * each of those that have PARSE_OPT_EARLY set. `argv` is not
+ * modified.
+ *
+ * `fn` may be NULL when no option has PARSE_OPT_EARLY set, which is
+ * useful to only find out where the scan stops.
+ *
+ * The scan always stops at "--" and at "--end-of-options", as
+ * parse_options() always stops parsing options there too, whatever its
+ * flags. PARSE_OPT_KEEP_DASHDASH and PARSE_OPT_KEEP_UNKNOWN_OPT only
+ * decide if the terminator is left in argv, not if it terminates.
+ *
+ * Returns the index at which the scan stopped, which is `argc` when the
+ * whole array was scanned.
+ *
+ * This scan is for now deliberately much simpler than
+ * parse_options(), so it differs from it in the following ways:
+ *
+ *  - Only the long form of an option is matched, and it has to be
+ *    spelled in full: short options and abbreviations are ignored.
+ *
+ *  - Negated forms ("--no-<name>") are not matched. This is harmless,
+ *    as they never take a value to skip.
+ *
+ *  - Options with PARSE_OPT_OPTARG or PARSE_OPT_LASTARG_DEFAULT are
+ *    treated as not taking a separate value.
+ *
+ *  - OPTION_SUBCOMMAND entries are skipped.
+ *
+ *  - OPTION_ALIAS entries are not resolved to the option they stand
+ *    for.
+ *
+ * So the scan can fail to see an option that parse_options() would
+ * accept, and callers have to cope with that, typically by erring on
+ * the safe side.
+ */
+int early_scan_options(int argc, const char **argv,
+		       const struct option *option,
+		       enum early_scan_flags flags,
+		       early_scan_fn *fn, void *data);
+
 /*----- incremental advanced APIs -----*/
 
 struct parse_opt_cmdmode_list;
diff --git a/t/helper/test-parse-options.c b/t/helper/test-parse-options.c
index f181f0c02d..83522714c8 100644
--- a/t/helper/test-parse-options.c
+++ b/t/helper/test-parse-options.c
@@ -383,3 +383,65 @@ int cmd__parse_subcommand(int argc, const char **argv)
 
 	return parse_subcommand__cmd(argc, argv, test_flags);
 }
+
+static int show_early_option(const struct option *opt, const char *value,
+			     int pos, void *data UNUSED)
+{
+	printf("found: %s at %d", opt->long_name, pos);
+	if (value)
+		printf(" value: %s", value);
+	putchar('\n');
+	return 0;
+}
+
+int cmd__early_scan_options(int argc, const char **argv)
+{
+	char *a_string = NULL;
+	int an_int = 0, a_bool = 0, a_short = 0;
+
+	const struct option option[] = {
+		OPT_GROUP("early scan test options"),
+		OPT_BOOL_F(0, "wanted", &a_bool,
+			   "wanted option taking no value",
+			   PARSE_OPT_EARLY),
+		OPT_STRING_F(0, "wanted-value", &a_string, "str",
+			     "wanted option taking a value",
+			     PARSE_OPT_EARLY),
+		OPT_STRING(0, "skipped-value", &a_string, "str",
+			   "option whose value has to be skipped"),
+		OPT_INTEGER(0, "number", &an_int,
+			    "option taking an integer value"),
+		OPT_STRING_F(0, "optarg", &a_string, "str",
+			     "option with an optional value",
+			     PARSE_OPT_OPTARG),
+		OPT_STRING_F(0, "lastarg", &a_string, "str",
+			     "option with a last argument default",
+			     PARSE_OPT_LASTARG_DEFAULT),
+		OPT_STRING_F(0, "early-optarg", &a_string, "str",
+			     "early option with an optional value",
+			     PARSE_OPT_EARLY | PARSE_OPT_OPTARG),
+		OPT_STRING_F(0, "early-lastarg", &a_string, "str",
+			     "early option with a last argument default",
+			     PARSE_OPT_EARLY | PARSE_OPT_LASTARG_DEFAULT),
+		OPT_BOOL('s', NULL, &a_short, "short only option"),
+		OPT_END()
+	};
+
+	enum early_scan_flags flags = 0;
+	int stopped;
+
+	while (argc > 1 && *argv[1] == '-') {
+		if (!strcmp(argv[1], "--stop-at-non-option"))
+			flags |= EARLY_SCAN_STOP_AT_NON_OPTION;
+		else
+			break;
+		argc--;
+		argv++;
+	}
+
+	stopped = early_scan_options(argc - 1, argv + 1, option, flags,
+				     show_early_option, NULL);
+	printf("stopped at: %d of %d\n", stopped, argc - 1);
+
+	return 0;
+}
diff --git a/t/helper/test-tool.c b/t/helper/test-tool.c
index b71a22b43b..5d2f5877d9 100644
--- a/t/helper/test-tool.c
+++ b/t/helper/test-tool.c
@@ -50,6 +50,7 @@ static struct test_cmd cmds[] = {
 	{ "pack-mtimes", cmd__pack_mtimes },
 	{ "parse-options", cmd__parse_options },
 	{ "parse-options-flags", cmd__parse_options_flags },
+	{ "early-scan-options", cmd__early_scan_options },
 	{ "parse-pathspec-file", cmd__parse_pathspec_file },
 	{ "parse-subcommand", cmd__parse_subcommand },
 	{ "partial-clone", cmd__partial_clone },
diff --git a/t/helper/test-tool.h b/t/helper/test-tool.h
index f2885b33d5..071306d52d 100644
--- a/t/helper/test-tool.h
+++ b/t/helper/test-tool.h
@@ -43,6 +43,7 @@ int cmd__pack_deltas(int argc, const char **argv);
 int cmd__pack_mtimes(int argc, const char **argv);
 int cmd__parse_options(int argc, const char **argv);
 int cmd__parse_options_flags(int argc, const char **argv);
+int cmd__early_scan_options(int argc, const char **argv);
 int cmd__parse_pathspec_file(int argc, const char** argv);
 int cmd__parse_subcommand(int argc, const char **argv);
 int cmd__partial_clone(int argc, const char **argv);
diff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh
index 449fff4d34..b796d96b9a 100755
--- a/t/t0040-parse-options.sh
+++ b/t/t0040-parse-options.sh
@@ -845,4 +845,177 @@ test_expect_success 'u16 limits range' '
 	test_grep "value 65536 for option .u16. not in range \[0,65535\]" err
 '
 
+test_expect_success 'early_scan_options() finds a wanted option' '
+	test-tool early-scan-options --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() reads a stuck or separate value' '
+	test-tool early-scan-options --wanted-value=one >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: one
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --wanted-value two >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: two
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() skips the value of other options' '
+	test-tool early-scan-options --skipped-value --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --skipped-value one --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() always stops at "--"' '
+	test-tool early-scan-options -- --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-non-option -- --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --skipped-value -- --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() always stops at "--end-of-options"' '
+	test-tool early-scan-options --end-of-options --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-non-option \
+		--end-of-options --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() can stop at a non-option' '
+	test-tool early-scan-options --stop-at-non-option \
+		arg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-non-option \
+		--skipped-value arg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() ignores abbreviated options' '
+	test-tool early-scan-options --want >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() takes values from struct option' '
+	test-tool early-scan-options --number --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --number=5 --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() does not skip an optional value' '
+	test-tool early-scan-options --optarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --lastarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() matches a stuck optional value' '
+	test-tool early-scan-options --early-optarg=one >actual &&
+	cat >expect <<-\EOF &&
+	found: early-optarg at 0 value: one
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --early-lastarg=two >actual &&
+	cat >expect <<-\EOF &&
+	found: early-lastarg at 0 value: two
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() does not take a separate optional value' '
+	test-tool early-scan-options --early-optarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: early-optarg at 0
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --early-lastarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: early-lastarg at 0
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() ignores options without a long name' '
+	test-tool early-scan-options -s --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() ignores negated options' '
+	test-tool early-scan-options --no-wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
 test_done
-- 
2.56.0.rc2
Kaartic Sivaraam· Sep 30, 2026, 07:13 UTC · re: Christian Couder · lore

Re: [PATCH v2 2/3] parse-options: add early_scan_options()

On 9/23/26 13:39, Christian Couder wrote:
>
 > [ snip ]
 >
Show 9 quoted lines
> One consequence of staying simple is that abbreviated options are
> still not matched, even though the scan is now given the command's
> full option array. Resolving them the way parse_options() does would
> mean duplicating the ambiguity detection that parse_long_opt()
> performs. So the scan can fail to see an option that parse_options()
> would accept, and its callers have to cope with that, typically by
> erring on the safe side. This and the other differences with
> parse_options() are documented in "parse-options.h".
> 

I think not handling abbreviations could also have another potential problem. Consider a command as follows:

  $ git fast-import --quiet --export-pack --allow-unsafe-features

Here `--export-pack` is an abbreviation of `--export-pack-edges`. So, the arg next to it should ideally be considered as a value for it but given the correct "ignore" logic, we will happily interpret is an argument which misaligns with parse_options()'s behaviour.

In the ideal world, we could say such weird names for files is unlikely and this isn't such a big concern. But given it is the scope of this series to make early scan more reliable, I think we should consider how to handle this better.

Would it make sense to actually err on the safe side and just stop walking the args as soon as we notice an unrecognized argument? This will the ensure the walk never misinterpret a value for an argument.

Show 6 quoted lines
>   
> diff --git a/parse-options.c b/parse-options.c
> index a132c1ea12..559dad9061 100644
> --- a/parse-options.c
> +++ b/parse-options.c
>
 > [ snip ]
 >
Show 35 quoted lines
> +int early_scan_options(int argc, const char **argv,
> +		       const struct option *option,
> +		       enum early_scan_flags flags,
> +		       early_scan_fn *fn, void *data)
> +{
> +	for (int i = 0; i < argc; i++) {
> +		const char *arg = argv[i];
> +		const char *value;
> +		const struct option *opt;
> +		int pos = i;
> +
> +		/*
> +		 * parse_options() always stops parsing options at these,
> +		 * whatever its flags, so nothing after them is an option.
> +		 */
> +		if (!strcmp(arg, "--") || !strcmp(arg, "--end-of-options"))
> +			return i;
> +
> +		opt = find_early_scan_option(arg, option, &value);
> +		if (!opt) {
> +			if ((flags & EARLY_SCAN_STOP_AT_NON_OPTION) &&
> +			    (*arg != '-' || !arg[1]))
> +				return i;
> +			continue;
> +		}
> +
> +		/*
> +		 * When an option takes a value, but that value is not
> +		 * stuck to it with '=', then the next argument is the
> +		 * value and it has to be skipped so that it isn't
> +		 * taken for an option itself.
> +		 */
> +		if (parse_options_takes_argument(opt) && !value && i + 1 < argc)
> +			value = argv[++i];
> +

The 'i +1 < argc' part is an appropriate guard to have. But this means a command such as the following:

   test-tool early-scan-options --wanted-value

... would reult in 'value' being NULL. I suppose this is kind of expected for the early scan code and is not something we need to worry about?

Show 14 quoted lines
> +		if (opt->flags & PARSE_OPT_EARLY && fn(opt, value, pos, data))
> +			return i;
> +	}
> +
> +	return argc;
> +}
> +
>   static int usage_argh(const struct option *opts, FILE *outfile)
>   {
>   	const char *s;
> diff --git a/parse-options.h b/parse-options.h
> index f29e73f85c..3ef64744a4 100644
> --- a/parse-options.h
> +++ b/parse-options.h
 >
Show 18 quoted lines
> [ snip ]
>
> +/*
> + * Scan `argv` for the options described by `option`, calling `fn` for
> + * each of those that have PARSE_OPT_EARLY set. `argv` is not
> + * modified.
> + *
> + * `fn` may be NULL when no option has PARSE_OPT_EARLY set, which is
> + * useful to only find out where the scan stops.
> + *
> + * The scan always stops at "--" and at "--end-of-options", as
> + * parse_options() always stops parsing options there too, whatever its
> + * flags. PARSE_OPT_KEEP_DASHDASH and PARSE_OPT_KEEP_UNKNOWN_OPT only
> + * decide if the terminator is left in argv, not if it terminates.
> + *
> + * Returns the index at which the scan stopped, which is `argc` when the
> + * whole array was scanned.
> + *

As for the return index, when the callback stops the scan the index returned is that of the option's value rather than the option itself. Would it be better to capture this more clearly?

Also, would it be helpful to also have a test for this?
Show 25 quoted lines
> + * This scan is for now deliberately much simpler than
> + * parse_options(), so it differs from it in the following ways:
> + *
> + *  - Only the long form of an option is matched, and it has to be
> + *    spelled in full: short options and abbreviations are ignored.
> + *
> + *  - Negated forms ("--no-<name>") are not matched. This is harmless,
> + *    as they never take a value to skip.
> + *
> + *  - Options with PARSE_OPT_OPTARG or PARSE_OPT_LASTARG_DEFAULT are
> + *    treated as not taking a separate value.
> + *
> + *  - OPTION_SUBCOMMAND entries are skipped.
> + *
> + *  - OPTION_ALIAS entries are not resolved to the option they stand
> + *    for.
> + *
> + * So the scan can fail to see an option that parse_options() would
> + * accept, and callers have to cope with that, typically by erring on
> + * the safe side.
> + */
> +int early_scan_options(int argc, const char **argv,
> +		       const struct option *option,
> +		       enum early_scan_flags flags,
> +		       early_scan_fn *fn, void *data);
 >
> [ snip ]>
> diff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh
> index 449fff4d34..b796d96b9a 100755
>
 > [ snip ]> +
Show 13 quoted lines
> +test_expect_success 'early_scan_options() takes values from struct option' '
> +	test-tool early-scan-options --number --wanted >actual &&
> +	cat >expect <<-\EOF &&
> +	stopped at: 2 of 2
> +	EOF
> +	test_cmp expect actual &&
> +	test-tool early-scan-options --number=5 --wanted >actual &&
> +	cat >expect <<-\EOF &&
> +	found: wanted at 1
> +	stopped at: 2 of 2
> +	EOF
> +	test_cmp expect actual
> +'

Compared to others, I'm not quite sure this test is testing something special. Do we need it?

Show 29 quoted lines
> +test_expect_success 'early_scan_options() does not skip an optional value' '
> +	test-tool early-scan-options --optarg --wanted >actual &&
> +	cat >expect <<-\EOF &&
> +	found: wanted at 1
> +	stopped at: 2 of 2
> +	EOF
> +	test_cmp expect actual &&
> +	test-tool early-scan-options --lastarg --wanted >actual &&
> +	cat >expect <<-\EOF &&
> +	found: wanted at 1
> +	stopped at: 2 of 2
> +	EOF
> +	test_cmp expect actual
> +'
> +
> +test_expect_success 'early_scan_options() matches a stuck optional value' '
> +	test-tool early-scan-options --early-optarg=one >actual &&
> +	cat >expect <<-\EOF &&
> +	found: early-optarg at 0 value: one
> +	stopped at: 1 of 1
> +	EOF
> +	test_cmp expect actual &&
> +	test-tool early-scan-options --early-lastarg=two >actual &&
> +	cat >expect <<-\EOF &&
> +	found: early-lastarg at 0 value: two
> +	stopped at: 1 of 1
> +	EOF
> +	test_cmp expect actual
> +'
Would the following be a useful part to also add to the above?
          test-tool early-scan-options --optarg=5 --wanted >actual &&
          cat >expect <<-\EOF &&
          found: wanted at 1
          stopped at: 2 of 2
          EOF
          test_cmp expect actual
-- 
Sivaraam
Christian Couder· Oct 12, 2026, 08:10 UTC · re: Kaartic Sivaraam · lore

Re: [PATCH v2 2/3] parse-options: add early_scan_options()

On Wed, Sep 30, 2026 at 9:13 AM Kaartic Sivaraam <kaartic.sivaraam@gmail.com> wrote:

Show 24 quoted lines
>
> On 9/23/26 13:39, Christian Couder wrote:
> >
>  > [ snip ]
>  >
> > One consequence of staying simple is that abbreviated options are
> > still not matched, even though the scan is now given the command's
> > full option array. Resolving them the way parse_options() does would
> > mean duplicating the ambiguity detection that parse_long_opt()
> > performs. So the scan can fail to see an option that parse_options()
> > would accept, and its callers have to cope with that, typically by
> > erring on the safe side. This and the other differences with
> > parse_options() are documented in "parse-options.h".
> >
>
> I think not handling abbreviations could also have another potential
> problem. Consider a command as follows:
>
>   $ git fast-import --quiet --export-pack --allow-unsafe-features
>
> Here `--export-pack` is an abbreviation of `--export-pack-edges`. So,
> the arg next to it should ideally be considered as a value for it but
> given the correct "ignore" logic, we will happily interpret is an
> argument which misaligns with parse_options()'s behaviour.

Right, thanks for pointing this out. In the v3 I have just sent, abbreviations are handled properly, using the same code that parse_options() uses.

Show 8 quoted lines
> In the ideal world, we could say such weird names for files is unlikely
> and this isn't such a big concern. But given it is the scope of this
> series to make early scan more reliable, I think we should consider how
> to handle this better.
>
> Would it make sense to actually err on the safe side and just stop
> walking the args as soon as we notice an unrecognized argument? This
> will the ensure the walk never misinterpret a value for an argument.

This is another improvement in v3. We err on the safe side and just stop the early scan as soon as something is not recognized. Thanks for this suggestion too.

Show 51 quoted lines
> > diff --git a/parse-options.c b/parse-options.c
> > index a132c1ea12..559dad9061 100644
> > --- a/parse-options.c
> > +++ b/parse-options.c
> >
>  > [ snip ]
>  >
> > +int early_scan_options(int argc, const char **argv,
> > +                    const struct option *option,
> > +                    enum early_scan_flags flags,
> > +                    early_scan_fn *fn, void *data)
> > +{
> > +     for (int i = 0; i < argc; i++) {
> > +             const char *arg = argv[i];
> > +             const char *value;
> > +             const struct option *opt;
> > +             int pos = i;
> > +
> > +             /*
> > +              * parse_options() always stops parsing options at these,
> > +              * whatever its flags, so nothing after them is an option.
> > +              */
> > +             if (!strcmp(arg, "--") || !strcmp(arg, "--end-of-options"))
> > +                     return i;
> > +
> > +             opt = find_early_scan_option(arg, option, &value);
> > +             if (!opt) {
> > +                     if ((flags & EARLY_SCAN_STOP_AT_NON_OPTION) &&
> > +                         (*arg != '-' || !arg[1]))
> > +                             return i;
> > +                     continue;
> > +             }
> > +
> > +             /*
> > +              * When an option takes a value, but that value is not
> > +              * stuck to it with '=', then the next argument is the
> > +              * value and it has to be skipped so that it isn't
> > +              * taken for an option itself.
> > +              */
> > +             if (parse_options_takes_argument(opt) && !value && i + 1 < argc)
> > +                     value = argv[++i];
> > +
>
> The 'i +1 < argc' part is an appropriate guard to have. But this means a
> command such as the following:
>
>    test-tool early-scan-options --wanted-value
>
> ... would reult in 'value' being NULL. I suppose this is kind of
> expected for the early scan code and is not something we need to worry
> about?

You were right to ask because it was actually worth worrying about a bit. The early scan reported an option that parse_options() would reject.

But now in v3, the scan stops at such an option instead of reporting it, except when an option with PARSE_OPT_LASTARG_DEFAULT is the last argument. In that special case, parse_options() uses the option's default value, so the scan similarly still reports the option, with a NULL value meaning "the default". Both cases are documented in "parse-options.h" and tested.

Show 39 quoted lines
> > +             if (opt->flags & PARSE_OPT_EARLY && fn(opt, value, pos, data))
> > +                     return i;
> > +     }
> > +
> > +     return argc;
> > +}
> > +
> >   static int usage_argh(const struct option *opts, FILE *outfile)
> >   {
> >       const char *s;
> > diff --git a/parse-options.h b/parse-options.h
> > index f29e73f85c..3ef64744a4 100644
> > --- a/parse-options.h
> > +++ b/parse-options.h
>  >
> > [ snip ]
> >
> > +/*
> > + * Scan `argv` for the options described by `option`, calling `fn` for
> > + * each of those that have PARSE_OPT_EARLY set. `argv` is not
> > + * modified.
> > + *
> > + * `fn` may be NULL when no option has PARSE_OPT_EARLY set, which is
> > + * useful to only find out where the scan stops.
> > + *
> > + * The scan always stops at "--" and at "--end-of-options", as
> > + * parse_options() always stops parsing options there too, whatever its
> > + * flags. PARSE_OPT_KEEP_DASHDASH and PARSE_OPT_KEEP_UNKNOWN_OPT only
> > + * decide if the terminator is left in argv, not if it terminates.
> > + *
> > + * Returns the index at which the scan stopped, which is `argc` when the
> > + * whole array was scanned.
> > + *
>
> As for the return index, when the callback stops the scan the index
> returned is that of the option's value rather than the option itself.
> Would it be better to capture this more clearly?
>
> Also, would it be helpful to also have a test for this?

Right. The index returned in that case was the index of the last argument consumed, while in all the other cases it was the index of the first argument not consumed (the "--", the non-option, etc), which was not consistent.

In v3, early_scan_options() always returns the index of the first argument not consumed by the scan. So if it found an option it was looking for, this is the index of the next argument after the option and its value if any.

A "--stop-at-found" option has been added to the test helper to test this. Thanks.

Show 47 quoted lines
> > + * This scan is for now deliberately much simpler than
> > + * parse_options(), so it differs from it in the following ways:
> > + *
> > + *  - Only the long form of an option is matched, and it has to be
> > + *    spelled in full: short options and abbreviations are ignored.
> > + *
> > + *  - Negated forms ("--no-<name>") are not matched. This is harmless,
> > + *    as they never take a value to skip.
> > + *
> > + *  - Options with PARSE_OPT_OPTARG or PARSE_OPT_LASTARG_DEFAULT are
> > + *    treated as not taking a separate value.
> > + *
> > + *  - OPTION_SUBCOMMAND entries are skipped.
> > + *
> > + *  - OPTION_ALIAS entries are not resolved to the option they stand
> > + *    for.
> > + *
> > + * So the scan can fail to see an option that parse_options() would
> > + * accept, and callers have to cope with that, typically by erring on
> > + * the safe side.
> > + */
> > +int early_scan_options(int argc, const char **argv,
> > +                    const struct option *option,
> > +                    enum early_scan_flags flags,
> > +                    early_scan_fn *fn, void *data);
>  >
> > [ snip ]>
> > diff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh
> > index 449fff4d34..b796d96b9a 100755
> >
>  > [ snip ]> +
> > +test_expect_success 'early_scan_options() takes values from struct option' '
> > +     test-tool early-scan-options --number --wanted >actual &&
> > +     cat >expect <<-\EOF &&
> > +     stopped at: 2 of 2
> > +     EOF
> > +     test_cmp expect actual &&
> > +     test-tool early-scan-options --number=5 --wanted >actual &&
> > +     cat >expect <<-\EOF &&
> > +     found: wanted at 1
> > +     stopped at: 2 of 2
> > +     EOF
> > +     test_cmp expect actual
> > +'
>
> Compared to others, I'm not quite sure this test is testing something
> special. Do we need it?
No. It was a leftover from v1.

The `--number --wanted` test was still interesting to check that the value of an OPTION_INTEGER option is skipped, so it was moved into the "skips the value of other options" test, and this one was removed.

Show 38 quoted lines
> > +test_expect_success 'early_scan_options() does not skip an optional value' '
> > +     test-tool early-scan-options --optarg --wanted >actual &&
> > +     cat >expect <<-\EOF &&
> > +     found: wanted at 1
> > +     stopped at: 2 of 2
> > +     EOF
> > +     test_cmp expect actual &&
> > +     test-tool early-scan-options --lastarg --wanted >actual &&
> > +     cat >expect <<-\EOF &&
> > +     found: wanted at 1
> > +     stopped at: 2 of 2
> > +     EOF
> > +     test_cmp expect actual
> > +'
> > +
> > +test_expect_success 'early_scan_options() matches a stuck optional value' '
> > +     test-tool early-scan-options --early-optarg=one >actual &&
> > +     cat >expect <<-\EOF &&
> > +     found: early-optarg at 0 value: one
> > +     stopped at: 1 of 1
> > +     EOF
> > +     test_cmp expect actual &&
> > +     test-tool early-scan-options --early-lastarg=two >actual &&
> > +     cat >expect <<-\EOF &&
> > +     found: early-lastarg at 0 value: two
> > +     stopped at: 1 of 1
> > +     EOF
> > +     test_cmp expect actual
> > +'
>
> Would the following be a useful part to also add to the above?
>
>           test-tool early-scan-options --optarg=5 --wanted >actual &&
>           cat >expect <<-\EOF &&
>           found: wanted at 1
>           stopped at: 2 of 2
>           EOF
>           test_cmp expect actual
Yes, thanks. I added it to the "does not skip an optional value" test.
Christian Couder· Sep 23, 2026, 08:09 UTC · re: Christian Couder · lore

[PATCH v2 3/3] fast-import: use early_scan_options() for --allow-unsafe-features

The "feature" lines at the start of the stream are processed before the command line options are parsed, so cmd_fast_import() scans its arguments early to find out if `--allow-unsafe-features` was given.

That scan doesn't know which options take their value as a separate argument, and it stops at the first argument that doesn't start with a dash. So it disagrees with parse_options(), which accepts values separated from their option by a space, for a command line like "--depth 5 --allow-unsafe-features": the scan stops at "5" and never sees the option, so unsafe "feature" commands from the stream are refused even though the option was given.

Let's fix this by using early_scan_options(), which scans the very same `struct option` array that parse_options() uses, so that both agree on which options take a value, and by marking `--allow-unsafe-features` with PARSE_OPT_EARLY so that the scan reports it.

Note that the scan still only matches the exact option spelling, while parse_options() also accepts unambiguous abbreviations, so the two still disagree for a command line like "--allow-unsafe". This errs on the safe side, and is now documented as a restriction.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 Documentation/git-fast-import.adoc | 10 ++++----
 builtin/fast-import.c              | 38 +++++++++++++++++-------------
 t/t9300-fast-import.sh             | 14 +++++++++++
 3 files changed, 39 insertions(+), 23 deletions(-)
Show changes to 3 files +39 −23

Documentation/git-fast-import.adoc, builtin/fast-import.c, t/t9300-fast-import.sh

diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc
index fd165e11d2..c04b8fe502 100644
--- a/Documentation/git-fast-import.adoc
+++ b/Documentation/git-fast-import.adoc
@@ -66,12 +66,10 @@ fast-import stream! This option is enabled automatically for
 remote-helpers that use the `import` capability, as they are
 already trusted to run their own code.
 +
-Note that this option has to be spelled in full, and has to appear
-before any option whose value is separated from it by a space, for
-the unsafe `feature` commands in the stream to be allowed. So
-`--allow-unsafe` or `--depth 5 --allow-unsafe-features` still refuse
-them, while `--allow-unsafe-features --depth 5` and
-`--depth=5 --allow-unsafe-features` allow them.
+Note that this option has to be spelled in full for the unsafe
+`feature` commands in the stream to be allowed. So `--allow-unsafe`
+is accepted as an unambiguous abbreviation of this option, but the
+unsafe `feature` commands are still refused.
 
 `--signed-tags=<mode>`::
 	Specify how to handle signed tags. Behaves in the same way as
diff --git a/builtin/fast-import.c b/builtin/fast-import.c
index fbd919982c..7f36b828ce 100644
--- a/builtin/fast-import.c
+++ b/builtin/fast-import.c
@@ -4120,6 +4120,17 @@ static int option_parse_quiet(const struct option *opt UNUSED,
 	return 0;
 }
 
+static int option_parse_early_allow_unsafe(const struct option *option,
+					   const char *value UNUSED,
+					   int pos UNUSED, void *data)
+{
+	struct fast_import_state *state = data;
+
+	if (!strcmp(option->long_name, "allow-unsafe-features"))
+		state->allow_unsafe_features = 1;
+	return 0;
+}
+
 int cmd_fast_import(int argc,
 		    const char **argv,
 		    const char *prefix,
@@ -4184,7 +4195,7 @@ int cmd_fast_import(int argc,
 		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),
+			   PARSE_OPT_HIDDEN | PARSE_OPT_NONEG | PARSE_OPT_EARLY),
 		OPT_CALLBACK_F(0, "export-pack-edges", &state, N_("file"),
 			       N_("dump edge commits to <file>"),
 			       PARSE_OPT_HIDDEN | PARSE_OPT_NONEG,
@@ -4218,23 +4229,16 @@ int cmd_fast_import(int argc,
 	 * line to override stream data). But we must do an early parse of any
 	 * command-line options that impact how we interpret the feature lines.
 	 *
-	 * NEEDSWORK: This scan only matches the exact "--allow-unsafe-features"
-	 * spelling and stops at the first argument that doesn't start with a
-	 * dash. As parse_options() below also accepts unambiguous abbreviations
-	 * and values separated by a space from their option, the two disagree
-	 * for command lines like "--allow-unsafe" or "--depth 5
-	 * --allow-unsafe-features": parse_options() accepts the option, but
-	 * this scan doesn't see it, so unsafe features from the stream are
-	 * still refused. This errs on the safe side, but should be fixed by
-	 * teaching this scan about the options that take a value.
+	 * NEEDSWORK: This scan only matches the exact
+	 * "--allow-unsafe-features" spelling, while parse_options() below
+	 * also accepts unambiguous abbreviations, so the two disagree for
+	 * a command line like "--allow-unsafe": parse_options() accepts
+	 * the option, but this scan doesn't see it, so unsafe features
+	 * from the stream are still refused. This errs on the safe side.
 	 */
-	for (int i = 1; i < argc; i++) {
-		const char *arg = argv[i];
-		if (*arg != '-' || !strcmp(arg, "--"))
-			break;
-		if (!strcmp(arg, "--allow-unsafe-features"))
-			state.allow_unsafe_features = 1;
-	}
+	early_scan_options(argc - 1, argv + 1, fast_import_options,
+			   EARLY_SCAN_STOP_AT_NON_OPTION,
+			   option_parse_early_allow_unsafe, &state);
 
 	rc_free = mem_pool_alloc(&fi_mem_pool, cmd_save * sizeof(*rc_free));
 	for (unsigned int i = 0; i < (cmd_save - 1); i++)
diff --git a/t/t9300-fast-import.sh b/t/t9300-fast-import.sh
index d9de2ef0d8..1a37f2b8e6 100755
--- a/t/t9300-fast-import.sh
+++ b/t/t9300-fast-import.sh
@@ -2344,6 +2344,20 @@ test_expect_success 'R: export-marks options can be overridden by commandline op
 	test_path_is_missing feature-sub
 '
 
+test_expect_success 'R: --allow-unsafe-features found after a value' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	git fast-import --allow-unsafe-features <input &&
+	git fast-import --depth=5 --allow-unsafe-features <input &&
+	git fast-import --depth 5 --allow-unsafe-features <input &&
+	git fast-import --date-format raw --allow-unsafe-features <input
+'
+
+test_expect_success 'R: --allow-unsafe-features has to be spelled in full' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	test_must_fail git fast-import --allow-unsafe <input 2>err &&
+	test_grep "forbidden in input without --allow-unsafe-features" err
+'
+
 test_expect_success 'R: catch typo in marks file name' '
 	test_must_fail git fast-import --import-marks=nonexistent.marks </dev/null &&
 	echo "feature import-marks=nonexistent.marks" |
-- 
2.56.0.rc2
Christian Couder· Oct 12, 2026, 07:44 UTC · re: Christian Couder · lore

[PATCH v3 0/4] Standardize early option scanning

A number of commands perform an early scan of their arguments to look for specific flags or structural separators (like `--`).

These hand-rolled early scans are often fragile. They especially fail to account for options that take their value as a separate argument. This leads to disagreements between the early scan and the actual parse_options() pass. For example, the early scanner might miss a special option entirely, or mistakenly treat an option's value as the `--` path separator.

To allow these commands to safely skip option values during their early scans, this series introduces a new "early-scan" sub-API into the existing "parse-options" API.

This is deliberately implemented as a new simple and fast scan. A full 'dry run' of parse_options() would have to avoid writing through `opt->value`, calling callbacks or dying. Instead, the scan reuses only the long option lookup of parse_options(), and stops when unsure.

This allows negated options ("--no-..."), unambiguous abbreviated options and aliases to be properly handled. The early scan also agrees with parse_options() on which options take a value, including those with PARSE_OPT_OPTARG or PARSE_OPT_LASTARG_DEFAULT.

To never misinterpret an option's value as an option though, it stops at any argument it cannot reliably skip:

 1. a short option, or a bundle of them,
 2. an unknown option, or an ambiguous or disallowed abbreviation,
 3. an option with a low-level callback, as such a callback may
 consume any number of arguments,
 4. an option with a missing or stuck value that parse_options() would
 reject, like "--no-<name>=<value>".

So the scan may fail to see an option that parse_options() would accept, but it doesn't report an option that parse_options() would not, and callers can safely err on the side of not having seen it.

This holds as long as the scan is told how the later parse_options() call treats its arguments: EARLY_SCAN_STOP_AT_NON_OPTION should be passed when parse_options() stops at non-options or has subcommands, and the scan should not be used with PARSE_OPT_KEEP_UNKNOWN_OPT, which disables abbreviations in parse_options() only.

The early scan is performed by a new early_scan_options() function which takes a regular `const struct option *option` array as argument.

This requires that the command already uses `struct option` and the parse-options API to parse its arguments. As the majority of commands performing an early scan don't use the parse-options API yet, they will have to be converted to use it before they can use early_scan_options().

In this series, only `git fast-import` is converted to the early-scan API. Its hand-rolled scan disagreed with parse_options() in both directions:

  - `git fast-import --depth 5 --allow-unsafe-features` silently
    ignored `--allow-unsafe-features`, refusing unsafe features from
    the stream, and so did `--allow-unsafe`, its abbreviation,
  - `git fast-import --quiet --export-pack --allow-unsafe-features`
    and `git fast-import --end-of-options --allow-unsafe-features`
    allowed unsafe features from the stream, while parse_options()
    takes `--allow-unsafe-features` as the value of
    `--export-pack-edges` in the first case, and as a non-option
    argument in the second one.
All these cases now agree with parse_options().

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

 - Patch 1/4 refactors some existing code into a new
   parse_options_takes_argument() helper that will be used in patch
   3/4.
 - Patch 2/4 is new in this v3. It extracts the long option lookup
   code from parse_long_opt() into a new lookup_long_opt() function,
   so that the function can be reused in the next patch.
 - Patch 3/4 introduces early_scan_options(), the early scanner that
   will be used instead of hand-rolled ones, along with the
   PARSE_OPT_EARLY flag and tests.
 - Patch 4/4 uses early_scan_options() to fix the early scan for
   `--allow-unsafe-features` in `git fast-import`.

Changes since v2 ================

Thanks a lot to Junio and Kaartic who reviewed previous versions.

Rebased on top of a018953688 (Git 2.56, 2026-09-27) to start from a stable base.

There are a number of important changes since v2:
 - In patch 1/4, parse_options_takes_argument() now considers
   PARSE_OPT_LASTARG_DEFAULT options as taking a value. This allows us
   to remove a limitation that was in v2 as these options now consume
   the next argument when there is one, like in parse_options().
 - Patch 2/4 is new, see above.
 - In patch 3/4, we reuse the new lookup_long_opt() function extracted
   by patch 2/4. This removes a number of limitations (around negated
   forms, unambiguous abbreviations and aliases) that were in v2, as
   the early scan now behaves in a similar way as parse_options()
   regarding long options. A number of tests have been added to ensure
   that.
 - In patch 3/4, the scan now stops at short options, unknown options,
   ambiguous or disallowed abbreviations, options with a low-level
   callback, and value-taking options given as the last argument,
   instead of skipping over them, as it could otherwise take an
   option's value for an option.
 - In patch 3/4, early_scan_fn() has a new `unset` argument for
   negated options, and early_scan_options() now returns the index of
   the first argument not consumed also when the callback stops the
   scan.
 - In patch 4/4, the commit message and documentation are updated to
   account for the better behavior of the early scan. A related
   NEEDSWORK comment is also removed, and some tests added.

CI tests: =========

They all pass, see:
https://github.com/chriscool/git/actions/runs/37965635739

Range-diff since v2 ===================

1:  32adff46ce ! 1:  57c48ab0fe parse-options: add parse_options_takes_argument()
    @@ Commit message
         function, and let's use it in show_gitcomp().
     
         Note that an option with PARSE_OPT_LASTARG_DEFAULT only consumes the
    -    next argument when it isn't the last one, so it is not considered as
    -    taking a value, which is what show_gitcomp() already did.
    +    next argument when it isn't the last one. It is considered as taking a
    +    value by parse_options_takes_argument(), as an early scan can easily
    +    check whether there is a next argument, and would otherwise wrongly
    +    take that argument for an option. show_gitcomp() keeps not appending
    +    an '=' to such an option though, as it already did, since its value is
    +    optional.
     
         Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
    @@ parse-options.c: static void show_negated_gitcomp(const struct option *opts, int
     +		return 0;
     +	}
     +
    -+	if (opt->flags & (PARSE_OPT_NOARG | PARSE_OPT_OPTARG |
    -+			  PARSE_OPT_LASTARG_DEFAULT))
    ++	if (opt->flags & (PARSE_OPT_NOARG | PARSE_OPT_OPTARG))
     +		return 0;
     +
     +	return 1;
    @@ parse-options.c: static int show_gitcomp(const struct option *opts, int show_all
     -			suffix = "=";
     -			break;
      		default:
    -+			if (parse_options_takes_argument(opts))
    ++			if (parse_options_takes_argument(opts) &&
    ++			    !(opts->flags & PARSE_OPT_LASTARG_DEFAULT))
     +				suffix = "=";
      			break;
      		}
    @@ parse-options.h: int parse_options(int argc, const char **argv, const char *pref
     + * Return non-zero if `opt` takes a value, which means that it consumes
     + * the next argument when that value is not stuck to it with an '='.
     + *
    -+ * Note that an option with PARSE_OPT_LASTARG_DEFAULT only consumes the
    -+ * next argument when it isn't the last one, so it is not considered as
    -+ * taking a value here.
    ++ * Note that an option with PARSE_OPT_LASTARG_DEFAULT is considered as
    ++ * taking a value here, even though it only consumes the next argument
    ++ * when it isn't the last one. Callers that care have to check for that
    ++ * flag themselves.
     + */
     +int parse_options_takes_argument(const struct option *opt);
     +
-:  ---------- > 2:  38243ce8bf parse-options: extract lookup_long_opt() from parse_long_opt()
2:  82569fa602 ! 3:  c36cae4e44 parse-options: add early_scan_options()
    @@ Commit message
     
         Let's add early_scan_options() to help with this. It walks the
         arguments using the very same `struct option` array that the command
    -    already passes to parse_options(), and uses the
    -    parse_options_takes_argument() helper added in a previous commit, so
    -    that the scan and the actual parsing agree on which options take a
    -    value.
    +    already passes to parse_options(). It looks up long options with the
    +    lookup_long_opt() helper extracted from parse_long_opt() in a previous
    +    commit, so that negated forms, unambiguous abbreviations and aliases
    +    are recognized the same way, and it uses the
    +    parse_options_takes_argument() helper added in another previous
    +    commit, so that the scan and the actual parsing agree on which options
    +    take a value.
     
         The options the caller wants to be told about are marked with a new
         PARSE_OPT_EARLY flag, so that nothing has to be spelled out a second
    @@ Commit message
         the commands converted now would keep both their option array and their
         PARSE_OPT_EARLY marks, so their conversion would not have to be redone.
     
    -    One consequence of staying simple is that abbreviated options are
    -    still not matched, even though the scan is now given the command's
    -    full option array. Resolving them the way parse_options() does would
    -    mean duplicating the ambiguity detection that parse_long_opt()
    -    performs. So the scan can fail to see an option that parse_options()
    -    would accept, and its callers have to cope with that, typically by
    -    erring on the safe side. This and the other differences with
    -    parse_options() are documented in "parse-options.h".
    +    One consequence of staying simple is that the scan doesn't try to
    +    handle what it cannot reliably skip, like short options, unknown
    +    options, ambiguous abbreviations or options with a low-level callback,
    +    which may consume any number of arguments. It stops at them instead,
    +    so that it never takes an option's value for an option. This matters,
    +    as for example with:
    +
    +      git fast-import --quiet --export-pack --allow-unsafe-features
    +
    +    parse_options() takes `--allow-unsafe-features` as the value of
    +    `--export-pack-edges`, which `--export-pack` abbreviates. A scan that
    +    just skipped `--export-pack` as an unknown option would wrongly see
    +    `--allow-unsafe-features` there.
    +
    +    So the scan can fail to see an option that parse_options() would
    +    accept, but it doesn't report an option that parse_options() would
    +    not, and its callers can safely err on the side of not having seen an
    +    option. The differences with parse_options() are documented in
    +    "parse-options.h".
     
         In practice, despite these limitations, early scans using
         early_scan_options() should still be safer and cleaner than the
    @@ Commit message
         about option values at all and therefore disagree with
         parse_options() in ways that create plain bugs.
     
    +    Helped-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
         Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
      ## Documentation/technical/api-parse-options.adoc ##
    @@ parse-options.c: int parse_options(int argc, const char **argv,
      }
      
     +/*
    -+ * Look for `arg` among `option`. On success, return the matching option
    -+ * and set `value` to the value stuck to it, if any, or to NULL.
    ++ * Look for `name`, a long option without its leading "--", among
    ++ * `option`, the way parse_options() would. Return true if it names an
    ++ * option exactly, or as an unambiguous abbreviation that is not
    ++ * disallowed, with `found` set to that option and its flags, and
    ++ * `stuck` to the value stuck to it, if any, or to NULL.
    ++ */
    ++static bool find_early_scan_option(struct parse_opt_ctx_t *p,
    ++				   const char *name,
    ++				   const struct option *option,
    ++				   bool disallow_abbrev,
    ++				   struct parsed_option *found,
    ++				   const char **stuck)
    ++{
    ++	struct parsed_option other;
    ++	enum long_opt_lookup result = lookup_long_opt(p, name, option,
    ++						      found, &other, stuck);
    ++
    ++	switch (result) {
    ++	case LONG_OPT_EXACT:
    ++		return true;
    ++	case LONG_OPT_ABBREV:
    ++		return !disallow_abbrev;
    ++	case LONG_OPT_AMBIGUOUS:
    ++	case LONG_OPT_UNKNOWN:
    ++		return false;
    ++	}
    ++
    ++	BUG("unknown enum long_opt_lookup value '%d'", result);
    ++}
    ++
    ++struct early_scan_state {
    ++	struct parse_opt_ctx_t ctx;
    ++	const struct option *option;
    ++	enum early_scan_flags flags;
    ++	early_scan_fn *fn;
    ++	void *data;
    ++	bool disallow_abbrev;
    ++};
    ++
    ++/*
    ++ * Look at argv[*i]. Return 'true' to go on scanning, with *i on the
    ++ * last argument consumed. Return 'false' to stop, with *i set to the
    ++ * first argument not consumed.
     + */
    -+static const struct option *find_early_scan_option(const char *arg,
    -+						   const struct option *option,
    -+						   const char **value)
    ++static bool early_scan_one_option(struct early_scan_state *s,
    ++				  int argc, const char **argv, int *i)
     +{
    -+	if (!skip_prefix(arg, "--", &arg))
    -+		return NULL;
    -+
    -+	for (const struct option *opt = option; opt->type != OPTION_END; opt++) {
    -+		const char *rest;
    -+
    -+		if (opt->type == OPTION_SUBCOMMAND)
    -+			continue;
    -+		if (!opt->long_name)
    -+			continue;
    -+		if (!skip_prefix(arg, opt->long_name, &rest))
    -+			continue;
    -+
    -+		if (!*rest) {
    -+			*value = NULL;
    -+			return opt;
    -+		}
    -+		/* Only an option that can take a value may have one stuck to it. */
    -+		if (*rest == '=' && !(opt->flags & PARSE_OPT_NOARG)) {
    -+			*value = rest + 1;
    -+			return opt;
    -+		}
    ++	const char *name;
    ++	const char *value;
    ++	struct parsed_option found;
    ++	bool unset;
    ++	int pos = *i;
    ++	const char *arg = argv[pos];
    ++
    ++	/*
    ++	 * parse_options() always stops parsing options at these,
    ++	 * whatever its flags, so nothing after them is an option.
    ++	 */
    ++	if (!strcmp(arg, "--") || !strcmp(arg, "--end-of-options"))
    ++		return false;
    ++
    ++	/* non-option */
    ++	if (*arg != '-' || !arg[1])
    ++		return !(s->flags & EARLY_SCAN_STOP_AT_NON_OPTION);
    ++
    ++	/* short option */
    ++	if (!skip_prefix(arg, "--", &name))
    ++		return false;
    ++
    ++	/* unknown, ambiguous or disallowed abbreviation */
    ++	if (!find_early_scan_option(&s->ctx, name, s->option,
    ++				    s->disallow_abbrev, &found, &value))
    ++		return false;
    ++
    ++	/* A low-level callback may consume any number of arguments. */
    ++	if (found.option->ll_callback)
    ++		return false;
    ++
    ++	unset = !!(found.flags & OPT_UNSET);
    ++
    ++	/* parse_options() rejects these, so don't go further. */
    ++	if (value && (unset || (found.option->flags & PARSE_OPT_NOARG)))
    ++		return false;
    ++
    ++	/*
    ++	 * Like get_arg(), take the next argument as the value when it is
    ++	 * not stuck to the option. When there is no next argument,
    ++	 * parse_options() uses the default value of an option with
    ++	 * PARSE_OPT_LASTARG_DEFAULT, but errors out for other options.
    ++	 */
    ++	if (!value && !unset && parse_options_takes_argument(found.option)) {
    ++		if (pos + 1 < argc)
    ++			value = argv[++*i];
    ++		else if (!(found.option->flags & PARSE_OPT_LASTARG_DEFAULT))
    ++			return false;
    ++	}
    ++
    ++	if ((found.option->flags & PARSE_OPT_EARLY) &&
    ++	    s->fn(found.option, value, unset, pos, s->data)) {
    ++		/* the option, and its value if any, have been consumed */
    ++		++*i;
    ++		return false;
     +	}
     +
    -+	return NULL;
    ++	return true;
     +}
     +
     +int early_scan_options(int argc, const char **argv,
    @@ parse-options.c: int parse_options(int argc, const char **argv,
     +		       enum early_scan_flags flags,
     +		       early_scan_fn *fn, void *data)
     +{
    -+	for (int i = 0; i < argc; i++) {
    -+		const char *arg = argv[i];
    -+		const char *value;
    -+		const struct option *opt;
    -+		int pos = i;
    -+
    -+		/*
    -+		 * parse_options() always stops parsing options at these,
    -+		 * whatever its flags, so nothing after them is an option.
    -+		 */
    -+		if (!strcmp(arg, "--") || !strcmp(arg, "--end-of-options"))
    -+			return i;
    -+
    -+		opt = find_early_scan_option(arg, option, &value);
    -+		if (!opt) {
    -+			if ((flags & EARLY_SCAN_STOP_AT_NON_OPTION) &&
    -+			    (*arg != '-' || !arg[1]))
    -+				return i;
    -+			continue;
    -+		}
    -+
    -+		/*
    -+		 * When an option takes a value, but that value is not
    -+		 * stuck to it with '=', then the next argument is the
    -+		 * value and it has to be skipped so that it isn't
    -+		 * taken for an option itself.
    -+		 */
    -+		if (parse_options_takes_argument(opt) && !value && i + 1 < argc)
    -+			value = argv[++i];
    -+
    -+		if (opt->flags & PARSE_OPT_EARLY && fn(opt, value, pos, data))
    -+			return i;
    -+	}
    ++	struct early_scan_state s = {
    ++		.flags = flags,
    ++		.fn = fn,
    ++		.data = data,
    ++		.disallow_abbrev =
    ++			git_env_bool("GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS", 0),
    ++	};
    ++	struct option *real_option = preprocess_options(&s.ctx, option);
    ++	int i;
    ++
    ++	s.option = real_option ? real_option : option;
    ++
    ++	for (i = 0; i < argc; i++)
    ++		if (!early_scan_one_option(&s, argc, argv, &i))
    ++			break;
     +
    -+	return argc;
    ++	free_preprocessed_options(real_option);
    ++	free(s.ctx.alias_groups);
    ++	return i;
     +}
     +
      static int usage_argh(const struct option *opts, FILE *outfile)
    @@ parse-options.h: static inline void die_for_incompatible_opt2(int opt1, const ch
     + * Called by early_scan_options() for each argument matching a
     + * `struct option` with PARSE_OPT_EARLY set.
     + *
    -+ * `option` is the matching option, `value` its value or NULL if it
    -+ * doesn't take one, and `pos` the index of the option in argv.
    ++ * - `option` is the matching option,
    ++ * - `value` its value, or NULL if it doesn't take one or if its value
    ++ *   is optional and wasn't given, as with PARSE_OPT_OPTARG, or with
    ++ *   PARSE_OPT_LASTARG_DEFAULT when the option is the last argument,
    ++ * - `unset` is 'true' for the negated form of the option (like
    ++ *   for parse_opt_cb()), in which case `value` is always NULL, and
    ++ * - `pos` the index of the option in argv.
     + *
    -+ * Returning a non-zero value stops the scan.
    ++ * Returning a non-zero value stops the scan right after the option and
    ++ * its value, if any.
     + */
     +typedef int early_scan_fn(const struct option *option, const char *value,
    -+			  int pos, void *data);
    ++			  bool unset, int pos, void *data);
     +
     +enum early_scan_flags {
     +	EARLY_SCAN_STOP_AT_NON_OPTION = 1 << 0, /* Stop at any non option */
    @@ parse-options.h: static inline void die_for_incompatible_opt2(int opt1, const ch
     + * flags. PARSE_OPT_KEEP_DASHDASH and PARSE_OPT_KEEP_UNKNOWN_OPT only
     + * decide if the terminator is left in argv, not if it terminates.
     + *
    -+ * Returns the index at which the scan stopped, which is `argc` when the
    -+ * whole array was scanned.
    ++ * Returns the index of the first argument not consumed by the scan,
    ++ * which is `argc` when the whole array was scanned.
    ++ *
    ++ * Long options are looked up the same way as parse_options() does,
    ++ * so their negated forms, their unambiguous abbreviations, unless
    ++ * GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS is set, and the OPTION_ALIAS
    ++ * entries standing for them are all recognized, and their value is
    ++ * skipped when they take one.
    ++ *
    ++ * To never misinterpret an option value as an option though, the scan
    ++ * stops at any argument it cannot reliably skip, that is:
     + *
    -+ * This scan is for now deliberately much simpler than
    -+ * parse_options(), so it differs from it in the following ways:
    ++ *  - a short option, or a bundle of them,
     + *
    -+ *  - Only the long form of an option is matched, and it has to be
    -+ *    spelled in full: short options and abbreviations are ignored.
    ++ *  - an unknown option, or an ambiguous or disallowed abbreviation,
     + *
    -+ *  - Negated forms ("--no-<name>") are not matched. This is harmless,
    -+ *    as they never take a value to skip.
    ++ *  - an option with a low-level callback, as such a callback may
    ++ *    consume any number of arguments,
     + *
    -+ *  - Options with PARSE_OPT_OPTARG or PARSE_OPT_LASTARG_DEFAULT are
    -+ *    treated as not taking a separate value.
    ++ *  - an option with a value stuck to it that parse_options() would
    ++ *    reject, like a negated option or a PARSE_OPT_NOARG one,
     + *
    -+ *  - OPTION_SUBCOMMAND entries are skipped.
    ++ *  - an option requiring a value when it is the last argument, which
    ++ *    parse_options() would also reject.
     + *
    -+ *  - OPTION_ALIAS entries are not resolved to the option they stand
    -+ *    for.
    ++ * In all these cases, the scan can fail to see an option that
    ++ * parse_options() would accept, but it doesn't report an option that
    ++ * parse_options() would not, so that callers err on the safe side.
     + *
    -+ * So the scan can fail to see an option that parse_options() would
    -+ * accept, and callers have to cope with that, typically by erring on
    -+ * the safe side.
    ++ * This requires the scan to be told about the way the later
    ++ * parse_options() call treats its arguments though: callers should
    ++ * pass EARLY_SCAN_STOP_AT_NON_OPTION when parse_options() is called
    ++ * with PARSE_OPT_STOP_AT_NON_OPTION or with subcommands, and should
    ++ * not use the scan when parse_options() is called with
    ++ * PARSE_OPT_KEEP_UNKNOWN_OPT, which disables abbreviations there but
    ++ * not here.
     + */
     +int early_scan_options(int argc, const char **argv,
     +		       const struct option *option,
    @@ t/helper/test-parse-options.c: int cmd__parse_subcommand(int argc, const char **
      	return parse_subcommand__cmd(argc, argv, test_flags);
      }
     +
    ++static enum parse_opt_result early_ll_callback(struct parse_opt_ctx_t *ctx UNUSED,
    ++					       const struct option *opt UNUSED,
    ++					       const char *arg UNUSED,
    ++					       int unset UNUSED)
    ++{
    ++	return 0;
    ++}
    ++
     +static int show_early_option(const struct option *opt, const char *value,
    -+			     int pos, void *data UNUSED)
    ++			     bool unset, int pos, void *data)
     +{
    ++	int *stop_at_found = data;
    ++
     +	printf("found: %s at %d", opt->long_name, pos);
    ++	if (unset)
    ++		printf(" unset");
     +	if (value)
     +		printf(" value: %s", value);
     +	putchar('\n');
    -+	return 0;
    ++	return *stop_at_found;
     +}
     +
     +int cmd__early_scan_options(int argc, const char **argv)
    @@ t/helper/test-parse-options.c: int cmd__parse_subcommand(int argc, const char **
     +			     PARSE_OPT_EARLY),
     +		OPT_STRING(0, "skipped-value", &a_string, "str",
     +			   "option whose value has to be skipped"),
    ++		OPT_ALIAS(0, "alias-of-skipped", "skipped-value"),
     +		OPT_INTEGER(0, "number", &an_int,
     +			    "option taking an integer value"),
     +		OPT_STRING_F(0, "optarg", &a_string, "str",
    @@ t/helper/test-parse-options.c: int cmd__parse_subcommand(int argc, const char **
     +		OPT_STRING_F(0, "early-lastarg", &a_string, "str",
     +			     "early option with a last argument default",
     +			     PARSE_OPT_EARLY | PARSE_OPT_LASTARG_DEFAULT),
    ++		OPT_BOOL_F(0, "no-early", &a_bool,
    ++			   "early option whose name starts with 'no-'",
    ++			   PARSE_OPT_EARLY),
     +		OPT_BOOL('s', NULL, &a_short, "short only option"),
    ++		{
    ++			.type = OPTION_LOWLEVEL_CALLBACK,
    ++			.long_name = "low-level",
    ++			.help = "option with a low-level callback",
    ++			.flags = PARSE_OPT_NOARG | PARSE_OPT_NONEG,
    ++			.ll_callback = early_ll_callback,
    ++		},
    ++		{
    ++			.type = OPTION_CALLBACK,
    ++			.long_name = "ll-value",
    ++			.argh = "str",
    ++			.help = "option with a value and a low-level callback",
    ++			.flags = PARSE_OPT_NONEG,
    ++			.ll_callback = early_ll_callback,
    ++		},
     +		OPT_END()
     +	};
     +
     +	enum early_scan_flags flags = 0;
    ++	int stop_at_found = 0;
     +	int stopped;
     +
     +	while (argc > 1 && *argv[1] == '-') {
     +		if (!strcmp(argv[1], "--stop-at-non-option"))
     +			flags |= EARLY_SCAN_STOP_AT_NON_OPTION;
    ++		else if (!strcmp(argv[1], "--stop-at-found"))
    ++			stop_at_found = 1;
     +		else
     +			break;
     +		argc--;
    @@ t/helper/test-parse-options.c: int cmd__parse_subcommand(int argc, const char **
     +	}
     +
     +	stopped = early_scan_options(argc - 1, argv + 1, option, flags,
    -+				     show_early_option, NULL);
    ++				     show_early_option, &stop_at_found);
     +	printf("stopped at: %d of %d\n", stopped, argc - 1);
     +
     +	return 0;
    @@ t/t0040-parse-options.sh: test_expect_success 'u16 limits range' '
     +	found: wanted at 2
     +	stopped at: 3 of 3
     +	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --number --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 2 of 2
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() stops at a last option missing its value' '
    ++	test-tool early-scan-options --wanted-value >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 0 of 1
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --wanted --skipped-value >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: wanted at 0
    ++	stopped at: 1 of 2
    ++	EOF
     +	test_cmp expect actual
     +'
     +
    @@ t/t0040-parse-options.sh: test_expect_success 'u16 limits range' '
     +	test_cmp expect actual
     +'
     +
    -+test_expect_success 'early_scan_options() ignores abbreviated options' '
    -+	test-tool early-scan-options --want >actual &&
    ++test_expect_success 'early_scan_options() matches unambiguous abbreviations' '
    ++	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
    ++	test-tool early-scan-options --wanted-v=x >actual &&
     +	cat >expect <<-\EOF &&
    ++	found: wanted-value at 0 value: x
     +	stopped at: 1 of 1
     +	EOF
    ++	test_cmp expect actual &&
    ++	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
    ++	test-tool early-scan-options --wanted-v x --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: wanted-value at 0 value: x
    ++	found: wanted at 2
    ++	stopped at: 3 of 3
    ++	EOF
     +	test_cmp expect actual
     +'
     +
    -+test_expect_success 'early_scan_options() takes values from struct option' '
    -+	test-tool early-scan-options --number --wanted >actual &&
    ++test_expect_success 'early_scan_options() skips the value of an abbreviation' '
    ++	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
    ++	test-tool early-scan-options --skipped --wanted >actual &&
     +	cat >expect <<-\EOF &&
     +	stopped at: 2 of 2
     +	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() stops at an ambiguous abbreviation' '
    ++	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
    ++	test-tool early-scan-options --want --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 0 of 2
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() stops at disallowed abbreviations' '
    ++	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=true \
    ++	test-tool early-scan-options --wanted-v=x >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 0 of 1
    ++	EOF
     +	test_cmp expect actual &&
    -+	test-tool early-scan-options --number=5 --wanted >actual &&
    ++	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=true \
    ++	test-tool early-scan-options --skipped --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 0 of 2
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() stops at an unknown option' '
    ++	test-tool early-scan-options --bogus --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 0 of 2
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() resolves aliases' '
    ++	test-tool early-scan-options --alias-of-skipped --wanted >actual &&
     +	cat >expect <<-\EOF &&
    -+	found: wanted at 1
     +	stopped at: 2 of 2
     +	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --alias-of-skipped x --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: wanted at 2
    ++	stopped at: 3 of 3
    ++	EOF
     +	test_cmp expect actual
     +'
     +
    @@ t/t0040-parse-options.sh: test_expect_success 'u16 limits range' '
     +	stopped at: 2 of 2
     +	EOF
     +	test_cmp expect actual &&
    -+	test-tool early-scan-options --lastarg --wanted >actual &&
    ++	test-tool early-scan-options --optarg=5 --wanted >actual &&
     +	cat >expect <<-\EOF &&
     +	found: wanted at 1
     +	stopped at: 2 of 2
    @@ t/t0040-parse-options.sh: test_expect_success 'u16 limits range' '
     +	test_cmp expect actual
     +'
     +
    ++test_expect_success 'early_scan_options() skips a last argument default value' '
    ++	test-tool early-scan-options --lastarg --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 2 of 2
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --wanted --lastarg >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: wanted at 0
    ++	stopped at: 2 of 2
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
     +test_expect_success 'early_scan_options() matches a stuck optional value' '
     +	test-tool early-scan-options --early-optarg=one >actual &&
     +	cat >expect <<-\EOF &&
    @@ t/t0040-parse-options.sh: test_expect_success 'u16 limits range' '
     +	found: wanted at 1
     +	stopped at: 2 of 2
     +	EOF
    -+	test_cmp expect actual &&
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() takes a last argument default value' '
     +	test-tool early-scan-options --early-lastarg --wanted >actual &&
     +	cat >expect <<-\EOF &&
    -+	found: early-lastarg at 0
    -+	found: wanted at 1
    ++	found: early-lastarg at 0 value: --wanted
     +	stopped at: 2 of 2
     +	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --early-lastarg >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: early-lastarg at 0
    ++	stopped at: 1 of 1
    ++	EOF
     +	test_cmp expect actual
     +'
     +
    -+test_expect_success 'early_scan_options() ignores options without a long name' '
    ++test_expect_success 'early_scan_options() stops at short options' '
     +	test-tool early-scan-options -s --wanted >actual &&
     +	cat >expect <<-\EOF &&
    -+	found: wanted at 1
    -+	stopped at: 2 of 2
    ++	stopped at: 0 of 2
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() stops at low-level callbacks' '
    ++	test-tool early-scan-options --low-level --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 0 of 2
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --ll-value x --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 0 of 3
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() stops after what the callback consumed' '
    ++	test-tool early-scan-options --stop-at-found --wanted --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: wanted at 0
    ++	stopped at: 1 of 2
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --stop-at-found \
    ++		--wanted-value x --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: wanted-value at 0 value: x
    ++	stopped at: 2 of 3
     +	EOF
     +	test_cmp expect actual
     +'
     +
    -+test_expect_success 'early_scan_options() ignores negated options' '
    ++test_expect_success 'early_scan_options() reports negated options' '
     +	test-tool early-scan-options --no-wanted >actual &&
     +	cat >expect <<-\EOF &&
    ++	found: wanted at 0 unset
     +	stopped at: 1 of 1
     +	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --early >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: no-early at 0 unset
    ++	stopped at: 1 of 1
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --no-early >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: no-early at 0
    ++	stopped at: 1 of 1
    ++	EOF
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'early_scan_options() does not take a value for negated options' '
    ++	test-tool early-scan-options --no-wanted-value --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	found: wanted-value at 0 unset
    ++	found: wanted at 1
    ++	stopped at: 2 of 2
    ++	EOF
    ++	test_cmp expect actual &&
    ++	test-tool early-scan-options --no-wanted-value=x --wanted >actual &&
    ++	cat >expect <<-\EOF &&
    ++	stopped at: 0 of 2
    ++	EOF
     +	test_cmp expect actual
     +'
     +
3:  8e5092d421 ! 4:  515f13df83 fast-import: use early_scan_options() for --allow-unsafe-features
    @@ Commit message
         `--allow-unsafe-features` with PARSE_OPT_EARLY so that the scan
         reports it.
     
    -    Note that the scan still only matches the exact option spelling, while
    -    parse_options() also accepts unambiguous abbreviations, so the two still
    -    disagree for a command line like "--allow-unsafe". This errs on the safe
    -    side, and is now documented as a restriction.
    +    As early_scan_options() looks up long options the same way as
    +    parse_options(), the two also agree on abbreviations now. So
    +    `--allow-unsafe` allows unsafe "feature" commands, while
    +    "--quiet --export-pack --allow-unsafe-features" refuses them, as
    +    parse_options() takes `--allow-unsafe-features` there as the value of
    +    `--export-pack-edges`. (The old scan wrongly allowed them in this
    +    case, as all the arguments start with a dash.)
     
    +    The note about having to spell the option in full in the
    +    documentation is therefore removed, and so is the NEEDSWORK comment
    +    about it.
    +
    +    Helped-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
         Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
      ## Documentation/git-fast-import.adoc ##
    -@@ Documentation/git-fast-import.adoc: fast-import stream! This option is enabled automatically for
    +@@ Documentation/git-fast-import.adoc: Only enable this option if you trust the program generating the
    + fast-import stream! This option is enabled automatically for
      remote-helpers that use the `import` capability, as they are
      already trusted to run their own code.
    - +
    +-+
     -Note that this option has to be spelled in full, and has to appear
     -before any option whose value is separated from it by a space, for
     -the unsafe `feature` commands in the stream to be allowed. So
     -`--allow-unsafe` or `--depth 5 --allow-unsafe-features` still refuse
     -them, while `--allow-unsafe-features --depth 5` and
     -`--depth=5 --allow-unsafe-features` allow them.
    -+Note that this option has to be spelled in full for the unsafe
    -+`feature` commands in the stream to be allowed. So `--allow-unsafe`
    -+is accepted as an unambiguous abbreviation of this option, but the
    -+unsafe `feature` commands are still refused.
      
      `--signed-tags=<mode>`::
      	Specify how to handle signed tags. Behaves in the same way as
    @@ builtin/fast-import.c: static int option_parse_quiet(const struct option *opt UN
      
     +static int option_parse_early_allow_unsafe(const struct option *option,
     +					   const char *value UNUSED,
    -+					   int pos UNUSED, void *data)
    ++					   bool unset, int pos UNUSED,
    ++					   void *data)
     +{
     +	struct fast_import_state *state = data;
     +
     +	if (!strcmp(option->long_name, "allow-unsafe-features"))
    -+		state->allow_unsafe_features = 1;
    ++		state->allow_unsafe_features = !unset;
     +	return 0;
     +}
     +
    @@ builtin/fast-import.c: int cmd_fast_import(int argc,
     -	 * this scan doesn't see it, so unsafe features from the stream are
     -	 * still refused. This errs on the safe side, but should be fixed by
     -	 * teaching this scan about the options that take a value.
    -+	 * NEEDSWORK: This scan only matches the exact
    -+	 * "--allow-unsafe-features" spelling, while parse_options() below
    -+	 * also accepts unambiguous abbreviations, so the two disagree for
    -+	 * a command line like "--allow-unsafe": parse_options() accepts
    -+	 * the option, but this scan doesn't see it, so unsafe features
    -+	 * from the stream are still refused. This errs on the safe side.
    ++	 * The scan uses the same options as parse_options() below, so the
    ++	 * two agree on which options take a value and on abbreviations. In
    ++	 * case of doubt, the scan stops early, so unsafe features are then
    ++	 * refused rather than wrongly allowed.
      	 */
     -	for (int i = 1; i < argc; i++) {
     -		const char *arg = argv[i];
    @@ t/t9300-fast-import.sh: test_expect_success 'R: export-marks options can be over
     +	git fast-import --date-format raw --allow-unsafe-features <input
     +'
     +
    -+test_expect_success 'R: --allow-unsafe-features has to be spelled in full' '
    ++test_expect_success 'R: --allow-unsafe-features can be abbreviated' '
    ++	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
    ++	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
    ++	git fast-import --allow-unsafe <input
    ++'
    ++
    ++test_expect_success 'R: disallowed abbreviation of --allow-unsafe-features' '
    ++	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
    ++	test_must_fail env GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=true \
    ++		git fast-import --allow-unsafe <input 2>err &&
    ++	test_grep "forbidden in input without --allow-unsafe-features" err
    ++'
    ++
    ++test_expect_success 'R: --allow-unsafe-features as the value of an abbreviation' '
     +	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
    -+	test_must_fail git fast-import --allow-unsafe <input 2>err &&
    ++	test_must_fail env GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
    ++		git fast-import --quiet --export-pack \
    ++		--allow-unsafe-features <input 2>err &&
     +	test_grep "forbidden in input without --allow-unsafe-features" err
     +'
     +
Christian Couder (4):
  parse-options: add parse_options_takes_argument()
  parse-options: extract lookup_long_opt() from parse_long_opt()
  parse-options: add early_scan_options()
  fast-import: use early_scan_options() for --allow-unsafe-features
 Documentation/git-fast-import.adoc            |   7 -
 .../technical/api-parse-options.adoc          |   5 +
 builtin/fast-import.c                         |  37 +-
 parse-options.c                               | 278 +++++++++++++--
 parse-options.h                               | 102 ++++++
 t/helper/test-parse-options.c                 |  96 ++++++
 t/helper/test-tool.c                          |   1 +
 t/helper/test-tool.h                          |   1 +
 t/t0040-parse-options.sh                      | 321 ++++++++++++++++++
 t/t9300-fast-import.sh                        |  29 ++
 10 files changed, 816 insertions(+), 61 deletions(-)
base-commit: a018953688f1b10bddf91bff8747068f5f4746a4
-- 
2.56.0.116.g6de20f6092
Christian Couder· Oct 12, 2026, 07:44 UTC · re: Christian Couder · lore

[PATCH v3 1/4] parse-options: add parse_options_takes_argument()

Whether an option takes a value, and therefore consumes the next argument when that value is not stuck to it with an '=', is decided by its type and its flags. That rule is currently open-coded in show_gitcomp(), which needs it to decide if it should append an '=' to the option it completes.

A following commit will need the same rule to find out which options an early scan of the command line has to skip along with their value.

So let's factor that rule out into a new parse_options_takes_argument() function, and let's use it in show_gitcomp().

Note that an option with PARSE_OPT_LASTARG_DEFAULT only consumes the next argument when it isn't the last one. It is considered as taking a value by parse_options_takes_argument(), as an early scan can easily check whether there is a next argument, and would otherwise wrongly take that argument for an option. show_gitcomp() keeps not appending an '=' to such an option though, as it already did, since its value is optional.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 parse-options.c | 35 ++++++++++++++++++++++-------------
 parse-options.h | 11 +++++++++++
 2 files changed, 33 insertions(+), 13 deletions(-)
Show changes to 2 files +33 −13

parse-options.c, parse-options.h

diff --git a/parse-options.c b/parse-options.c
index 4519ead9dc..d7cbb5a343 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -841,6 +841,25 @@ static void show_negated_gitcomp(const struct option *opts, int show_all,
 	}
 }
 
+int parse_options_takes_argument(const struct option *opt)
+{
+	switch (opt->type) {
+	case OPTION_STRING:
+	case OPTION_FILENAME:
+	case OPTION_INTEGER:
+	case OPTION_UNSIGNED:
+	case OPTION_CALLBACK:
+		break;
+	default:
+		return 0;
+	}
+
+	if (opt->flags & (PARSE_OPT_NOARG | PARSE_OPT_OPTARG))
+		return 0;
+
+	return 1;
+}
+
 static int show_gitcomp(const struct option *opts, int show_all)
 {
 	const struct option *original_opts = opts;
@@ -862,20 +881,10 @@ static int show_gitcomp(const struct option *opts, int show_all)
 			break;
 		case OPTION_GROUP:
 			continue;
-		case OPTION_STRING:
-		case OPTION_FILENAME:
-		case OPTION_INTEGER:
-		case OPTION_UNSIGNED:
-		case OPTION_CALLBACK:
-			if (opts->flags & PARSE_OPT_NOARG)
-				break;
-			if (opts->flags & PARSE_OPT_OPTARG)
-				break;
-			if (opts->flags & PARSE_OPT_LASTARG_DEFAULT)
-				break;
-			suffix = "=";
-			break;
 		default:
+			if (parse_options_takes_argument(opts) &&
+			    !(opts->flags & PARSE_OPT_LASTARG_DEFAULT))
+				suffix = "=";
 			break;
 		}
 		if (opts->flags & PARSE_OPT_COMP_ARG)
diff --git a/parse-options.h b/parse-options.h
index d7f896a933..589f8d9008 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -420,6 +420,17 @@ int parse_options(int argc, const char **argv, const char *prefix,
 		  const char * const usagestr[],
 		  enum parse_opt_flags flags);
 
+/*
+ * Return non-zero if `opt` takes a value, which means that it consumes
+ * the next argument when that value is not stuck to it with an '='.
+ *
+ * Note that an option with PARSE_OPT_LASTARG_DEFAULT is considered as
+ * taking a value here, even though it only consumes the next argument
+ * when it isn't the last one. Callers that care have to check for that
+ * flag themselves.
+ */
+int parse_options_takes_argument(const struct option *opt);
+
 NORETURN void usage_with_options(const char * const *usagestr,
 				 const struct option *options);
 
-- 
2.56.0.116.g6de20f6092
Christian Couder· Oct 12, 2026, 07:44 UTC · re: Christian Couder · lore

[PATCH v3 2/4] parse-options: extract lookup_long_opt() from parse_long_opt()

In a following commit, an early scan of the command line will need to look up long options the same way parse_options() does, including unambiguous abbreviations and negated forms, but without any side effect: it must neither set option values nor call die() or error().

parse_long_opt() can't be used for that, as it does both the look up and the actions that follow it: it calls get_value() on the option it finds, die()s when abbreviations are disallowed, and error()s on an ambiguous abbreviation.

Let's extract a new lookup_long_opt() helper from parse_long_opt() to perform only the look up part, and let parse_long_opt() act on what lookup_long_opt() returns.

There is no behavior change intended. In particular an exact match is still preferred to any abbreviation, abbreviations are still rejected when disallowed only if there is no exact match, and the ambiguity error message is unchanged.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 parse-options.c | 105 +++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 81 insertions(+), 24 deletions(-)
Show changes to parse-options.c +81 −24
diff --git a/parse-options.c b/parse-options.c
index d7cbb5a343..a98b958423 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -516,16 +516,46 @@ static void register_abbrev(struct parse_opt_ctx_t *p,
 	abbrev->flags = flags;
 }
 
-static enum parse_opt_result parse_long_opt(
-	struct parse_opt_ctx_t *p, const char *arg,
-	const struct option *options)
+enum long_opt_lookup {
+	LONG_OPT_EXACT,      /* exact match found */
+	LONG_OPT_ABBREV,     /* unambiguous abbreviation found */
+	LONG_OPT_AMBIGUOUS,  /* more than one candidate abbreviation */
+	LONG_OPT_UNKNOWN,    /* nothing matches */
+};
+
+/*
+ * Look up the long option named by `arg` (without its leading "--")
+ * without acting on it. (Neither prints nor dies.)
+ *
+ * Return value:
+ * - On LONG_OPT_EXACT, `found` is the exact matching option and its flags
+ *   (including OPT_UNSET for a negated form), and `stuck` points after
+ *   the '=' or is NULL.
+ * - On LONG_OPT_ABBREV, `found` is the unambiguous abbreviation, same as
+ *   above for its flags and `stuck`.
+ * - On LONG_OPT_AMBIGUOUS, `found` and `other` are two candidates of an
+ *   ambiguous abbreviation.
+ * - On LONG_OPT_UNKNOWN, nothing matches, no result.
+ *
+ * `other` is only meaningful for LONG_OPT_AMBIGUOUS.
+ */
+static enum long_opt_lookup lookup_long_opt(struct parse_opt_ctx_t *p,
+					    const char *arg,
+					    const struct option *options,
+					    struct parsed_option *found,
+					    struct parsed_option *other,
+					    const char **stuck)
 {
+	enum opt_parsed flags = OPT_LONG;
 	const char *arg_end = strchrnul(arg, '=');
 	const char *arg_start = arg;
-	enum opt_parsed flags = OPT_LONG;
 	int arg_starts_with_no_no = 0;
-	struct parsed_option abbrev = { .option = NULL, .flags = OPT_LONG };
-	struct parsed_option ambiguous = { .option = NULL, .flags = OPT_LONG };
+
+	found->option = NULL;
+	found->flags = OPT_LONG;
+	other->option = NULL;
+	other->flags = OPT_LONG;
+	*stuck = NULL;
 
 	if (skip_prefix(arg_start, "no-", &arg_start)) {
 		if (skip_prefix(arg_start, "no-", &arg_start))
@@ -554,43 +584,70 @@ static enum parse_opt_result parse_long_opt(
 
 		if (skip_prefix(arg_start, long_name, &rest)) {
 			if (*rest == '=')
-				p->opt = rest + 1;
+				*stuck = rest + 1;
 			else if (*rest)
 				continue;
-			return get_value(p, options, flags ^ opt_flags);
+			found->option = options;
+			found->flags = flags ^ opt_flags;
+			return LONG_OPT_EXACT;
 		}
 
 		/* abbreviated? */
 		if (!strncmp(long_name, arg_start, arg_end - arg_start))
 			register_abbrev(p, options, flags ^ opt_flags,
-					&abbrev, &ambiguous);
+					found, other);
 
 		/* negated and abbreviated very much? */
 		if (allow_unset && starts_with("no-", arg))
 			register_abbrev(p, options, OPT_UNSET ^ opt_flags,
-					&abbrev, &ambiguous);
+					found, other);
 	}
 
-	if (disallow_abbreviated_options && (ambiguous.option || abbrev.option))
+	if (other->option)
+		return LONG_OPT_AMBIGUOUS;
+
+	if (found->option) {
+		if (*arg_end)
+			*stuck = arg_end + 1;
+		return LONG_OPT_ABBREV;
+	}
+
+	return LONG_OPT_UNKNOWN;
+}
+
+static enum parse_opt_result parse_long_opt(struct parse_opt_ctx_t *p,
+					    const char *arg,
+					    const struct option *options)
+{
+	struct parsed_option found;
+	struct parsed_option other;
+	const char *stuck;
+	enum long_opt_lookup result = lookup_long_opt(p, arg, options,
+						      &found, &other, &stuck);
+
+	if (result == LONG_OPT_UNKNOWN)
+		return PARSE_OPT_UNKNOWN;
+
+	if (disallow_abbreviated_options &&
+	    (result == LONG_OPT_ABBREV || result == LONG_OPT_AMBIGUOUS)) {
+		const char *arg_end = strchrnul(arg, '=');
 		die("disallowed abbreviated or ambiguous option '%.*s'",
 		    (int)(arg_end - arg), arg);
+	}
 
-	if (ambiguous.option) {
-		error(_("ambiguous option: %s "
-			"(could be --%s%s or --%s%s)"),
-			arg,
-			(ambiguous.flags & OPT_UNSET) ?  "no-" : "",
-			ambiguous.option->long_name,
-			(abbrev.flags & OPT_UNSET) ?  "no-" : "",
-			abbrev.option->long_name);
+	if (result == LONG_OPT_AMBIGUOUS) {
+		error(_("ambiguous option: %s (could be --%s%s or --%s%s)"), arg,
+		      (other.flags & OPT_UNSET) ? "no-" : "", other.option->long_name,
+		      (found.flags & OPT_UNSET) ? "no-" : "", found.option->long_name);
 		return PARSE_OPT_HELP_ERROR;
 	}
-	if (abbrev.option) {
-		if (*arg_end)
-			p->opt = arg_end + 1;
-		return get_value(p, abbrev.option, abbrev.flags);
+
+	if (result == LONG_OPT_ABBREV || result == LONG_OPT_EXACT) {
+		p->opt = stuck;
+		return get_value(p, found.option, found.flags);
 	}
-	return PARSE_OPT_UNKNOWN;
+
+	BUG("unknown enum long_opt_lookup value '%d'", result);
 }
 
 static enum parse_opt_result parse_nodash_opt(struct parse_opt_ctx_t *p,
-- 
2.56.0.116.g6de20f6092
Kaartic Sivaraam· Oct 30, 2026, 21:08 UTC · re: Christian Couder · lore

Re: [PATCH v3 2/4] parse-options: extract lookup_long_opt() from parse_long_opt()

On 10/12/26 13:14, Christian Couder wrote:
Show 16 quoted lines
> In a following commit, an early scan of the command line will need to
> look up long options the same way parse_options() does, including
> unambiguous abbreviations and negated forms, but without any side
> effect: it must neither set option values nor call die() or error().
> > parse_long_opt() can't be used for that, as it does both the look up
> and the actions that follow it: it calls get_value() on the option it
> finds, die()s when abbreviations are disallowed, and error()s on an
> ambiguous abbreviation.
> > Let's extract a new lookup_long_opt() helper from parse_long_opt() to
> perform only the look up part, and let parse_long_opt() act on what
> lookup_long_opt() returns.
> > There is no behavior change intended. In particular an exact match is
> still preferred to any abbreviation, abbreviations are still rejected
> when disallowed only if there is no exact match, and the ambiguity
> error message is unchanged.
>
Neatly explained!
Show 101 quoted lines
> diff --git a/parse-options.c b/parse-options.c
> index d7cbb5a343..a98b958423 100644
> --- a/parse-options.c
> +++ b/parse-options.c
> @@ -516,16 +516,46 @@ static void register_abbrev(struct parse_opt_ctx_t *p,
>   	abbrev->flags = flags;
>   }
>   > -static enum parse_opt_result parse_long_opt(
> -	struct parse_opt_ctx_t *p, const char *arg,
> -	const struct option *options)
> +enum long_opt_lookup {
> +	LONG_OPT_EXACT,      /* exact match found */
> +	LONG_OPT_ABBREV,     /* unambiguous abbreviation found */
> +	LONG_OPT_AMBIGUOUS,  /* more than one candidate abbreviation */
> +	LONG_OPT_UNKNOWN,    /* nothing matches */
> +};
> +
> +/*
> + * Look up the long option named by `arg` (without its leading "--")
> + * without acting on it. (Neither prints nor dies.)
> + *
> + * Return value:
> + * - On LONG_OPT_EXACT, `found` is the exact matching option and its flags
> + *   (including OPT_UNSET for a negated form), and `stuck` points after
> + *   the '=' or is NULL.
> + * - On LONG_OPT_ABBREV, `found` is the unambiguous abbreviation, same as
> + *   above for its flags and `stuck`.
> + * - On LONG_OPT_AMBIGUOUS, `found` and `other` are two candidates of an
> + *   ambiguous abbreviation.
> + * - On LONG_OPT_UNKNOWN, nothing matches, no result.
> + *
> + * `other` is only meaningful for LONG_OPT_AMBIGUOUS.
> + */
> +static enum long_opt_lookup lookup_long_opt(struct parse_opt_ctx_t *p,
> +					    const char *arg,
> +					    const struct option *options,
> +					    struct parsed_option *found,
> +					    struct parsed_option *other,
> +					    const char **stuck)
>   {
> +	enum opt_parsed flags = OPT_LONG;
>   	const char *arg_end = strchrnul(arg, '=');
>   	const char *arg_start = arg;
> -	enum opt_parsed flags = OPT_LONG;
>   	int arg_starts_with_no_no = 0;
> -	struct parsed_option abbrev = { .option = NULL, .flags = OPT_LONG };
> -	struct parsed_option ambiguous = { .option = NULL, .flags = OPT_LONG };
> +
> +	found->option = NULL;
> +	found->flags = OPT_LONG;
> +	other->option = NULL;
> +	other->flags = OPT_LONG;
> +	*stuck = NULL;
>   >   	if (skip_prefix(arg_start, "no-", &arg_start)) {
>   		if (skip_prefix(arg_start, "no-", &arg_start))
> @@ -554,43 +584,70 @@ static enum parse_opt_result parse_long_opt(
>   >   		if (skip_prefix(arg_start, long_name, &rest)) {
>   			if (*rest == '=')
> -				p->opt = rest + 1;
> +				*stuck = rest + 1;
>   			else if (*rest)
>   				continue;
> -			return get_value(p, options, flags ^ opt_flags);
> +			found->option = options;
> +			found->flags = flags ^ opt_flags;
> +			return LONG_OPT_EXACT;
>   		}
>   >   		/* abbreviated? */
>   		if (!strncmp(long_name, arg_start, arg_end - arg_start))
>   			register_abbrev(p, options, flags ^ opt_flags,
> -					&abbrev, &ambiguous);
> +					found, other);
>   >   		/* negated and abbreviated very much? */
>   		if (allow_unset && starts_with("no-", arg))
>   			register_abbrev(p, options, OPT_UNSET ^ opt_flags,
> -					&abbrev, &ambiguous);
> +					found, other);
>   	}
>   > -	if (disallow_abbreviated_options && (ambiguous.option || abbrev.option))
> +	if (other->option)
> +		return LONG_OPT_AMBIGUOUS;
> +
> +	if (found->option) {
> +		if (*arg_end)
> +			*stuck = arg_end + 1;
> +		return LONG_OPT_ABBREV;
> +	}
> +
> +	return LONG_OPT_UNKNOWN;
> +}
> +
> +static enum parse_opt_result parse_long_opt(struct parse_opt_ctx_t *p,
> +					    const char *arg,
> +					    const struct option *options)
> +{
> +	struct parsed_option found;
> +	struct parsed_option other;
> +	const char *stuck;
> +	enum long_opt_lookup result = lookup_long_opt(p, arg, options,
> +						      &found, &other, &stuck);
> +
Would it not be better to consume the `enum long_op_lookup` return value via a switch rather than having a set of if statements to cover all the cases?
Show 37 quoted lines
> +	if (result == LONG_OPT_UNKNOWN)
> +		return PARSE_OPT_UNKNOWN;
> +
> +	if (disallow_abbreviated_options &&
> +	    (result == LONG_OPT_ABBREV || result == LONG_OPT_AMBIGUOUS)) {
> +		const char *arg_end = strchrnul(arg, '=');
>   		die("disallowed abbreviated or ambiguous option '%.*s'",
>   		    (int)(arg_end - arg), arg);
> +	}
>   > -	if (ambiguous.option) {
> -		error(_("ambiguous option: %s "
> -			"(could be --%s%s or --%s%s)"),
> -			arg,
> -			(ambiguous.flags & OPT_UNSET) ?  "no-" : "",
> -			ambiguous.option->long_name,
> -			(abbrev.flags & OPT_UNSET) ?  "no-" : "",
> -			abbrev.option->long_name);
> +	if (result == LONG_OPT_AMBIGUOUS) {
> +		error(_("ambiguous option: %s (could be --%s%s or --%s%s)"), arg,
> +		      (other.flags & OPT_UNSET) ? "no-" : "", other.option->long_name,
> +		      (found.flags & OPT_UNSET) ? "no-" : "", found.option->long_name);
>   		return PARSE_OPT_HELP_ERROR;
>   	}
> -	if (abbrev.option) {
> -		if (*arg_end)
> -			p->opt = arg_end + 1;
> -		return get_value(p, abbrev.option, abbrev.flags);
> +
> +	if (result == LONG_OPT_ABBREV || result == LONG_OPT_EXACT) {
> +		p->opt = stuck;
> +		return get_value(p, found.option, found.flags);
>   	}
> -	return PARSE_OPT_UNKNOWN;
> +
> +	BUG("unknown enum long_opt_lookup value '%d'", result);
>   }
>   >   static enum parse_opt_result parse_nodash_opt(struct parse_opt_ctx_t *p,
Rest of the patch looks good to me.
-- 
Sivaraam
Christian Couder· Nov 2, 2026, 15:20 UTC · re: Kaartic Sivaraam · lore

Re: [PATCH v3 2/4] parse-options: extract lookup_long_opt() from parse_long_opt()

On Fri, Oct 30, 2026 at 10:09 PM Kaartic Sivaraam <kaartic.sivaraam@gmail.com> wrote:

>
> On 10/12/26 13:14, Christian Couder wrote:
Show 14 quoted lines
> > +static enum parse_opt_result parse_long_opt(struct parse_opt_ctx_t *p,
> > +                                         const char *arg,
> > +                                         const struct option *options)
> > +{
> > +     struct parsed_option found;
> > +     struct parsed_option other;
> > +     const char *stuck;
> > +     enum long_opt_lookup result = lookup_long_opt(p, arg, options,
> > +                                                   &found, &other, &stuck);
> > +
>
> Would it not be better to consume the `enum long_op_lookup` return value
> via a switch rather than having a set of if statements to cover all the
> cases?

Yeah, it might be a bit better with a switch, so the v4 I just sent uses a switch.

Thanks.
Christian Couder· Oct 12, 2026, 07:44 UTC · re: Christian Couder · lore

[PATCH v3 3/4] parse-options: add early_scan_options()

Some commands need to look at a few of their options before they can parse their command line for real, for example because the result decides whether a repository is needed at all, or how the beginning of their input should be interpreted.

Such an early scan has to know which options take their value as a separate argument, or it mistakes such a value for an option. Several commands get this wrong, as they just walk their arguments comparing them to the few option names they care about.

Let's add early_scan_options() to help with this. It walks the arguments using the very same `struct option` array that the command already passes to parse_options(). It looks up long options with the lookup_long_opt() helper extracted from parse_long_opt() in a previous commit, so that negated forms, unambiguous abbreviations and aliases are recognized the same way, and it uses the parse_options_takes_argument() helper added in another previous commit, so that the scan and the actual parsing agree on which options take a value.

The options the caller wants to be told about are marked with a new PARSE_OPT_EARLY flag, so that nothing has to be spelled out a second time, and so that the mark cannot drift away from the option it refers to.

Using a per-option flag for this is not new as that flag space already holds flags that the parsing loop itself ignores, like PARSE_OPT_NOCOMPLETE and PARSE_OPT_COMP_ARG, which only the completion helper looks at, or PARSE_OPT_HIDDEN and PARSE_OPT_LITERAL_ARGHELP, which only the usage output looks at.

The scan is deliberately kept much simpler than parse_options(), instead of teaching the latter to perform a side effect free "dry run". Such a dry run would have to avoid writing through `opt->value`, calling option callbacks, dying on an invalid value, handling `--help` and tracking command mode conflicts, so it would be a much larger refactoring. If parse_options() learns to do it in the future though, the commands converted now would keep both their option array and their PARSE_OPT_EARLY marks, so their conversion would not have to be redone.

One consequence of staying simple is that the scan doesn't try to handle what it cannot reliably skip, like short options, unknown options, ambiguous abbreviations or options with a low-level callback, which may consume any number of arguments. It stops at them instead, so that it never takes an option's value for an option. This matters, as for example with:

  git fast-import --quiet --export-pack --allow-unsafe-features

parse_options() takes `--allow-unsafe-features` as the value of `--export-pack-edges`, which `--export-pack` abbreviates. A scan that just skipped `--export-pack` as an unknown option would wrongly see `--allow-unsafe-features` there.

So the scan can fail to see an option that parse_options() would accept, but it doesn't report an option that parse_options() would not, and its callers can safely err on the side of not having seen an option. The differences with parse_options() are documented in "parse-options.h".

In practice, despite these limitations, early scans using early_scan_options() should still be safer and cleaner than the ad-hoc hand-rolled scans they are meant to replace, which don't know about option values at all and therefore disagree with parse_options() in ways that create plain bugs.

Helped-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 .../technical/api-parse-options.adoc          |   5 +
 parse-options.c                               | 138 ++++++++
 parse-options.h                               |  91 +++++
 t/helper/test-parse-options.c                 |  96 ++++++
 t/helper/test-tool.c                          |   1 +
 t/helper/test-tool.h                          |   1 +
 t/t0040-parse-options.sh                      | 321 ++++++++++++++++++
 7 files changed, 653 insertions(+)
Show changes to 7 files +653 −0

Documentation/technical/api-parse-options.adoc, parse-options.c, parse-options.h, t/helper/test-parse-options.c, t/helper/test-tool.c, t/helper/test-tool.h, t/t0040-parse-options.sh

diff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc
index 95b7924e84..f59d8e90a5 100644
--- a/Documentation/technical/api-parse-options.adoc
+++ b/Documentation/technical/api-parse-options.adoc
@@ -197,6 +197,11 @@ are the bitwise-or of:
 	Internal flag, set on options that were expanded from a
 	configured alias. It should not be set by callers.
 
+`PARSE_OPT_EARLY`::
+	Report this option to `early_scan_options()`, which looks at a
+	few options before parsing the command line for real. Ignored
+	by `parse_options()` itself.
+
 `PARSE_OPT_NOCOMPLETE`::
 	Do not offer this option for completion.
 
diff --git a/parse-options.c b/parse-options.c
index a98b958423..c03c396aa6 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -726,6 +726,8 @@ static void parse_options_check(const struct option *opts)
 		     opts->long_name))
 			optbug(opts, "uses feature "
 			       "not supported for dashless options");
+		if ((opts->flags & PARSE_OPT_EARLY) && !opts->long_name)
+			optbug(opts, "uses PARSE_OPT_EARLY, which needs a long name");
 		if (opts->type == OPTION_SET_INT && !opts->defval &&
 		    opts->long_name && !(opts->flags & PARSE_OPT_NONEG))
 			optbug(opts, "OPTION_SET_INT 0 should not be negatable");
@@ -763,6 +765,8 @@ static void parse_options_check(const struct option *opts)
 		case OPTION_SUBCOMMAND:
 			if (!opts->value || !opts->subcommand_fn)
 				optbug(opts, "OPTION_SUBCOMMAND needs a value and a subcommand function");
+			if (opts->flags & PARSE_OPT_EARLY)
+				optbug(opts, "OPTION_SUBCOMMAND does not support PARSE_OPT_EARLY");
 			if (!subcommand_value)
 				subcommand_value = opts->value;
 			else if (subcommand_value != opts->value)
@@ -1310,6 +1314,140 @@ int parse_options(int argc, const char **argv,
 	return parse_options_end(&ctx);
 }
 
+/*
+ * Look for `name`, a long option without its leading "--", among
+ * `option`, the way parse_options() would. Return true if it names an
+ * option exactly, or as an unambiguous abbreviation that is not
+ * disallowed, with `found` set to that option and its flags, and
+ * `stuck` to the value stuck to it, if any, or to NULL.
+ */
+static bool find_early_scan_option(struct parse_opt_ctx_t *p,
+				   const char *name,
+				   const struct option *option,
+				   bool disallow_abbrev,
+				   struct parsed_option *found,
+				   const char **stuck)
+{
+	struct parsed_option other;
+	enum long_opt_lookup result = lookup_long_opt(p, name, option,
+						      found, &other, stuck);
+
+	switch (result) {
+	case LONG_OPT_EXACT:
+		return true;
+	case LONG_OPT_ABBREV:
+		return !disallow_abbrev;
+	case LONG_OPT_AMBIGUOUS:
+	case LONG_OPT_UNKNOWN:
+		return false;
+	}
+
+	BUG("unknown enum long_opt_lookup value '%d'", result);
+}
+
+struct early_scan_state {
+	struct parse_opt_ctx_t ctx;
+	const struct option *option;
+	enum early_scan_flags flags;
+	early_scan_fn *fn;
+	void *data;
+	bool disallow_abbrev;
+};
+
+/*
+ * Look at argv[*i]. Return 'true' to go on scanning, with *i on the
+ * last argument consumed. Return 'false' to stop, with *i set to the
+ * first argument not consumed.
+ */
+static bool early_scan_one_option(struct early_scan_state *s,
+				  int argc, const char **argv, int *i)
+{
+	const char *name;
+	const char *value;
+	struct parsed_option found;
+	bool unset;
+	int pos = *i;
+	const char *arg = argv[pos];
+
+	/*
+	 * parse_options() always stops parsing options at these,
+	 * whatever its flags, so nothing after them is an option.
+	 */
+	if (!strcmp(arg, "--") || !strcmp(arg, "--end-of-options"))
+		return false;
+
+	/* non-option */
+	if (*arg != '-' || !arg[1])
+		return !(s->flags & EARLY_SCAN_STOP_AT_NON_OPTION);
+
+	/* short option */
+	if (!skip_prefix(arg, "--", &name))
+		return false;
+
+	/* unknown, ambiguous or disallowed abbreviation */
+	if (!find_early_scan_option(&s->ctx, name, s->option,
+				    s->disallow_abbrev, &found, &value))
+		return false;
+
+	/* A low-level callback may consume any number of arguments. */
+	if (found.option->ll_callback)
+		return false;
+
+	unset = !!(found.flags & OPT_UNSET);
+
+	/* parse_options() rejects these, so don't go further. */
+	if (value && (unset || (found.option->flags & PARSE_OPT_NOARG)))
+		return false;
+
+	/*
+	 * Like get_arg(), take the next argument as the value when it is
+	 * not stuck to the option. When there is no next argument,
+	 * parse_options() uses the default value of an option with
+	 * PARSE_OPT_LASTARG_DEFAULT, but errors out for other options.
+	 */
+	if (!value && !unset && parse_options_takes_argument(found.option)) {
+		if (pos + 1 < argc)
+			value = argv[++*i];
+		else if (!(found.option->flags & PARSE_OPT_LASTARG_DEFAULT))
+			return false;
+	}
+
+	if ((found.option->flags & PARSE_OPT_EARLY) &&
+	    s->fn(found.option, value, unset, pos, s->data)) {
+		/* the option, and its value if any, have been consumed */
+		++*i;
+		return false;
+	}
+
+	return true;
+}
+
+int early_scan_options(int argc, const char **argv,
+		       const struct option *option,
+		       enum early_scan_flags flags,
+		       early_scan_fn *fn, void *data)
+{
+	struct early_scan_state s = {
+		.flags = flags,
+		.fn = fn,
+		.data = data,
+		.disallow_abbrev =
+			git_env_bool("GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS", 0),
+	};
+	struct option *real_option = preprocess_options(&s.ctx, option);
+	int i;
+
+	s.option = real_option ? real_option : option;
+
+	for (i = 0; i < argc; i++)
+		if (!early_scan_one_option(&s, argc, argv, &i))
+			break;
+
+	free_preprocessed_options(real_option);
+	free(s.ctx.alias_groups);
+	return i;
+}
+
 static int usage_argh(const struct option *opts, FILE *outfile)
 {
 	const char *s;
diff --git a/parse-options.h b/parse-options.h
index 589f8d9008..f39b9a779a 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -51,6 +51,7 @@ enum parse_opt_option_flags {
 	PARSE_OPT_NODASH = 1 << 5,
 	PARSE_OPT_LITERAL_ARGHELP = 1 << 6,
 	PARSE_OPT_FROM_ALIAS = 1 << 7,
+	PARSE_OPT_EARLY = 1 << 8,	/* only for early_scan_options() */
 	PARSE_OPT_NOCOMPLETE = 1 << 9,
 	PARSE_OPT_COMP_ARG = 1 << 10,
 	PARSE_OPT_CMDMODE = 1 << 11,
@@ -502,6 +503,96 @@ static inline void die_for_incompatible_opt2(int opt1, const char *opt1_name,
 		BUG("option callback expects an argument"); \
 } while(0)
 
+/*----- Early scan: scanning argv before the actual option parsing -----*/
+
+/*
+ * Some commands need to look at a few options before they can parse
+ * their command line for real, for example because the result decides
+ * whether a repository is needed at all.
+ *
+ * Such an early scan has to know which options take their value as a
+ * separate argument, or it could mistake such a value for an
+ * option. The functions below allow performing such early scans
+ * without being fooled by option values.
+ */
+
+/*
+ * Called by early_scan_options() for each argument matching a
+ * `struct option` with PARSE_OPT_EARLY set.
+ *
+ * - `option` is the matching option,
+ * - `value` its value, or NULL if it doesn't take one or if its value
+ *   is optional and wasn't given, as with PARSE_OPT_OPTARG, or with
+ *   PARSE_OPT_LASTARG_DEFAULT when the option is the last argument,
+ * - `unset` is 'true' for the negated form of the option (like
+ *   for parse_opt_cb()), in which case `value` is always NULL, and
+ * - `pos` the index of the option in argv.
+ *
+ * Returning a non-zero value stops the scan right after the option and
+ * its value, if any.
+ */
+typedef int early_scan_fn(const struct option *option, const char *value,
+			  bool unset, int pos, void *data);
+
+enum early_scan_flags {
+	EARLY_SCAN_STOP_AT_NON_OPTION = 1 << 0, /* Stop at any non option */
+};
+
+/*
+ * Scan `argv` for the options described by `option`, calling `fn` for
+ * each of those that have PARSE_OPT_EARLY set. `argv` is not
+ * modified.
+ *
+ * `fn` may be NULL when no option has PARSE_OPT_EARLY set, which is
+ * useful to only find out where the scan stops.
+ *
+ * The scan always stops at "--" and at "--end-of-options", as
+ * parse_options() always stops parsing options there too, whatever its
+ * flags. PARSE_OPT_KEEP_DASHDASH and PARSE_OPT_KEEP_UNKNOWN_OPT only
+ * decide if the terminator is left in argv, not if it terminates.
+ *
+ * Returns the index of the first argument not consumed by the scan,
+ * which is `argc` when the whole array was scanned.
+ *
+ * Long options are looked up the same way as parse_options() does,
+ * so their negated forms, their unambiguous abbreviations, unless
+ * GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS is set, and the OPTION_ALIAS
+ * entries standing for them are all recognized, and their value is
+ * skipped when they take one.
+ *
+ * To never misinterpret an option value as an option though, the scan
+ * stops at any argument it cannot reliably skip, that is:
+ *
+ *  - a short option, or a bundle of them,
+ *
+ *  - an unknown option, or an ambiguous or disallowed abbreviation,
+ *
+ *  - an option with a low-level callback, as such a callback may
+ *    consume any number of arguments,
+ *
+ *  - an option with a value stuck to it that parse_options() would
+ *    reject, like a negated option or a PARSE_OPT_NOARG one,
+ *
+ *  - an option requiring a value when it is the last argument, which
+ *    parse_options() would also reject.
+ *
+ * In all these cases, the scan can fail to see an option that
+ * parse_options() would accept, but it doesn't report an option that
+ * parse_options() would not, so that callers err on the safe side.
+ *
+ * This requires the scan to be told about the way the later
+ * parse_options() call treats its arguments though: callers should
+ * pass EARLY_SCAN_STOP_AT_NON_OPTION when parse_options() is called
+ * with PARSE_OPT_STOP_AT_NON_OPTION or with subcommands, and should
+ * not use the scan when parse_options() is called with
+ * PARSE_OPT_KEEP_UNKNOWN_OPT, which disables abbreviations there but
+ * not here.
+ */
+int early_scan_options(int argc, const char **argv,
+		       const struct option *option,
+		       enum early_scan_flags flags,
+		       early_scan_fn *fn, void *data);
+
 /*----- incremental advanced APIs -----*/
 
 struct parse_opt_cmdmode_list;
diff --git a/t/helper/test-parse-options.c b/t/helper/test-parse-options.c
index f181f0c02d..de3dd5751c 100644
--- a/t/helper/test-parse-options.c
+++ b/t/helper/test-parse-options.c
@@ -383,3 +383,99 @@ int cmd__parse_subcommand(int argc, const char **argv)
 
 	return parse_subcommand__cmd(argc, argv, test_flags);
 }
+
+static enum parse_opt_result early_ll_callback(struct parse_opt_ctx_t *ctx UNUSED,
+					       const struct option *opt UNUSED,
+					       const char *arg UNUSED,
+					       int unset UNUSED)
+{
+	return 0;
+}
+
+static int show_early_option(const struct option *opt, const char *value,
+			     bool unset, int pos, void *data)
+{
+	int *stop_at_found = data;
+
+	printf("found: %s at %d", opt->long_name, pos);
+	if (unset)
+		printf(" unset");
+	if (value)
+		printf(" value: %s", value);
+	putchar('\n');
+	return *stop_at_found;
+}
+
+int cmd__early_scan_options(int argc, const char **argv)
+{
+	char *a_string = NULL;
+	int an_int = 0, a_bool = 0, a_short = 0;
+
+	const struct option option[] = {
+		OPT_GROUP("early scan test options"),
+		OPT_BOOL_F(0, "wanted", &a_bool,
+			   "wanted option taking no value",
+			   PARSE_OPT_EARLY),
+		OPT_STRING_F(0, "wanted-value", &a_string, "str",
+			     "wanted option taking a value",
+			     PARSE_OPT_EARLY),
+		OPT_STRING(0, "skipped-value", &a_string, "str",
+			   "option whose value has to be skipped"),
+		OPT_ALIAS(0, "alias-of-skipped", "skipped-value"),
+		OPT_INTEGER(0, "number", &an_int,
+			    "option taking an integer value"),
+		OPT_STRING_F(0, "optarg", &a_string, "str",
+			     "option with an optional value",
+			     PARSE_OPT_OPTARG),
+		OPT_STRING_F(0, "lastarg", &a_string, "str",
+			     "option with a last argument default",
+			     PARSE_OPT_LASTARG_DEFAULT),
+		OPT_STRING_F(0, "early-optarg", &a_string, "str",
+			     "early option with an optional value",
+			     PARSE_OPT_EARLY | PARSE_OPT_OPTARG),
+		OPT_STRING_F(0, "early-lastarg", &a_string, "str",
+			     "early option with a last argument default",
+			     PARSE_OPT_EARLY | PARSE_OPT_LASTARG_DEFAULT),
+		OPT_BOOL_F(0, "no-early", &a_bool,
+			   "early option whose name starts with 'no-'",
+			   PARSE_OPT_EARLY),
+		OPT_BOOL('s', NULL, &a_short, "short only option"),
+		{
+			.type = OPTION_LOWLEVEL_CALLBACK,
+			.long_name = "low-level",
+			.help = "option with a low-level callback",
+			.flags = PARSE_OPT_NOARG | PARSE_OPT_NONEG,
+			.ll_callback = early_ll_callback,
+		},
+		{
+			.type = OPTION_CALLBACK,
+			.long_name = "ll-value",
+			.argh = "str",
+			.help = "option with a value and a low-level callback",
+			.flags = PARSE_OPT_NONEG,
+			.ll_callback = early_ll_callback,
+		},
+		OPT_END()
+	};
+
+	enum early_scan_flags flags = 0;
+	int stop_at_found = 0;
+	int stopped;
+
+	while (argc > 1 && *argv[1] == '-') {
+		if (!strcmp(argv[1], "--stop-at-non-option"))
+			flags |= EARLY_SCAN_STOP_AT_NON_OPTION;
+		else if (!strcmp(argv[1], "--stop-at-found"))
+			stop_at_found = 1;
+		else
+			break;
+		argc--;
+		argv++;
+	}
+
+	stopped = early_scan_options(argc - 1, argv + 1, option, flags,
+				     show_early_option, &stop_at_found);
+	printf("stopped at: %d of %d\n", stopped, argc - 1);
+
+	return 0;
+}
diff --git a/t/helper/test-tool.c b/t/helper/test-tool.c
index b71a22b43b..5d2f5877d9 100644
--- a/t/helper/test-tool.c
+++ b/t/helper/test-tool.c
@@ -50,6 +50,7 @@ static struct test_cmd cmds[] = {
 	{ "pack-mtimes", cmd__pack_mtimes },
 	{ "parse-options", cmd__parse_options },
 	{ "parse-options-flags", cmd__parse_options_flags },
+	{ "early-scan-options", cmd__early_scan_options },
 	{ "parse-pathspec-file", cmd__parse_pathspec_file },
 	{ "parse-subcommand", cmd__parse_subcommand },
 	{ "partial-clone", cmd__partial_clone },
diff --git a/t/helper/test-tool.h b/t/helper/test-tool.h
index f2885b33d5..071306d52d 100644
--- a/t/helper/test-tool.h
+++ b/t/helper/test-tool.h
@@ -43,6 +43,7 @@ int cmd__pack_deltas(int argc, const char **argv);
 int cmd__pack_mtimes(int argc, const char **argv);
 int cmd__parse_options(int argc, const char **argv);
 int cmd__parse_options_flags(int argc, const char **argv);
+int cmd__early_scan_options(int argc, const char **argv);
 int cmd__parse_pathspec_file(int argc, const char** argv);
 int cmd__parse_subcommand(int argc, const char **argv);
 int cmd__partial_clone(int argc, const char **argv);
diff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh
index 449fff4d34..c44b12e46d 100755
--- a/t/t0040-parse-options.sh
+++ b/t/t0040-parse-options.sh
@@ -845,4 +845,325 @@ test_expect_success 'u16 limits range' '
 	test_grep "value 65536 for option .u16. not in range \[0,65535\]" err
 '
 
+test_expect_success 'early_scan_options() finds a wanted option' '
+	test-tool early-scan-options --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() reads a stuck or separate value' '
+	test-tool early-scan-options --wanted-value=one >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: one
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --wanted-value two >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: two
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() skips the value of other options' '
+	test-tool early-scan-options --skipped-value --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --skipped-value one --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --number --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at a last option missing its value' '
+	test-tool early-scan-options --wanted-value >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --wanted --skipped-value >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0
+	stopped at: 1 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() always stops at "--"' '
+	test-tool early-scan-options -- --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-non-option -- --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --skipped-value -- --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() always stops at "--end-of-options"' '
+	test-tool early-scan-options --end-of-options --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-non-option \
+		--end-of-options --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() can stop at a non-option' '
+	test-tool early-scan-options --stop-at-non-option \
+		arg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-non-option \
+		--skipped-value arg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() matches unambiguous abbreviations' '
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+	test-tool early-scan-options --wanted-v=x >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: x
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+	test-tool early-scan-options --wanted-v x --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: x
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() skips the value of an abbreviation' '
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+	test-tool early-scan-options --skipped --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at an ambiguous abbreviation' '
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+	test-tool early-scan-options --want --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at disallowed abbreviations' '
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=true \
+	test-tool early-scan-options --wanted-v=x >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 1
+	EOF
+	test_cmp expect actual &&
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=true \
+	test-tool early-scan-options --skipped --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at an unknown option' '
+	test-tool early-scan-options --bogus --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() resolves aliases' '
+	test-tool early-scan-options --alias-of-skipped --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --alias-of-skipped x --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() does not skip an optional value' '
+	test-tool early-scan-options --optarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --optarg=5 --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() skips a last argument default value' '
+	test-tool early-scan-options --lastarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --wanted --lastarg >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() matches a stuck optional value' '
+	test-tool early-scan-options --early-optarg=one >actual &&
+	cat >expect <<-\EOF &&
+	found: early-optarg at 0 value: one
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --early-lastarg=two >actual &&
+	cat >expect <<-\EOF &&
+	found: early-lastarg at 0 value: two
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() does not take a separate optional value' '
+	test-tool early-scan-options --early-optarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: early-optarg at 0
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() takes a last argument default value' '
+	test-tool early-scan-options --early-lastarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: early-lastarg at 0 value: --wanted
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --early-lastarg >actual &&
+	cat >expect <<-\EOF &&
+	found: early-lastarg at 0
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at short options' '
+	test-tool early-scan-options -s --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at low-level callbacks' '
+	test-tool early-scan-options --low-level --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --ll-value x --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops after what the callback consumed' '
+	test-tool early-scan-options --stop-at-found --wanted --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0
+	stopped at: 1 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-found \
+		--wanted-value x --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: x
+	stopped at: 2 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() reports negated options' '
+	test-tool early-scan-options --no-wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0 unset
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --early >actual &&
+	cat >expect <<-\EOF &&
+	found: no-early at 0 unset
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --no-early >actual &&
+	cat >expect <<-\EOF &&
+	found: no-early at 0
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() does not take a value for negated options' '
+	test-tool early-scan-options --no-wanted-value --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 unset
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --no-wanted-value=x --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
 test_done
-- 
2.56.0.116.g6de20f6092
Kaartic Sivaraam· Oct 30, 2026, 21:27 UTC · re: Christian Couder · lore

Re: [PATCH v3 3/4] parse-options: add early_scan_options()

On 10/12/26 13:14, Christian Couder wrote:
Show 22 quoted lines
> diff --git a/parse-options.c b/parse-options.c
> index a98b958423..c03c396aa6 100644
> --- a/parse-options.c
> +++ b/parse-options.c
> @@ -726,6 +726,8 @@ static void parse_options_check(const struct option *opts)
>   		     opts->long_name))
>   			optbug(opts, "uses feature "
>   			       "not supported for dashless options");
> +		if ((opts->flags & PARSE_OPT_EARLY) && !opts->long_name)
> +			optbug(opts, "uses PARSE_OPT_EARLY, which needs a long name");
>   		if (opts->type == OPTION_SET_INT && !opts->defval &&
>   		    opts->long_name && !(opts->flags & PARSE_OPT_NONEG))
>   			optbug(opts, "OPTION_SET_INT 0 should not be negatable");
> @@ -763,6 +765,8 @@ static void parse_options_check(const struct option *opts)
>   		case OPTION_SUBCOMMAND:
>   			if (!opts->value || !opts->subcommand_fn)
>   				optbug(opts, "OPTION_SUBCOMMAND needs a value and a subcommand function");
> +			if (opts->flags & PARSE_OPT_EARLY)
> +				optbug(opts, "OPTION_SUBCOMMAND does not support PARSE_OPT_EARLY");
>   			if (!subcommand_value)
>   				subcommand_value = opts->value;
>   			else if (subcommand_value != opts->value)
Would it make sense to also have these validations within early_scan_options() just in case it is called before parse_options_start() is invoked?
  > diff --git a/parse-options.h b/parse-options.h
Show 32 quoted lines
> index 589f8d9008..f39b9a779a 100644
> --- a/parse-options.h
> +++ b/parse-options.h
> @@ -51,6 +51,7 @@ enum parse_opt_option_flags {
>   	PARSE_OPT_NODASH = 1 << 5,
>   	PARSE_OPT_LITERAL_ARGHELP = 1 << 6,
>   	PARSE_OPT_FROM_ALIAS = 1 << 7,
> +	PARSE_OPT_EARLY = 1 << 8,	/* only for early_scan_options() */
>   	PARSE_OPT_NOCOMPLETE = 1 << 9,
>   	PARSE_OPT_COMP_ARG = 1 << 10,
>   	PARSE_OPT_CMDMODE = 1 << 11,
> @@ -502,6 +503,96 @@ static inline void die_for_incompatible_opt2(int opt1, const char *opt1_name,
>   		BUG("option callback expects an argument"); \
>   } while(0)
>   > +/*----- Early scan: scanning argv before the actual option parsing -----*/
> +
> +/*
> + * Some commands need to look at a few options before they can parse
> + * their command line for real, for example because the result decides
> + * whether a repository is needed at all.
> + *
> + * Such an early scan has to know which options take their value as a
> + * separate argument, or it could mistake such a value for an
> + * option. The functions below allow performing such early scans
> + * without being fooled by option values.
> + */
> +
> +/*
> + * Called by early_scan_options() for each argument matching a
> + * `struct option` with PARSE_OPT_EARLY set.
> + *
> + * - `option` is the matching option,
Would it be helpful to also convey here that the caller is not expected to retain the pointer as the memory pointing to it would be freed once the scan completes?
Rest of the patch looks fine to me.
-- 
Sivaraam
Christian Couder· Nov 2, 2026, 15:25 UTC · re: Kaartic Sivaraam · lore

Re: [PATCH v3 3/4] parse-options: add early_scan_options()

On Fri, Oct 30, 2026 at 10:27 PM Kaartic Sivaraam <kaartic.sivaraam@gmail.com> wrote:

>
> On 10/12/26 13:14, Christian Couder wrote:
Show 13 quoted lines
> > @@ -763,6 +765,8 @@ static void parse_options_check(const struct option *opts)
> >               case OPTION_SUBCOMMAND:
> >                       if (!opts->value || !opts->subcommand_fn)
> >                               optbug(opts, "OPTION_SUBCOMMAND needs a value and a subcommand function");
> > +                     if (opts->flags & PARSE_OPT_EARLY)
> > +                             optbug(opts, "OPTION_SUBCOMMAND does not support PARSE_OPT_EARLY");
> >                       if (!subcommand_value)
> >                               subcommand_value = opts->value;
> >                       else if (subcommand_value != opts->value)
>
> Would it make sense to also have these validations within
> early_scan_options() just in case it is called before
> parse_options_start() is invoked?

Yeah, I think it's cheap and simple enough to just call parse_options_check() from early_scan_options(), so I have added that call in the v4 I just sent.

Show 9 quoted lines
> > +/*
> > + * Called by early_scan_options() for each argument matching a
> > + * `struct option` with PARSE_OPT_EARLY set.
> > + *
> > + * - `option` is the matching option,
>
> Would it be helpful to also convey here that the caller is not expected
> to retain the pointer as the memory pointing to it would be freed once
> the scan completes?
Yeah, it looks like this in v4:
 * - `option` is the matching option, (may point into a temporary
 *   copy of the options, so must not be used after the scan,)
Thanks.
Christian Couder· Oct 12, 2026, 07:44 UTC · re: Christian Couder · lore

[PATCH v3 4/4] fast-import: use early_scan_options() for --allow-unsafe-features

The "feature" lines at the start of the stream are processed before the command line options are parsed, so cmd_fast_import() scans its arguments early to find out if `--allow-unsafe-features` was given.

That scan doesn't know which options take their value as a separate argument, and it stops at the first argument that doesn't start with a dash. So it disagrees with parse_options(), which accepts values separated from their option by a space, for a command line like "--depth 5 --allow-unsafe-features": the scan stops at "5" and never sees the option, so unsafe "feature" commands from the stream are refused even though the option was given.

Let's fix this by using early_scan_options(), which scans the very same `struct option` array that parse_options() uses, so that both agree on which options take a value, and by marking `--allow-unsafe-features` with PARSE_OPT_EARLY so that the scan reports it.

As early_scan_options() looks up long options the same way as parse_options(), the two also agree on abbreviations now. So `--allow-unsafe` allows unsafe "feature" commands, while "--quiet --export-pack --allow-unsafe-features" refuses them, as parse_options() takes `--allow-unsafe-features` there as the value of `--export-pack-edges`. (The old scan wrongly allowed them in this case, as all the arguments start with a dash.)

The note about having to spell the option in full in the documentation is therefore removed, and so is the NEEDSWORK comment about it.

Helped-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 Documentation/git-fast-import.adoc |  7 ------
 builtin/fast-import.c              | 37 ++++++++++++++++--------------
 t/t9300-fast-import.sh             | 29 +++++++++++++++++++++++
 3 files changed, 49 insertions(+), 24 deletions(-)
Show changes to 3 files +49 −24

Documentation/git-fast-import.adoc, builtin/fast-import.c, t/t9300-fast-import.sh

diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc
index fd165e11d2..7c5900e048 100644
--- a/Documentation/git-fast-import.adoc
+++ b/Documentation/git-fast-import.adoc
@@ -65,13 +65,6 @@ Only enable this option if you trust the program generating the
 fast-import stream! This option is enabled automatically for
 remote-helpers that use the `import` capability, as they are
 already trusted to run their own code.
-+
-Note that this option has to be spelled in full, and has to appear
-before any option whose value is separated from it by a space, for
-the unsafe `feature` commands in the stream to be allowed. So
-`--allow-unsafe` or `--depth 5 --allow-unsafe-features` still refuse
-them, while `--allow-unsafe-features --depth 5` and
-`--depth=5 --allow-unsafe-features` allow them.
 
 `--signed-tags=<mode>`::
 	Specify how to handle signed tags. Behaves in the same way as
diff --git a/builtin/fast-import.c b/builtin/fast-import.c
index fbd919982c..2e667af349 100644
--- a/builtin/fast-import.c
+++ b/builtin/fast-import.c
@@ -4120,6 +4120,18 @@ static int option_parse_quiet(const struct option *opt UNUSED,
 	return 0;
 }
 
+static int option_parse_early_allow_unsafe(const struct option *option,
+					   const char *value UNUSED,
+					   bool unset, int pos UNUSED,
+					   void *data)
+{
+	struct fast_import_state *state = data;
+
+	if (!strcmp(option->long_name, "allow-unsafe-features"))
+		state->allow_unsafe_features = !unset;
+	return 0;
+}
+
 int cmd_fast_import(int argc,
 		    const char **argv,
 		    const char *prefix,
@@ -4184,7 +4196,7 @@ int cmd_fast_import(int argc,
 		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),
+			   PARSE_OPT_HIDDEN | PARSE_OPT_NONEG | PARSE_OPT_EARLY),
 		OPT_CALLBACK_F(0, "export-pack-edges", &state, N_("file"),
 			       N_("dump edge commits to <file>"),
 			       PARSE_OPT_HIDDEN | PARSE_OPT_NONEG,
@@ -4218,23 +4230,14 @@ int cmd_fast_import(int argc,
 	 * line to override stream data). But we must do an early parse of any
 	 * command-line options that impact how we interpret the feature lines.
 	 *
-	 * NEEDSWORK: This scan only matches the exact "--allow-unsafe-features"
-	 * spelling and stops at the first argument that doesn't start with a
-	 * dash. As parse_options() below also accepts unambiguous abbreviations
-	 * and values separated by a space from their option, the two disagree
-	 * for command lines like "--allow-unsafe" or "--depth 5
-	 * --allow-unsafe-features": parse_options() accepts the option, but
-	 * this scan doesn't see it, so unsafe features from the stream are
-	 * still refused. This errs on the safe side, but should be fixed by
-	 * teaching this scan about the options that take a value.
+	 * The scan uses the same options as parse_options() below, so the
+	 * two agree on which options take a value and on abbreviations. In
+	 * case of doubt, the scan stops early, so unsafe features are then
+	 * refused rather than wrongly allowed.
 	 */
-	for (int i = 1; i < argc; i++) {
-		const char *arg = argv[i];
-		if (*arg != '-' || !strcmp(arg, "--"))
-			break;
-		if (!strcmp(arg, "--allow-unsafe-features"))
-			state.allow_unsafe_features = 1;
-	}
+	early_scan_options(argc - 1, argv + 1, fast_import_options,
+			   EARLY_SCAN_STOP_AT_NON_OPTION,
+			   option_parse_early_allow_unsafe, &state);
 
 	rc_free = mem_pool_alloc(&fi_mem_pool, cmd_save * sizeof(*rc_free));
 	for (unsigned int i = 0; i < (cmd_save - 1); i++)
diff --git a/t/t9300-fast-import.sh b/t/t9300-fast-import.sh
index d9de2ef0d8..85059a5385 100755
--- a/t/t9300-fast-import.sh
+++ b/t/t9300-fast-import.sh
@@ -2344,6 +2344,35 @@ test_expect_success 'R: export-marks options can be overridden by commandline op
 	test_path_is_missing feature-sub
 '
 
+test_expect_success 'R: --allow-unsafe-features found after a value' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	git fast-import --allow-unsafe-features <input &&
+	git fast-import --depth=5 --allow-unsafe-features <input &&
+	git fast-import --depth 5 --allow-unsafe-features <input &&
+	git fast-import --date-format raw --allow-unsafe-features <input
+'
+
+test_expect_success 'R: --allow-unsafe-features can be abbreviated' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+	git fast-import --allow-unsafe <input
+'
+
+test_expect_success 'R: disallowed abbreviation of --allow-unsafe-features' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	test_must_fail env GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=true \
+		git fast-import --allow-unsafe <input 2>err &&
+	test_grep "forbidden in input without --allow-unsafe-features" err
+'
+
+test_expect_success 'R: --allow-unsafe-features as the value of an abbreviation' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	test_must_fail env GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+		git fast-import --quiet --export-pack \
+		--allow-unsafe-features <input 2>err &&
+	test_grep "forbidden in input without --allow-unsafe-features" err
+'
+
 test_expect_success 'R: catch typo in marks file name' '
 	test_must_fail git fast-import --import-marks=nonexistent.marks </dev/null &&
 	echo "feature import-marks=nonexistent.marks" |
-- 
2.56.0.116.g6de20f6092
Cynthia Uche· Oct 31, 2026, 14:22 UTC · re: Christian Couder · lore

Re: [PATCH v3 4/4] fast-import: use early_scan_options() for --allow-unsafe-features

Hi Christian,

I read through the series and ran t0040 and t9300 on the cc/early-scan-options topic, as in origin/seen (tip dabb68a20d). All 118 tests in t0040 pass, including the new early-scan tests, and all 261 tests in t9300 pass, including the new R: tests.

Show 8 quoted lines
> +	 * The scan uses the same options as parse_options() below, so the
> +	 * two agree on which options take a value and on abbreviations. In
> +	 * case of doubt, the scan stops early, so unsafe features are then
> +	 * refused rather than wrongly allowed.
> +	 */
> +	early_scan_options(argc - 1, argv + 1, fast_import_options,
> +			   EARLY_SCAN_STOP_AT_NON_OPTION,
> +			   option_parse_early_allow_unsafe, &state);

The call passes EARLY_SCAN_STOP_AT_NON_OPTION, but the 3/4 header says to pass it when parse_options() is called with PARSE_OPT_STOP_AT_NON_OPTION or with subcommands. That is not the case here: parse_argv() calls parse_options() with only PARSE_OPT_KEEP_ARGV0, and the table has no subcommands. Stopping at the first non-option is the safe direction, and it matches the old loop, which also broke at the first argument not starting with a dash. But the comment only says the scan stops early "in case of doubt", and does not mention this flag.

With an input file containing "feature import-marks-if-exists=nonexistent.marks", I tried:

  ./git fast-import --depth 5 --allow-unsafe-features <input
which succeeds (exit=0), and
  ./git fast-import --depth 5 extra --allow-unsafe-features <input

which dies with "forbidden in input without --allow-unsafe-features" (exit=128). The stray "extra" would make parse_options() fail with a usage error, but that only happens after the stream's feature lines have been processed.

To see what the flag changes, I replaced EARLY_SCAN_STOP_AT_NON_OPTION with 0 locally and ran the second command again. It then failed with the usage error (exit=129) instead, so the scan had gone past "extra", seen --allow-unsafe-features, and the unsafe feature line was accepted before parse_options() rejected the command line.

I would suggest adding a sentence to the comment saying that the scan stops at the first non-option through EARLY_SCAN_STOP_AT_NON_OPTION, even though parse_options() is not called with PARSE_OPT_STOP_AT_NON_OPTION, so that readers know why the flag is passed.

I did not find other issues in this patch :)

Thanks, Cynthia

Christian Couder· Nov 2, 2026, 15:36 UTC · re: Cynthia Uche · lore

Re: [PATCH v3 4/4] fast-import: use early_scan_options() for --allow-unsafe-features

Hi Cynthia,

On Sat, Oct 31, 2026 at 3:25 PM Cynthia Uche <herroyalpriestess@gmail.com> wrote:

Show 20 quoted lines
>
> Hi Christian,
>
> I read through the series and ran t0040 and t9300 on the
> cc/early-scan-options topic, as in origin/seen (tip dabb68a20d).
> All 118 tests in t0040 pass, including the new early-scan tests, and
> all 261 tests in t9300 pass, including the new R: tests.
>
> > +      * The scan uses the same options as parse_options() below, so the
> > +      * two agree on which options take a value and on abbreviations. In
> > +      * case of doubt, the scan stops early, so unsafe features are then
> > +      * refused rather than wrongly allowed.
> > +      */
> > +     early_scan_options(argc - 1, argv + 1, fast_import_options,
> > +                        EARLY_SCAN_STOP_AT_NON_OPTION,
> > +                        option_parse_early_allow_unsafe, &state);
>
> The call passes EARLY_SCAN_STOP_AT_NON_OPTION, but the 3/4 header says
> to pass it when parse_options() is called with
> PARSE_OPT_STOP_AT_NON_OPTION or with subcommands.

Yeah, the end of that header comment wasn't as helpful as it could have been. I have reworked and improved it. In the v4 I just sent, it looks like this:

 * This requires the scan to be told about the way the later
 * parse_options() call treats its arguments though:
 *
 *  - when parse_options() is called with PARSE_OPT_STOP_AT_NON_OPTION
 *    or with subcommands, callers should pass
 *    EARLY_SCAN_STOP_AT_NON_OPTION,
 *
 *  - when parse_options() is called with PARSE_OPT_KEEP_UNKNOWN_OPT,
 *    which disables abbreviations there but not here, callers should
 *    not use the scan.
 *
 * Passing EARLY_SCAN_STOP_AT_NON_OPTION in other cases is safe, and
 * useful when the caller rejects non-option arguments itself."
 */
Show 32 quoted lines
> That is not the case
> here: parse_argv() calls parse_options() with only PARSE_OPT_KEEP_ARGV0,
> and the table has no subcommands. Stopping at the first non-option is
> the safe direction, and it matches the old loop, which also broke at
> the first argument not starting with a dash. But the comment only says
> the scan stops early "in case of doubt", and does not mention this flag.
>
> With an input file containing
> "feature import-marks-if-exists=nonexistent.marks", I tried:
>
>   ./git fast-import --depth 5 --allow-unsafe-features <input
>
> which succeeds (exit=0), and
>
>   ./git fast-import --depth 5 extra --allow-unsafe-features <input
>
> which dies with "forbidden in input without --allow-unsafe-features"
> (exit=128). The stray "extra" would make parse_options() fail with a
> usage error, but that only happens after the stream's feature lines
> have been processed.
>
> To see what the flag changes, I replaced EARLY_SCAN_STOP_AT_NON_OPTION
> with 0 locally and ran the second command again. It then failed with
> the usage error (exit=129) instead, so the scan had gone past "extra",
> seen --allow-unsafe-features, and the unsafe feature line was accepted
> before parse_options() rejected the command line.
>
> I would suggest adding a sentence to the comment saying that the scan
> stops at the first non-option through EARLY_SCAN_STOP_AT_NON_OPTION,
> even though parse_options() is not called with
> PARSE_OPT_STOP_AT_NON_OPTION, so that readers know why the flag is
> passed.
Right, in v4, I have improved the comment to explain why we pass the flag:
/*
* We don't parse most options until after we've seen the set of
* "feature" lines at the start of the stream (which allows the command
* line to override stream data). But we must do an early parse of any
* command-line options that impact how we interpret the feature lines.
*
* The scan uses the same options as parse_options() below, so the
* two agree on which options take a value and on abbreviations. In
* case of doubt, the scan stops early, so unsafe features are then
* refused rather than wrongly allowed.
*
* EARLY_SCAN_STOP_AT_NON_OPTION is passed even though parse_options()
* is not called with PARSE_OPT_STOP_AT_NON_OPTION, as any non-option
* argument makes parse_argv() reject the command line, and the stream
* should not have been processed with unsafe features by then.
*/

I also added a small test for `git fast-import --depth 5 extra --allow-unsafe-features` as it looks like an interesting thing to test.

> I did not find other issues in this patch :)
Thank you for your suggestions and your review.
Kaartic Sivaraam· Oct 30, 2026, 21:33 UTC · re: Christian Couder · lore

Re: [PATCH v3 0/4] Standardize early option scanning

On 10/12/26 13:14, Christian Couder wrote:
Show 30 quoted lines
> > Changes since v2
> ================
> > Thanks a lot to Junio and Kaartic who reviewed previous versions.
> > Rebased on top of a018953688 (Git 2.56, 2026-09-27) to start from a
> stable base.
> > There are a number of important changes since v2:
> >   - In patch 1/4, parse_options_takes_argument() now considers
>     PARSE_OPT_LASTARG_DEFAULT options as taking a value. This allows us
>     to remove a limitation that was in v2 as these options now consume
>     the next argument when there is one, like in parse_options().
> >   - Patch 2/4 is new, see above.
> >   - In patch 3/4, we reuse the new lookup_long_opt() function extracted
>     by patch 2/4. This removes a number of limitations (around negated
>     forms, unambiguous abbreviations and aliases) that were in v2, as
>     the early scan now behaves in a similar way as parse_options()
>     regarding long options. A number of tests have been added to ensure
>     that.
> >   - In patch 3/4, the scan now stops at short options, unknown options,
>     ambiguous or disallowed abbreviations, options with a low-level
>     callback, and value-taking options given as the last argument,
>     instead of skipping over them, as it could otherwise take an
>     option's value for an option.
> >   - In patch 3/4, early_scan_fn() has a new `unset` argument for
>     negated options, and early_scan_options() now returns the index of
>     the first argument not consumed also when the callback stops the
>     scan.
> >   - In patch 4/4, the commit message and documentation are updated to
>     account for the better behavior of the early scan. A related
>     NEEDSWORK comment is also removed, and some tests added.
>
The v3 seems to be in a much better state to me. Just left a few minor comments.
Thank you for working on this!
-- 
Sivaraam
Christian Couder· Nov 2, 2026, 15:14 UTC · re: Christian Couder · lore

[PATCH v4 0/4] Standardize early option scanning

A number of commands perform an early scan of their arguments to look for specific flags or structural separators (like `--`).

These hand-rolled early scans are often fragile. They especially fail to account for options that take their value as a separate argument. This leads to disagreements between the early scan and the actual parse_options() pass. For example, the early scanner might miss a special option entirely, or mistakenly treat an option's value as the `--` path separator.

To allow these commands to safely skip option values during their early scans, this series introduces a new "early-scan" sub-API into the existing "parse-options" API.

This is deliberately implemented as a new simple and fast scan. A full 'dry run' of parse_options() would have to avoid writing through `opt->value`, calling callbacks or dying. Instead, the scan reuses only the long option lookup of parse_options(), and stops when unsure.

This allows negated options ("--no-..."), unambiguous abbreviated options and aliases to be properly handled. The early scan also agrees with parse_options() on which options take a value, including those with PARSE_OPT_OPTARG or PARSE_OPT_LASTARG_DEFAULT.

To never misinterpret an option's value as an option though, it stops at any argument it cannot reliably skip:

 1. a short option, or a bundle of them,
 2. an unknown option, or an ambiguous or disallowed abbreviation,
 3. an option with a low-level callback, as such a callback may
 consume any number of arguments,
 4. an option with a missing or stuck value that parse_options() would
 reject, like "--no-<name>=<value>".

So the scan may fail to see an option that parse_options() would accept, but it doesn't report an option that parse_options() would not, and callers can safely err on the side of not having seen it.

This holds as long as the scan is told how the later parse_options() call treats its arguments: EARLY_SCAN_STOP_AT_NON_OPTION should be passed when parse_options() stops at non-options or has subcommands, and the scan should not be used with PARSE_OPT_KEEP_UNKNOWN_OPT, which disables abbreviations in parse_options() only.

The early scan is performed by a new early_scan_options() function which takes a regular `const struct option *option` array as argument.

This requires that the command already uses `struct option` and the parse-options API to parse its arguments. As the majority of commands performing an early scan don't use the parse-options API yet, they will have to be converted to use it before they can use early_scan_options().

In this series, only `git fast-import` is converted to the early-scan API. Its hand-rolled scan disagreed with parse_options() in both directions:

  - `git fast-import --depth 5 --allow-unsafe-features` silently
    ignored `--allow-unsafe-features`, refusing unsafe features from
    the stream, and so did `--allow-unsafe`, its abbreviation,
  - `git fast-import --quiet --export-pack --allow-unsafe-features`
    and `git fast-import --end-of-options --allow-unsafe-features`
    allowed unsafe features from the stream, while parse_options()
    takes `--allow-unsafe-features` as the value of
    `--export-pack-edges` in the first case, and as a non-option
    argument in the second one.
All these cases now agree with parse_options().

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

 - Patch 1/4 refactors some existing code into a new
   parse_options_takes_argument() helper that will be used in patch
   3/4.
 - Patch 2/4 extracts the long option lookup code from
   parse_long_opt() into a new lookup_long_opt() function, so that the
   function can be reused in the next patch.
 - Patch 3/4 introduces early_scan_options(), the early scanner that
   will be used instead of hand-rolled ones, along with the
   PARSE_OPT_EARLY flag and tests.
 - Patch 4/4 uses early_scan_options() to fix the early scan for
   `--allow-unsafe-features` in `git fast-import`.

Changes since v3 ================

Thanks a lot to Junio, Kaartic and Cynthia who reviewed previous versions.

There are a number of small changes since v3:
 - In patch 2/4, a `switch` statement is now used in parse_long_opt()
   to process the result from lookup_long_opt().
 - In patch 3/4, a parse_options_check() call has been added to
   early_scan_options(), after aliases are preprocessed, so that the
   options are checked before the scan relies on them, rather than
   only later by parse_options().
 - In patch 3/4, in "parse-options.h":
   - the comment before early_scan_fn() has been improved to mention
     that the `option` argument may point into a temporary copy of the
     options, and
   - the end of the comment before early_scan_options() has been made
     clearer and now mentions that EARLY_SCAN_STOP_AT_NON_OPTION is
     safe to use even if PARSE_OPT_STOP_AT_NON_OPTION is not passed to
     parse_options().
 - In patch 4/4:
   - the comment before the call to early_scan_options() in
     cmd_fast_import() has been improved to explain why
     EARLY_SCAN_STOP_AT_NON_OPTION is passed,
   - a new test has been added to check that unsafe "feature" commands
     from the stream are refused when `--allow-unsafe-features` comes
     after a non-option argument, which parse_argv() rejects anyway.

CI tests: =========

Some failed, see:
https://github.com/chriscool/git/actions/runs/41450228024

but the failures in t5550 and t5540 on ubuntu:rolling and alpine:latest are unrelated. They come from recent curl stripping credentials from CURLINFO_EFFECTIVE_URL, and are fixed on master by jk/http-curl-strip-creds.

Patches =======

Christian Couder (4):
  parse-options: add parse_options_takes_argument()
  parse-options: extract lookup_long_opt() from parse_long_opt()
  parse-options: add early_scan_options()
  fast-import: use early_scan_options() for --allow-unsafe-features

Diffstat ========

 Documentation/git-fast-import.adoc            |   7 -
 .../technical/api-parse-options.adoc          |   5 +
 builtin/fast-import.c                         |  42 ++-
 parse-options.c                               | 291 +++++++++++++---
 parse-options.h                               | 109 ++++++
 t/helper/test-parse-options.c                 |  96 ++++++
 t/helper/test-tool.c                          |   1 +
 t/helper/test-tool.h                          |   1 +
 t/t0040-parse-options.sh                      | 321 ++++++++++++++++++
 t/t9300-fast-import.sh                        |  36 ++
 10 files changed, 844 insertions(+), 65 deletions(-)

Range-diff since v3 ===================

1:  57c48ab0fe = 1:  57c48ab0fe parse-options: add parse_options_takes_argument()
2:  38243ce8bf ! 2:  1c001e577e parse-options: extract lookup_long_opt() from parse_long_opt()
    @@ Commit message
         when disallowed only if there is no exact match, and the ambiguity
         error message is unchanged.
     
    +    Helped-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
         Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
      ## parse-options.c ##
    @@ parse-options.c: static enum parse_opt_result parse_long_opt(
      	}
      
     -	if (disallow_abbreviated_options && (ambiguous.option || abbrev.option))
    +-		die("disallowed abbreviated or ambiguous option '%.*s'",
    +-		    (int)(arg_end - arg), arg);
    +-
    +-	if (ambiguous.option) {
    +-		error(_("ambiguous option: %s "
    +-			"(could be --%s%s or --%s%s)"),
    +-			arg,
    +-			(ambiguous.flags & OPT_UNSET) ?  "no-" : "",
    +-			ambiguous.option->long_name,
    +-			(abbrev.flags & OPT_UNSET) ?  "no-" : "",
    +-			abbrev.option->long_name);
    +-		return PARSE_OPT_HELP_ERROR;
    +-	}
    +-	if (abbrev.option) {
     +	if (other->option)
     +		return LONG_OPT_AMBIGUOUS;
     +
     +	if (found->option) {
    -+		if (*arg_end)
    + 		if (*arg_end)
    +-			p->opt = arg_end + 1;
    +-		return get_value(p, abbrev.option, abbrev.flags);
     +			*stuck = arg_end + 1;
     +		return LONG_OPT_ABBREV;
    -+	}
    + 	}
    +-	return PARSE_OPT_UNKNOWN;
     +
     +	return LONG_OPT_UNKNOWN;
     +}
    @@ parse-options.c: static enum parse_opt_result parse_long_opt(
     +	enum long_opt_lookup result = lookup_long_opt(p, arg, options,
     +						      &found, &other, &stuck);
     +
    -+	if (result == LONG_OPT_UNKNOWN)
    ++	switch (result) {
    ++	case LONG_OPT_UNKNOWN:
     +		return PARSE_OPT_UNKNOWN;
    -+
    -+	if (disallow_abbreviated_options &&
    -+	    (result == LONG_OPT_ABBREV || result == LONG_OPT_AMBIGUOUS)) {
    -+		const char *arg_end = strchrnul(arg, '=');
    - 		die("disallowed abbreviated or ambiguous option '%.*s'",
    - 		    (int)(arg_end - arg), arg);
    -+	}
    - 
    --	if (ambiguous.option) {
    --		error(_("ambiguous option: %s "
    --			"(could be --%s%s or --%s%s)"),
    --			arg,
    --			(ambiguous.flags & OPT_UNSET) ?  "no-" : "",
    --			ambiguous.option->long_name,
    --			(abbrev.flags & OPT_UNSET) ?  "no-" : "",
    --			abbrev.option->long_name);
    -+	if (result == LONG_OPT_AMBIGUOUS) {
    -+		error(_("ambiguous option: %s (could be --%s%s or --%s%s)"), arg,
    -+		      (other.flags & OPT_UNSET) ? "no-" : "", other.option->long_name,
    -+		      (found.flags & OPT_UNSET) ? "no-" : "", found.option->long_name);
    - 		return PARSE_OPT_HELP_ERROR;
    - 	}
    --	if (abbrev.option) {
    --		if (*arg_end)
    --			p->opt = arg_end + 1;
    --		return get_value(p, abbrev.option, abbrev.flags);
    -+
    -+	if (result == LONG_OPT_ABBREV || result == LONG_OPT_EXACT) {
    ++	case LONG_OPT_ABBREV:
    ++	case LONG_OPT_AMBIGUOUS:
    ++		if (disallow_abbreviated_options) {
    ++			const char *arg_end = strchrnul(arg, '=');
    ++			die("disallowed abbreviated or ambiguous option '%.*s'",
    ++			    (int)(arg_end - arg), arg);
    ++		}
    ++		if (result == LONG_OPT_AMBIGUOUS) {
    ++			error(_("ambiguous option: %s "
    ++				"(could be --%s%s or --%s%s)"),
    ++			      arg,
    ++			      (other.flags & OPT_UNSET) ? "no-" : "",
    ++			      other.option->long_name,
    ++			      (found.flags & OPT_UNSET) ? "no-" : "",
    ++			      found.option->long_name);
    ++			return PARSE_OPT_HELP_ERROR;
    ++		}
    ++		/* fallthru */
    ++	case LONG_OPT_EXACT:
     +		p->opt = stuck;
     +		return get_value(p, found.option, found.flags);
    - 	}
    --	return PARSE_OPT_UNKNOWN;
    ++	}
     +
     +	BUG("unknown enum long_opt_lookup value '%d'", result);
      }
3:  c36cae4e44 ! 3:  9e2d7fc5d6 parse-options: add early_scan_options()
    @@ parse-options.c: int parse_options(int argc, const char **argv,
     +	int i;
     +
     +	s.option = real_option ? real_option : option;
    ++	parse_options_check(s.option);
     +
     +	for (i = 0; i < argc; i++)
     +		if (!early_scan_one_option(&s, argc, argv, &i))
    @@ parse-options.h: static inline void die_for_incompatible_opt2(int opt1, const ch
     + * Called by early_scan_options() for each argument matching a
     + * `struct option` with PARSE_OPT_EARLY set.
     + *
    -+ * - `option` is the matching option,
    ++ * - `option` is the matching option, (may point into a temporary
    ++ *   copy of the options, so must not be used after the scan,)
     + * - `value` its value, or NULL if it doesn't take one or if its value
     + *   is optional and wasn't given, as with PARSE_OPT_OPTARG, or with
     + *   PARSE_OPT_LASTARG_DEFAULT when the option is the last argument,
    @@ parse-options.h: static inline void die_for_incompatible_opt2(int opt1, const ch
     + * parse_options() would not, so that callers err on the safe side.
     + *
     + * This requires the scan to be told about the way the later
    -+ * parse_options() call treats its arguments though: callers should
    -+ * pass EARLY_SCAN_STOP_AT_NON_OPTION when parse_options() is called
    -+ * with PARSE_OPT_STOP_AT_NON_OPTION or with subcommands, and should
    -+ * not use the scan when parse_options() is called with
    -+ * PARSE_OPT_KEEP_UNKNOWN_OPT, which disables abbreviations there but
    -+ * not here.
    ++ * parse_options() call treats its arguments though:
    ++ *
    ++ *  - when parse_options() is called with PARSE_OPT_STOP_AT_NON_OPTION
    ++ *    or with subcommands, callers should pass
    ++ *    EARLY_SCAN_STOP_AT_NON_OPTION,
    ++ *
    ++ *  - when parse_options() is called with PARSE_OPT_KEEP_UNKNOWN_OPT,
    ++ *    which disables abbreviations there but not here, callers should
    ++ *    not use the scan.
    ++ *
    ++ * Passing EARLY_SCAN_STOP_AT_NON_OPTION in other cases is safe, and
    ++ * useful when the caller rejects non-option arguments itself.
     + */
     +int early_scan_options(int argc, const char **argv,
     +		       const struct option *option,
4:  515f13df83 ! 4:  ceeb21e89e fast-import: use early_scan_options() for --allow-unsafe-features
    @@ Commit message
         about it.
     
         Helped-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
    +    Helped-by: Cynthia Uche <herroyalpriestess@gmail.com>
         Signed-off-by: Christian Couder <christian.couder@gmail.com>
     
      ## Documentation/git-fast-import.adoc ##
    @@ builtin/fast-import.c: int cmd_fast_import(int argc,
     +	 * two agree on which options take a value and on abbreviations. In
     +	 * case of doubt, the scan stops early, so unsafe features are then
     +	 * refused rather than wrongly allowed.
    ++	 *
    ++	 * EARLY_SCAN_STOP_AT_NON_OPTION is passed even though parse_options()
    ++	 * is not called with PARSE_OPT_STOP_AT_NON_OPTION, as any non-option
    ++	 * argument makes parse_argv() reject the command line, and the stream
    ++	 * should not have been processed with unsafe features by then.
      	 */
     -	for (int i = 1; i < argc; i++) {
     -		const char *arg = argv[i];
    @@ t/t9300-fast-import.sh: test_expect_success 'R: export-marks options can be over
     +		--allow-unsafe-features <input 2>err &&
     +	test_grep "forbidden in input without --allow-unsafe-features" err
     +'
    ++
    ++test_expect_success 'R: --allow-unsafe-features after a non-option' '
    ++	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
    ++	test_must_fail git fast-import --depth 5 extra \
    ++		--allow-unsafe-features <input 2>err &&
    ++	test_grep "forbidden in input without --allow-unsafe-features" err
    ++'
     +
      test_expect_success 'R: catch typo in marks file name' '
      	test_must_fail git fast-import --import-marks=nonexistent.marks </dev/null &&
base-commit: a018953688f1b10bddf91bff8747068f5f4746a4
-- 
2.56.0.4.gceeb21e89e
Christian Couder· Nov 2, 2026, 15:14 UTC · re: Christian Couder · lore

[PATCH v4 1/4] parse-options: add parse_options_takes_argument()

Whether an option takes a value, and therefore consumes the next argument when that value is not stuck to it with an '=', is decided by its type and its flags. That rule is currently open-coded in show_gitcomp(), which needs it to decide if it should append an '=' to the option it completes.

A following commit will need the same rule to find out which options an early scan of the command line has to skip along with their value.

So let's factor that rule out into a new parse_options_takes_argument() function, and let's use it in show_gitcomp().

Note that an option with PARSE_OPT_LASTARG_DEFAULT only consumes the next argument when it isn't the last one. It is considered as taking a value by parse_options_takes_argument(), as an early scan can easily check whether there is a next argument, and would otherwise wrongly take that argument for an option. show_gitcomp() keeps not appending an '=' to such an option though, as it already did, since its value is optional.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 parse-options.c | 35 ++++++++++++++++++++++-------------
 parse-options.h | 11 +++++++++++
 2 files changed, 33 insertions(+), 13 deletions(-)
Show changes to 2 files +33 −13

parse-options.c, parse-options.h

diff --git a/parse-options.c b/parse-options.c
index 4519ead9dc..d7cbb5a343 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -841,6 +841,25 @@ static void show_negated_gitcomp(const struct option *opts, int show_all,
 	}
 }
 
+int parse_options_takes_argument(const struct option *opt)
+{
+	switch (opt->type) {
+	case OPTION_STRING:
+	case OPTION_FILENAME:
+	case OPTION_INTEGER:
+	case OPTION_UNSIGNED:
+	case OPTION_CALLBACK:
+		break;
+	default:
+		return 0;
+	}
+
+	if (opt->flags & (PARSE_OPT_NOARG | PARSE_OPT_OPTARG))
+		return 0;
+
+	return 1;
+}
+
 static int show_gitcomp(const struct option *opts, int show_all)
 {
 	const struct option *original_opts = opts;
@@ -862,20 +881,10 @@ static int show_gitcomp(const struct option *opts, int show_all)
 			break;
 		case OPTION_GROUP:
 			continue;
-		case OPTION_STRING:
-		case OPTION_FILENAME:
-		case OPTION_INTEGER:
-		case OPTION_UNSIGNED:
-		case OPTION_CALLBACK:
-			if (opts->flags & PARSE_OPT_NOARG)
-				break;
-			if (opts->flags & PARSE_OPT_OPTARG)
-				break;
-			if (opts->flags & PARSE_OPT_LASTARG_DEFAULT)
-				break;
-			suffix = "=";
-			break;
 		default:
+			if (parse_options_takes_argument(opts) &&
+			    !(opts->flags & PARSE_OPT_LASTARG_DEFAULT))
+				suffix = "=";
 			break;
 		}
 		if (opts->flags & PARSE_OPT_COMP_ARG)
diff --git a/parse-options.h b/parse-options.h
index d7f896a933..589f8d9008 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -420,6 +420,17 @@ int parse_options(int argc, const char **argv, const char *prefix,
 		  const char * const usagestr[],
 		  enum parse_opt_flags flags);
 
+/*
+ * Return non-zero if `opt` takes a value, which means that it consumes
+ * the next argument when that value is not stuck to it with an '='.
+ *
+ * Note that an option with PARSE_OPT_LASTARG_DEFAULT is considered as
+ * taking a value here, even though it only consumes the next argument
+ * when it isn't the last one. Callers that care have to check for that
+ * flag themselves.
+ */
+int parse_options_takes_argument(const struct option *opt);
+
 NORETURN void usage_with_options(const char * const *usagestr,
 				 const struct option *options);
 
-- 
2.56.0.4.gceeb21e89e
Christian Couder· Nov 2, 2026, 15:14 UTC · re: Christian Couder · lore

[PATCH v4 2/4] parse-options: extract lookup_long_opt() from parse_long_opt()

In a following commit, an early scan of the command line will need to look up long options the same way parse_options() does, including unambiguous abbreviations and negated forms, but without any side effect: it must neither set option values nor call die() or error().

parse_long_opt() can't be used for that, as it does both the look up and the actions that follow it: it calls get_value() on the option it finds, die()s when abbreviations are disallowed, and error()s on an ambiguous abbreviation.

Let's extract a new lookup_long_opt() helper from parse_long_opt() to perform only the look up part, and let parse_long_opt() act on what lookup_long_opt() returns.

There is no behavior change intended. In particular an exact match is still preferred to any abbreviation, abbreviations are still rejected when disallowed only if there is no exact match, and the ambiguity error message is unchanged.

Helped-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 parse-options.c | 117 ++++++++++++++++++++++++++++++++++++------------
 1 file changed, 89 insertions(+), 28 deletions(-)
Show changes to parse-options.c +89 −28
diff --git a/parse-options.c b/parse-options.c
index d7cbb5a343..d94d6fed93 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -516,16 +516,46 @@ static void register_abbrev(struct parse_opt_ctx_t *p,
 	abbrev->flags = flags;
 }
 
-static enum parse_opt_result parse_long_opt(
-	struct parse_opt_ctx_t *p, const char *arg,
-	const struct option *options)
+enum long_opt_lookup {
+	LONG_OPT_EXACT,      /* exact match found */
+	LONG_OPT_ABBREV,     /* unambiguous abbreviation found */
+	LONG_OPT_AMBIGUOUS,  /* more than one candidate abbreviation */
+	LONG_OPT_UNKNOWN,    /* nothing matches */
+};
+
+/*
+ * Look up the long option named by `arg` (without its leading "--")
+ * without acting on it. (Neither prints nor dies.)
+ *
+ * Return value:
+ * - On LONG_OPT_EXACT, `found` is the exact matching option and its flags
+ *   (including OPT_UNSET for a negated form), and `stuck` points after
+ *   the '=' or is NULL.
+ * - On LONG_OPT_ABBREV, `found` is the unambiguous abbreviation, same as
+ *   above for its flags and `stuck`.
+ * - On LONG_OPT_AMBIGUOUS, `found` and `other` are two candidates of an
+ *   ambiguous abbreviation.
+ * - On LONG_OPT_UNKNOWN, nothing matches, no result.
+ *
+ * `other` is only meaningful for LONG_OPT_AMBIGUOUS.
+ */
+static enum long_opt_lookup lookup_long_opt(struct parse_opt_ctx_t *p,
+					    const char *arg,
+					    const struct option *options,
+					    struct parsed_option *found,
+					    struct parsed_option *other,
+					    const char **stuck)
 {
+	enum opt_parsed flags = OPT_LONG;
 	const char *arg_end = strchrnul(arg, '=');
 	const char *arg_start = arg;
-	enum opt_parsed flags = OPT_LONG;
 	int arg_starts_with_no_no = 0;
-	struct parsed_option abbrev = { .option = NULL, .flags = OPT_LONG };
-	struct parsed_option ambiguous = { .option = NULL, .flags = OPT_LONG };
+
+	found->option = NULL;
+	found->flags = OPT_LONG;
+	other->option = NULL;
+	other->flags = OPT_LONG;
+	*stuck = NULL;
 
 	if (skip_prefix(arg_start, "no-", &arg_start)) {
 		if (skip_prefix(arg_start, "no-", &arg_start))
@@ -554,43 +584,74 @@ static enum parse_opt_result parse_long_opt(
 
 		if (skip_prefix(arg_start, long_name, &rest)) {
 			if (*rest == '=')
-				p->opt = rest + 1;
+				*stuck = rest + 1;
 			else if (*rest)
 				continue;
-			return get_value(p, options, flags ^ opt_flags);
+			found->option = options;
+			found->flags = flags ^ opt_flags;
+			return LONG_OPT_EXACT;
 		}
 
 		/* abbreviated? */
 		if (!strncmp(long_name, arg_start, arg_end - arg_start))
 			register_abbrev(p, options, flags ^ opt_flags,
-					&abbrev, &ambiguous);
+					found, other);
 
 		/* negated and abbreviated very much? */
 		if (allow_unset && starts_with("no-", arg))
 			register_abbrev(p, options, OPT_UNSET ^ opt_flags,
-					&abbrev, &ambiguous);
+					found, other);
 	}
 
-	if (disallow_abbreviated_options && (ambiguous.option || abbrev.option))
-		die("disallowed abbreviated or ambiguous option '%.*s'",
-		    (int)(arg_end - arg), arg);
-
-	if (ambiguous.option) {
-		error(_("ambiguous option: %s "
-			"(could be --%s%s or --%s%s)"),
-			arg,
-			(ambiguous.flags & OPT_UNSET) ?  "no-" : "",
-			ambiguous.option->long_name,
-			(abbrev.flags & OPT_UNSET) ?  "no-" : "",
-			abbrev.option->long_name);
-		return PARSE_OPT_HELP_ERROR;
-	}
-	if (abbrev.option) {
+	if (other->option)
+		return LONG_OPT_AMBIGUOUS;
+
+	if (found->option) {
 		if (*arg_end)
-			p->opt = arg_end + 1;
-		return get_value(p, abbrev.option, abbrev.flags);
+			*stuck = arg_end + 1;
+		return LONG_OPT_ABBREV;
 	}
-	return PARSE_OPT_UNKNOWN;
+
+	return LONG_OPT_UNKNOWN;
+}
+
+static enum parse_opt_result parse_long_opt(struct parse_opt_ctx_t *p,
+					    const char *arg,
+					    const struct option *options)
+{
+	struct parsed_option found;
+	struct parsed_option other;
+	const char *stuck;
+	enum long_opt_lookup result = lookup_long_opt(p, arg, options,
+						      &found, &other, &stuck);
+
+	switch (result) {
+	case LONG_OPT_UNKNOWN:
+		return PARSE_OPT_UNKNOWN;
+	case LONG_OPT_ABBREV:
+	case LONG_OPT_AMBIGUOUS:
+		if (disallow_abbreviated_options) {
+			const char *arg_end = strchrnul(arg, '=');
+			die("disallowed abbreviated or ambiguous option '%.*s'",
+			    (int)(arg_end - arg), arg);
+		}
+		if (result == LONG_OPT_AMBIGUOUS) {
+			error(_("ambiguous option: %s "
+				"(could be --%s%s or --%s%s)"),
+			      arg,
+			      (other.flags & OPT_UNSET) ? "no-" : "",
+			      other.option->long_name,
+			      (found.flags & OPT_UNSET) ? "no-" : "",
+			      found.option->long_name);
+			return PARSE_OPT_HELP_ERROR;
+		}
+		/* fallthru */
+	case LONG_OPT_EXACT:
+		p->opt = stuck;
+		return get_value(p, found.option, found.flags);
+	}
+
+	BUG("unknown enum long_opt_lookup value '%d'", result);
 }
 
 static enum parse_opt_result parse_nodash_opt(struct parse_opt_ctx_t *p,
-- 
2.56.0.4.gceeb21e89e
Christian Couder· Nov 2, 2026, 15:14 UTC · re: Christian Couder · lore

[PATCH v4 3/4] parse-options: add early_scan_options()

Some commands need to look at a few of their options before they can parse their command line for real, for example because the result decides whether a repository is needed at all, or how the beginning of their input should be interpreted.

Such an early scan has to know which options take their value as a separate argument, or it mistakes such a value for an option. Several commands get this wrong, as they just walk their arguments comparing them to the few option names they care about.

Let's add early_scan_options() to help with this. It walks the arguments using the very same `struct option` array that the command already passes to parse_options(). It looks up long options with the lookup_long_opt() helper extracted from parse_long_opt() in a previous commit, so that negated forms, unambiguous abbreviations and aliases are recognized the same way, and it uses the parse_options_takes_argument() helper added in another previous commit, so that the scan and the actual parsing agree on which options take a value.

The options the caller wants to be told about are marked with a new PARSE_OPT_EARLY flag, so that nothing has to be spelled out a second time, and so that the mark cannot drift away from the option it refers to.

Using a per-option flag for this is not new as that flag space already holds flags that the parsing loop itself ignores, like PARSE_OPT_NOCOMPLETE and PARSE_OPT_COMP_ARG, which only the completion helper looks at, or PARSE_OPT_HIDDEN and PARSE_OPT_LITERAL_ARGHELP, which only the usage output looks at.

The scan is deliberately kept much simpler than parse_options(), instead of teaching the latter to perform a side effect free "dry run". Such a dry run would have to avoid writing through `opt->value`, calling option callbacks, dying on an invalid value, handling `--help` and tracking command mode conflicts, so it would be a much larger refactoring. If parse_options() learns to do it in the future though, the commands converted now would keep both their option array and their PARSE_OPT_EARLY marks, so their conversion would not have to be redone.

One consequence of staying simple is that the scan doesn't try to handle what it cannot reliably skip, like short options, unknown options, ambiguous abbreviations or options with a low-level callback, which may consume any number of arguments. It stops at them instead, so that it never takes an option's value for an option. This matters, as for example with:

  git fast-import --quiet --export-pack --allow-unsafe-features

parse_options() takes `--allow-unsafe-features` as the value of `--export-pack-edges`, which `--export-pack` abbreviates. A scan that just skipped `--export-pack` as an unknown option would wrongly see `--allow-unsafe-features` there.

So the scan can fail to see an option that parse_options() would accept, but it doesn't report an option that parse_options() would not, and its callers can safely err on the side of not having seen an option. The differences with parse_options() are documented in "parse-options.h".

In practice, despite these limitations, early scans using early_scan_options() should still be safer and cleaner than the ad-hoc hand-rolled scans they are meant to replace, which don't know about option values at all and therefore disagree with parse_options() in ways that create plain bugs.

Helped-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 .../technical/api-parse-options.adoc          |   5 +
 parse-options.c                               | 139 ++++++++
 parse-options.h                               |  98 ++++++
 t/helper/test-parse-options.c                 |  96 ++++++
 t/helper/test-tool.c                          |   1 +
 t/helper/test-tool.h                          |   1 +
 t/t0040-parse-options.sh                      | 321 ++++++++++++++++++
 7 files changed, 661 insertions(+)
Show changes to 7 files +661 −0

Documentation/technical/api-parse-options.adoc, parse-options.c, parse-options.h, t/helper/test-parse-options.c, t/helper/test-tool.c, t/helper/test-tool.h, t/t0040-parse-options.sh

diff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc
index 95b7924e84..f59d8e90a5 100644
--- a/Documentation/technical/api-parse-options.adoc
+++ b/Documentation/technical/api-parse-options.adoc
@@ -197,6 +197,11 @@ are the bitwise-or of:
 	Internal flag, set on options that were expanded from a
 	configured alias. It should not be set by callers.
 
+`PARSE_OPT_EARLY`::
+	Report this option to `early_scan_options()`, which looks at a
+	few options before parsing the command line for real. Ignored
+	by `parse_options()` itself.
+
 `PARSE_OPT_NOCOMPLETE`::
 	Do not offer this option for completion.
 
diff --git a/parse-options.c b/parse-options.c
index d94d6fed93..7e8b406129 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -730,6 +730,8 @@ static void parse_options_check(const struct option *opts)
 		     opts->long_name))
 			optbug(opts, "uses feature "
 			       "not supported for dashless options");
+		if ((opts->flags & PARSE_OPT_EARLY) && !opts->long_name)
+			optbug(opts, "uses PARSE_OPT_EARLY, which needs a long name");
 		if (opts->type == OPTION_SET_INT && !opts->defval &&
 		    opts->long_name && !(opts->flags & PARSE_OPT_NONEG))
 			optbug(opts, "OPTION_SET_INT 0 should not be negatable");
@@ -767,6 +769,8 @@ static void parse_options_check(const struct option *opts)
 		case OPTION_SUBCOMMAND:
 			if (!opts->value || !opts->subcommand_fn)
 				optbug(opts, "OPTION_SUBCOMMAND needs a value and a subcommand function");
+			if (opts->flags & PARSE_OPT_EARLY)
+				optbug(opts, "OPTION_SUBCOMMAND does not support PARSE_OPT_EARLY");
 			if (!subcommand_value)
 				subcommand_value = opts->value;
 			else if (subcommand_value != opts->value)
@@ -1314,6 +1318,141 @@ int parse_options(int argc, const char **argv,
 	return parse_options_end(&ctx);
 }
 
+/*
+ * Look for `name`, a long option without its leading "--", among
+ * `option`, the way parse_options() would. Return true if it names an
+ * option exactly, or as an unambiguous abbreviation that is not
+ * disallowed, with `found` set to that option and its flags, and
+ * `stuck` to the value stuck to it, if any, or to NULL.
+ */
+static bool find_early_scan_option(struct parse_opt_ctx_t *p,
+				   const char *name,
+				   const struct option *option,
+				   bool disallow_abbrev,
+				   struct parsed_option *found,
+				   const char **stuck)
+{
+	struct parsed_option other;
+	enum long_opt_lookup result = lookup_long_opt(p, name, option,
+						      found, &other, stuck);
+
+	switch (result) {
+	case LONG_OPT_EXACT:
+		return true;
+	case LONG_OPT_ABBREV:
+		return !disallow_abbrev;
+	case LONG_OPT_AMBIGUOUS:
+	case LONG_OPT_UNKNOWN:
+		return false;
+	}
+
+	BUG("unknown enum long_opt_lookup value '%d'", result);
+}
+
+struct early_scan_state {
+	struct parse_opt_ctx_t ctx;
+	const struct option *option;
+	enum early_scan_flags flags;
+	early_scan_fn *fn;
+	void *data;
+	bool disallow_abbrev;
+};
+
+/*
+ * Look at argv[*i]. Return 'true' to go on scanning, with *i on the
+ * last argument consumed. Return 'false' to stop, with *i set to the
+ * first argument not consumed.
+ */
+static bool early_scan_one_option(struct early_scan_state *s,
+				  int argc, const char **argv, int *i)
+{
+	const char *name;
+	const char *value;
+	struct parsed_option found;
+	bool unset;
+	int pos = *i;
+	const char *arg = argv[pos];
+
+	/*
+	 * parse_options() always stops parsing options at these,
+	 * whatever its flags, so nothing after them is an option.
+	 */
+	if (!strcmp(arg, "--") || !strcmp(arg, "--end-of-options"))
+		return false;
+
+	/* non-option */
+	if (*arg != '-' || !arg[1])
+		return !(s->flags & EARLY_SCAN_STOP_AT_NON_OPTION);
+
+	/* short option */
+	if (!skip_prefix(arg, "--", &name))
+		return false;
+
+	/* unknown, ambiguous or disallowed abbreviation */
+	if (!find_early_scan_option(&s->ctx, name, s->option,
+				    s->disallow_abbrev, &found, &value))
+		return false;
+
+	/* A low-level callback may consume any number of arguments. */
+	if (found.option->ll_callback)
+		return false;
+
+	unset = !!(found.flags & OPT_UNSET);
+
+	/* parse_options() rejects these, so don't go further. */
+	if (value && (unset || (found.option->flags & PARSE_OPT_NOARG)))
+		return false;
+
+	/*
+	 * Like get_arg(), take the next argument as the value when it is
+	 * not stuck to the option. When there is no next argument,
+	 * parse_options() uses the default value of an option with
+	 * PARSE_OPT_LASTARG_DEFAULT, but errors out for other options.
+	 */
+	if (!value && !unset && parse_options_takes_argument(found.option)) {
+		if (pos + 1 < argc)
+			value = argv[++*i];
+		else if (!(found.option->flags & PARSE_OPT_LASTARG_DEFAULT))
+			return false;
+	}
+
+	if ((found.option->flags & PARSE_OPT_EARLY) &&
+	    s->fn(found.option, value, unset, pos, s->data)) {
+		/* the option, and its value if any, have been consumed */
+		++*i;
+		return false;
+	}
+
+	return true;
+}
+
+int early_scan_options(int argc, const char **argv,
+		       const struct option *option,
+		       enum early_scan_flags flags,
+		       early_scan_fn *fn, void *data)
+{
+	struct early_scan_state s = {
+		.flags = flags,
+		.fn = fn,
+		.data = data,
+		.disallow_abbrev =
+			git_env_bool("GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS", 0),
+	};
+	struct option *real_option = preprocess_options(&s.ctx, option);
+	int i;
+
+	s.option = real_option ? real_option : option;
+	parse_options_check(s.option);
+
+	for (i = 0; i < argc; i++)
+		if (!early_scan_one_option(&s, argc, argv, &i))
+			break;
+
+	free_preprocessed_options(real_option);
+	free(s.ctx.alias_groups);
+	return i;
+}
+
 static int usage_argh(const struct option *opts, FILE *outfile)
 {
 	const char *s;
diff --git a/parse-options.h b/parse-options.h
index 589f8d9008..14e8568989 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -51,6 +51,7 @@ enum parse_opt_option_flags {
 	PARSE_OPT_NODASH = 1 << 5,
 	PARSE_OPT_LITERAL_ARGHELP = 1 << 6,
 	PARSE_OPT_FROM_ALIAS = 1 << 7,
+	PARSE_OPT_EARLY = 1 << 8,	/* only for early_scan_options() */
 	PARSE_OPT_NOCOMPLETE = 1 << 9,
 	PARSE_OPT_COMP_ARG = 1 << 10,
 	PARSE_OPT_CMDMODE = 1 << 11,
@@ -502,6 +503,103 @@ static inline void die_for_incompatible_opt2(int opt1, const char *opt1_name,
 		BUG("option callback expects an argument"); \
 } while(0)
 
+/*----- Early scan: scanning argv before the actual option parsing -----*/
+
+/*
+ * Some commands need to look at a few options before they can parse
+ * their command line for real, for example because the result decides
+ * whether a repository is needed at all.
+ *
+ * Such an early scan has to know which options take their value as a
+ * separate argument, or it could mistake such a value for an
+ * option. The functions below allow performing such early scans
+ * without being fooled by option values.
+ */
+
+/*
+ * Called by early_scan_options() for each argument matching a
+ * `struct option` with PARSE_OPT_EARLY set.
+ *
+ * - `option` is the matching option, (may point into a temporary
+ *   copy of the options, so must not be used after the scan,)
+ * - `value` its value, or NULL if it doesn't take one or if its value
+ *   is optional and wasn't given, as with PARSE_OPT_OPTARG, or with
+ *   PARSE_OPT_LASTARG_DEFAULT when the option is the last argument,
+ * - `unset` is 'true' for the negated form of the option (like
+ *   for parse_opt_cb()), in which case `value` is always NULL, and
+ * - `pos` the index of the option in argv.
+ *
+ * Returning a non-zero value stops the scan right after the option and
+ * its value, if any.
+ */
+typedef int early_scan_fn(const struct option *option, const char *value,
+			  bool unset, int pos, void *data);
+
+enum early_scan_flags {
+	EARLY_SCAN_STOP_AT_NON_OPTION = 1 << 0, /* Stop at any non option */
+};
+
+/*
+ * Scan `argv` for the options described by `option`, calling `fn` for
+ * each of those that have PARSE_OPT_EARLY set. `argv` is not
+ * modified.
+ *
+ * `fn` may be NULL when no option has PARSE_OPT_EARLY set, which is
+ * useful to only find out where the scan stops.
+ *
+ * The scan always stops at "--" and at "--end-of-options", as
+ * parse_options() always stops parsing options there too, whatever its
+ * flags. PARSE_OPT_KEEP_DASHDASH and PARSE_OPT_KEEP_UNKNOWN_OPT only
+ * decide if the terminator is left in argv, not if it terminates.
+ *
+ * Returns the index of the first argument not consumed by the scan,
+ * which is `argc` when the whole array was scanned.
+ *
+ * Long options are looked up the same way as parse_options() does,
+ * so their negated forms, their unambiguous abbreviations, unless
+ * GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS is set, and the OPTION_ALIAS
+ * entries standing for them are all recognized, and their value is
+ * skipped when they take one.
+ *
+ * To never misinterpret an option value as an option though, the scan
+ * stops at any argument it cannot reliably skip, that is:
+ *
+ *  - a short option, or a bundle of them,
+ *
+ *  - an unknown option, or an ambiguous or disallowed abbreviation,
+ *
+ *  - an option with a low-level callback, as such a callback may
+ *    consume any number of arguments,
+ *
+ *  - an option with a value stuck to it that parse_options() would
+ *    reject, like a negated option or a PARSE_OPT_NOARG one,
+ *
+ *  - an option requiring a value when it is the last argument, which
+ *    parse_options() would also reject.
+ *
+ * In all these cases, the scan can fail to see an option that
+ * parse_options() would accept, but it doesn't report an option that
+ * parse_options() would not, so that callers err on the safe side.
+ *
+ * This requires the scan to be told about the way the later
+ * parse_options() call treats its arguments though:
+ *
+ *  - when parse_options() is called with PARSE_OPT_STOP_AT_NON_OPTION
+ *    or with subcommands, callers should pass
+ *    EARLY_SCAN_STOP_AT_NON_OPTION,
+ *
+ *  - when parse_options() is called with PARSE_OPT_KEEP_UNKNOWN_OPT,
+ *    which disables abbreviations there but not here, callers should
+ *    not use the scan.
+ *
+ * Passing EARLY_SCAN_STOP_AT_NON_OPTION in other cases is safe, and
+ * useful when the caller rejects non-option arguments itself.
+ */
+int early_scan_options(int argc, const char **argv,
+		       const struct option *option,
+		       enum early_scan_flags flags,
+		       early_scan_fn *fn, void *data);
+
 /*----- incremental advanced APIs -----*/
 
 struct parse_opt_cmdmode_list;
diff --git a/t/helper/test-parse-options.c b/t/helper/test-parse-options.c
index f181f0c02d..de3dd5751c 100644
--- a/t/helper/test-parse-options.c
+++ b/t/helper/test-parse-options.c
@@ -383,3 +383,99 @@ int cmd__parse_subcommand(int argc, const char **argv)
 
 	return parse_subcommand__cmd(argc, argv, test_flags);
 }
+
+static enum parse_opt_result early_ll_callback(struct parse_opt_ctx_t *ctx UNUSED,
+					       const struct option *opt UNUSED,
+					       const char *arg UNUSED,
+					       int unset UNUSED)
+{
+	return 0;
+}
+
+static int show_early_option(const struct option *opt, const char *value,
+			     bool unset, int pos, void *data)
+{
+	int *stop_at_found = data;
+
+	printf("found: %s at %d", opt->long_name, pos);
+	if (unset)
+		printf(" unset");
+	if (value)
+		printf(" value: %s", value);
+	putchar('\n');
+	return *stop_at_found;
+}
+
+int cmd__early_scan_options(int argc, const char **argv)
+{
+	char *a_string = NULL;
+	int an_int = 0, a_bool = 0, a_short = 0;
+
+	const struct option option[] = {
+		OPT_GROUP("early scan test options"),
+		OPT_BOOL_F(0, "wanted", &a_bool,
+			   "wanted option taking no value",
+			   PARSE_OPT_EARLY),
+		OPT_STRING_F(0, "wanted-value", &a_string, "str",
+			     "wanted option taking a value",
+			     PARSE_OPT_EARLY),
+		OPT_STRING(0, "skipped-value", &a_string, "str",
+			   "option whose value has to be skipped"),
+		OPT_ALIAS(0, "alias-of-skipped", "skipped-value"),
+		OPT_INTEGER(0, "number", &an_int,
+			    "option taking an integer value"),
+		OPT_STRING_F(0, "optarg", &a_string, "str",
+			     "option with an optional value",
+			     PARSE_OPT_OPTARG),
+		OPT_STRING_F(0, "lastarg", &a_string, "str",
+			     "option with a last argument default",
+			     PARSE_OPT_LASTARG_DEFAULT),
+		OPT_STRING_F(0, "early-optarg", &a_string, "str",
+			     "early option with an optional value",
+			     PARSE_OPT_EARLY | PARSE_OPT_OPTARG),
+		OPT_STRING_F(0, "early-lastarg", &a_string, "str",
+			     "early option with a last argument default",
+			     PARSE_OPT_EARLY | PARSE_OPT_LASTARG_DEFAULT),
+		OPT_BOOL_F(0, "no-early", &a_bool,
+			   "early option whose name starts with 'no-'",
+			   PARSE_OPT_EARLY),
+		OPT_BOOL('s', NULL, &a_short, "short only option"),
+		{
+			.type = OPTION_LOWLEVEL_CALLBACK,
+			.long_name = "low-level",
+			.help = "option with a low-level callback",
+			.flags = PARSE_OPT_NOARG | PARSE_OPT_NONEG,
+			.ll_callback = early_ll_callback,
+		},
+		{
+			.type = OPTION_CALLBACK,
+			.long_name = "ll-value",
+			.argh = "str",
+			.help = "option with a value and a low-level callback",
+			.flags = PARSE_OPT_NONEG,
+			.ll_callback = early_ll_callback,
+		},
+		OPT_END()
+	};
+
+	enum early_scan_flags flags = 0;
+	int stop_at_found = 0;
+	int stopped;
+
+	while (argc > 1 && *argv[1] == '-') {
+		if (!strcmp(argv[1], "--stop-at-non-option"))
+			flags |= EARLY_SCAN_STOP_AT_NON_OPTION;
+		else if (!strcmp(argv[1], "--stop-at-found"))
+			stop_at_found = 1;
+		else
+			break;
+		argc--;
+		argv++;
+	}
+
+	stopped = early_scan_options(argc - 1, argv + 1, option, flags,
+				     show_early_option, &stop_at_found);
+	printf("stopped at: %d of %d\n", stopped, argc - 1);
+
+	return 0;
+}
diff --git a/t/helper/test-tool.c b/t/helper/test-tool.c
index b71a22b43b..5d2f5877d9 100644
--- a/t/helper/test-tool.c
+++ b/t/helper/test-tool.c
@@ -50,6 +50,7 @@ static struct test_cmd cmds[] = {
 	{ "pack-mtimes", cmd__pack_mtimes },
 	{ "parse-options", cmd__parse_options },
 	{ "parse-options-flags", cmd__parse_options_flags },
+	{ "early-scan-options", cmd__early_scan_options },
 	{ "parse-pathspec-file", cmd__parse_pathspec_file },
 	{ "parse-subcommand", cmd__parse_subcommand },
 	{ "partial-clone", cmd__partial_clone },
diff --git a/t/helper/test-tool.h b/t/helper/test-tool.h
index f2885b33d5..071306d52d 100644
--- a/t/helper/test-tool.h
+++ b/t/helper/test-tool.h
@@ -43,6 +43,7 @@ int cmd__pack_deltas(int argc, const char **argv);
 int cmd__pack_mtimes(int argc, const char **argv);
 int cmd__parse_options(int argc, const char **argv);
 int cmd__parse_options_flags(int argc, const char **argv);
+int cmd__early_scan_options(int argc, const char **argv);
 int cmd__parse_pathspec_file(int argc, const char** argv);
 int cmd__parse_subcommand(int argc, const char **argv);
 int cmd__partial_clone(int argc, const char **argv);
diff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh
index 449fff4d34..c44b12e46d 100755
--- a/t/t0040-parse-options.sh
+++ b/t/t0040-parse-options.sh
@@ -845,4 +845,325 @@ test_expect_success 'u16 limits range' '
 	test_grep "value 65536 for option .u16. not in range \[0,65535\]" err
 '
 
+test_expect_success 'early_scan_options() finds a wanted option' '
+	test-tool early-scan-options --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() reads a stuck or separate value' '
+	test-tool early-scan-options --wanted-value=one >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: one
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --wanted-value two >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: two
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() skips the value of other options' '
+	test-tool early-scan-options --skipped-value --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --skipped-value one --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --number --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at a last option missing its value' '
+	test-tool early-scan-options --wanted-value >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --wanted --skipped-value >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0
+	stopped at: 1 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() always stops at "--"' '
+	test-tool early-scan-options -- --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-non-option -- --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --skipped-value -- --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() always stops at "--end-of-options"' '
+	test-tool early-scan-options --end-of-options --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-non-option \
+		--end-of-options --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() can stop at a non-option' '
+	test-tool early-scan-options --stop-at-non-option \
+		arg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-non-option \
+		--skipped-value arg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() matches unambiguous abbreviations' '
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+	test-tool early-scan-options --wanted-v=x >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: x
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+	test-tool early-scan-options --wanted-v x --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: x
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() skips the value of an abbreviation' '
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+	test-tool early-scan-options --skipped --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at an ambiguous abbreviation' '
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+	test-tool early-scan-options --want --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at disallowed abbreviations' '
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=true \
+	test-tool early-scan-options --wanted-v=x >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 1
+	EOF
+	test_cmp expect actual &&
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=true \
+	test-tool early-scan-options --skipped --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at an unknown option' '
+	test-tool early-scan-options --bogus --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() resolves aliases' '
+	test-tool early-scan-options --alias-of-skipped --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --alias-of-skipped x --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 2
+	stopped at: 3 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() does not skip an optional value' '
+	test-tool early-scan-options --optarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --optarg=5 --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() skips a last argument default value' '
+	test-tool early-scan-options --lastarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --wanted --lastarg >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() matches a stuck optional value' '
+	test-tool early-scan-options --early-optarg=one >actual &&
+	cat >expect <<-\EOF &&
+	found: early-optarg at 0 value: one
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --early-lastarg=two >actual &&
+	cat >expect <<-\EOF &&
+	found: early-lastarg at 0 value: two
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() does not take a separate optional value' '
+	test-tool early-scan-options --early-optarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: early-optarg at 0
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() takes a last argument default value' '
+	test-tool early-scan-options --early-lastarg --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: early-lastarg at 0 value: --wanted
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --early-lastarg >actual &&
+	cat >expect <<-\EOF &&
+	found: early-lastarg at 0
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at short options' '
+	test-tool early-scan-options -s --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops at low-level callbacks' '
+	test-tool early-scan-options --low-level --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --ll-value x --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() stops after what the callback consumed' '
+	test-tool early-scan-options --stop-at-found --wanted --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0
+	stopped at: 1 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --stop-at-found \
+		--wanted-value x --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 value: x
+	stopped at: 2 of 3
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() reports negated options' '
+	test-tool early-scan-options --no-wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted at 0 unset
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --early >actual &&
+	cat >expect <<-\EOF &&
+	found: no-early at 0 unset
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --no-early >actual &&
+	cat >expect <<-\EOF &&
+	found: no-early at 0
+	stopped at: 1 of 1
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'early_scan_options() does not take a value for negated options' '
+	test-tool early-scan-options --no-wanted-value --wanted >actual &&
+	cat >expect <<-\EOF &&
+	found: wanted-value at 0 unset
+	found: wanted at 1
+	stopped at: 2 of 2
+	EOF
+	test_cmp expect actual &&
+	test-tool early-scan-options --no-wanted-value=x --wanted >actual &&
+	cat >expect <<-\EOF &&
+	stopped at: 0 of 2
+	EOF
+	test_cmp expect actual
+'
+
 test_done
-- 
2.56.0.4.gceeb21e89e
Christian Couder· Nov 2, 2026, 15:14 UTC · re: Christian Couder · lore

[PATCH v4 4/4] fast-import: use early_scan_options() for --allow-unsafe-features

The "feature" lines at the start of the stream are processed before the command line options are parsed, so cmd_fast_import() scans its arguments early to find out if `--allow-unsafe-features` was given.

That scan doesn't know which options take their value as a separate argument, and it stops at the first argument that doesn't start with a dash. So it disagrees with parse_options(), which accepts values separated from their option by a space, for a command line like "--depth 5 --allow-unsafe-features": the scan stops at "5" and never sees the option, so unsafe "feature" commands from the stream are refused even though the option was given.

Let's fix this by using early_scan_options(), which scans the very same `struct option` array that parse_options() uses, so that both agree on which options take a value, and by marking `--allow-unsafe-features` with PARSE_OPT_EARLY so that the scan reports it.

As early_scan_options() looks up long options the same way as parse_options(), the two also agree on abbreviations now. So `--allow-unsafe` allows unsafe "feature" commands, while "--quiet --export-pack --allow-unsafe-features" refuses them, as parse_options() takes `--allow-unsafe-features` there as the value of `--export-pack-edges`. (The old scan wrongly allowed them in this case, as all the arguments start with a dash.)

The note about having to spell the option in full in the documentation is therefore removed, and so is the NEEDSWORK comment about it.

Helped-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
Helped-by: Cynthia Uche <herroyalpriestess@gmail.com>
Signed-off-by: Christian Couder <christian.couder@gmail.com>
---
 Documentation/git-fast-import.adoc |  7 -----
 builtin/fast-import.c              | 42 ++++++++++++++++++------------
 t/t9300-fast-import.sh             | 36 +++++++++++++++++++++++++
 3 files changed, 61 insertions(+), 24 deletions(-)
Show changes to 3 files +61 −24

Documentation/git-fast-import.adoc, builtin/fast-import.c, t/t9300-fast-import.sh

diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc
index fd165e11d2..7c5900e048 100644
--- a/Documentation/git-fast-import.adoc
+++ b/Documentation/git-fast-import.adoc
@@ -65,13 +65,6 @@ Only enable this option if you trust the program generating the
 fast-import stream! This option is enabled automatically for
 remote-helpers that use the `import` capability, as they are
 already trusted to run their own code.
-+
-Note that this option has to be spelled in full, and has to appear
-before any option whose value is separated from it by a space, for
-the unsafe `feature` commands in the stream to be allowed. So
-`--allow-unsafe` or `--depth 5 --allow-unsafe-features` still refuse
-them, while `--allow-unsafe-features --depth 5` and
-`--depth=5 --allow-unsafe-features` allow them.
 
 `--signed-tags=<mode>`::
 	Specify how to handle signed tags. Behaves in the same way as
diff --git a/builtin/fast-import.c b/builtin/fast-import.c
index fbd919982c..863938bb27 100644
--- a/builtin/fast-import.c
+++ b/builtin/fast-import.c
@@ -4120,6 +4120,18 @@ static int option_parse_quiet(const struct option *opt UNUSED,
 	return 0;
 }
 
+static int option_parse_early_allow_unsafe(const struct option *option,
+					   const char *value UNUSED,
+					   bool unset, int pos UNUSED,
+					   void *data)
+{
+	struct fast_import_state *state = data;
+
+	if (!strcmp(option->long_name, "allow-unsafe-features"))
+		state->allow_unsafe_features = !unset;
+	return 0;
+}
+
 int cmd_fast_import(int argc,
 		    const char **argv,
 		    const char *prefix,
@@ -4184,7 +4196,7 @@ int cmd_fast_import(int argc,
 		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),
+			   PARSE_OPT_HIDDEN | PARSE_OPT_NONEG | PARSE_OPT_EARLY),
 		OPT_CALLBACK_F(0, "export-pack-edges", &state, N_("file"),
 			       N_("dump edge commits to <file>"),
 			       PARSE_OPT_HIDDEN | PARSE_OPT_NONEG,
@@ -4218,23 +4230,19 @@ int cmd_fast_import(int argc,
 	 * line to override stream data). But we must do an early parse of any
 	 * command-line options that impact how we interpret the feature lines.
 	 *
-	 * NEEDSWORK: This scan only matches the exact "--allow-unsafe-features"
-	 * spelling and stops at the first argument that doesn't start with a
-	 * dash. As parse_options() below also accepts unambiguous abbreviations
-	 * and values separated by a space from their option, the two disagree
-	 * for command lines like "--allow-unsafe" or "--depth 5
-	 * --allow-unsafe-features": parse_options() accepts the option, but
-	 * this scan doesn't see it, so unsafe features from the stream are
-	 * still refused. This errs on the safe side, but should be fixed by
-	 * teaching this scan about the options that take a value.
+	 * The scan uses the same options as parse_options() below, so the
+	 * two agree on which options take a value and on abbreviations. In
+	 * case of doubt, the scan stops early, so unsafe features are then
+	 * refused rather than wrongly allowed.
+	 *
+	 * EARLY_SCAN_STOP_AT_NON_OPTION is passed even though parse_options()
+	 * is not called with PARSE_OPT_STOP_AT_NON_OPTION, as any non-option
+	 * argument makes parse_argv() reject the command line, and the stream
+	 * should not have been processed with unsafe features by then.
 	 */
-	for (int i = 1; i < argc; i++) {
-		const char *arg = argv[i];
-		if (*arg != '-' || !strcmp(arg, "--"))
-			break;
-		if (!strcmp(arg, "--allow-unsafe-features"))
-			state.allow_unsafe_features = 1;
-	}
+	early_scan_options(argc - 1, argv + 1, fast_import_options,
+			   EARLY_SCAN_STOP_AT_NON_OPTION,
+			   option_parse_early_allow_unsafe, &state);
 
 	rc_free = mem_pool_alloc(&fi_mem_pool, cmd_save * sizeof(*rc_free));
 	for (unsigned int i = 0; i < (cmd_save - 1); i++)
diff --git a/t/t9300-fast-import.sh b/t/t9300-fast-import.sh
index d9de2ef0d8..9a5964c7ad 100755
--- a/t/t9300-fast-import.sh
+++ b/t/t9300-fast-import.sh
@@ -2344,6 +2344,42 @@ test_expect_success 'R: export-marks options can be overridden by commandline op
 	test_path_is_missing feature-sub
 '
 
+test_expect_success 'R: --allow-unsafe-features found after a value' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	git fast-import --allow-unsafe-features <input &&
+	git fast-import --depth=5 --allow-unsafe-features <input &&
+	git fast-import --depth 5 --allow-unsafe-features <input &&
+	git fast-import --date-format raw --allow-unsafe-features <input
+'
+
+test_expect_success 'R: --allow-unsafe-features can be abbreviated' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+	git fast-import --allow-unsafe <input
+'
+
+test_expect_success 'R: disallowed abbreviation of --allow-unsafe-features' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	test_must_fail env GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=true \
+		git fast-import --allow-unsafe <input 2>err &&
+	test_grep "forbidden in input without --allow-unsafe-features" err
+'
+
+test_expect_success 'R: --allow-unsafe-features as the value of an abbreviation' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	test_must_fail env GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=false \
+		git fast-import --quiet --export-pack \
+		--allow-unsafe-features <input 2>err &&
+	test_grep "forbidden in input without --allow-unsafe-features" err
+'
+
+test_expect_success 'R: --allow-unsafe-features after a non-option' '
+	echo "feature import-marks-if-exists=nonexistent.marks" >input &&
+	test_must_fail git fast-import --depth 5 extra \
+		--allow-unsafe-features <input 2>err &&
+	test_grep "forbidden in input without --allow-unsafe-features" err
+'
+
 test_expect_success 'R: catch typo in marks file name' '
 	test_must_fail git fast-import --import-marks=nonexistent.marks </dev/null &&
 	echo "feature import-marks=nonexistent.marks" |
-- 
2.56.0.4.gceeb21e89e
Kaartic Sivaraam· Nov 3, 2026, 07:54 UTC · re: Christian Couder · lore

Re: [PATCH v4 0/4] Standardize early option scanning

On 11/2/26 20:44, Christian Couder wrote:
Show 27 quoted lines
> Changes since v3
> ================
> > Thanks a lot to Junio, Kaartic and Cynthia who reviewed previous
> versions.
> > There are a number of small changes since v3:
> >   - In patch 2/4, a `switch` statement is now used in parse_long_opt()
>     to process the result from lookup_long_opt().
> >   - In patch 3/4, a parse_options_check() call has been added to
>     early_scan_options(), after aliases are preprocessed, so that the
>     options are checked before the scan relies on them, rather than
>     only later by parse_options().
> >   - In patch 3/4, in "parse-options.h":
> >     - the comment before early_scan_fn() has been improved to mention
>       that the `option` argument may point into a temporary copy of the
>       options, and
> >     - the end of the comment before early_scan_options() has been made
>       clearer and now mentions that EARLY_SCAN_STOP_AT_NON_OPTION is
>       safe to use even if PARSE_OPT_STOP_AT_NON_OPTION is not passed to
>       parse_options().
> >   - In patch 4/4:
> >     - the comment before the call to early_scan_options() in
>       cmd_fast_import() has been improved to explain why
>       EARLY_SCAN_STOP_AT_NON_OPTION is passed,
> >     - a new test has been added to check that unsafe "feature" commands
>       from the stream are refused when `--allow-unsafe-features` comes
>       after a non-option argument, which parse_argv() rejects anyway.
> Thanks! This version looks good to me!
-- 
Sivaraam
Junio C Hamano· Nov 3, 2026, 17:20 UTC · re: Kaartic Sivaraam · lore

Re: [PATCH v4 0/4] Standardize early option scanning

Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:
Show 11 quoted lines
> On 11/2/26 20:44, Christian Couder wrote:
>> Changes since v3
>> ================
>> 
>> Thanks a lot to Junio, Kaartic and Cynthia who reviewed previous
>> versions.
>> 
>> There are a number of small changes since v3:
>> ...
>
> Thanks! This version looks good to me!
Looking good.  Let me mark the topic for 'next'.  Thanks, all.

← back to recent threads