git/parse-options.h, branch v2.50.0

parse-options: detect mismatches in integer signedness

2025-04-17T15:15:16Z

It was reported that "t5620-backfill.sh" fails on s390x and sparc64 in a test that exercises the "--min-batch-size" command line option. The symptom was that the option didn't seem to have an effect: we didn't fetch objects with a batch size of 20, but instead fetched all objects at once. As it turns out, the root cause is that `--min-batch-size` uses `OPT_INTEGER()` to parse the command line option. While this macro expects the caller to pass a pointer to an integer, we instead pass a pointer to a `size_t`. This coincidentally works on most platforms, but it breaks apart on the mentioned platforms because they are big endian. This issue isn't specific to git-backfill(1): there are a couple of other places where we have the same type confusion going on. This indicates that the issue really is the interface that the parse-options subsystem provides -- it is simply too easy to get this wrong as there isn't any kind of compiler warning, and things just work on the most common systems. Address the systemic issue by introducing two new build asserts `BARF_UNLESS_SIGNED()` and `BARF_UNLESS_UNSIGNED()`. As the names already hint at, those macros will cause a compiler error when passed a value that is not signed or unsigned, respectively. Adapt `OPT_INTEGER()`, `OPT_UNSIGNED()` as well as `OPT_MAGNITUDE()` to use those asserts. This uncovers a small set of sites where we indeed have the same bug as in git-backfill(1). Adapt all of them to use the correct option. Reported-by: Todd Zullinger Reported-by: John Paul Adrian Glaubitz Helped-by: SZEDER Gábor Helped-by: Jeff King Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

parse-options: introduce precision handling for `OPTION_UNSIGNED`

2025-04-17T15:15:16Z

This commit is the equivalent to the preceding commit, but instead of introducing precision handling for `OPTION_INTEGER` we introduce it for `OPTION_UNSIGNED`. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

parse-options: introduce precision handling for `OPTION_INTEGER`

2025-04-17T15:15:15Z

The `OPTION_INTEGER` option type accepts a signed integer. The type of the underlying integer is a simple `int`, which restricts the range of values accepted by such options. But there is a catch: because the caller provides a pointer to the value via the `.value` field, which is a simple void pointer. This has two consequences: - There is no check whether the passed value is sufficiently long to store the entire range of `int`. This can lead to integer wraparound in the best case and out-of-bounds writes in the worst case. - Even when a caller knows that they want to store a value larger than `INT_MAX` they don't have a way to do so. In practice this doesn't tend to be a huge issue because users typically don't end up passing huge values to most commands. But the parsing logic is demonstrably broken, and it is too easy to get the calling convention wrong. Improve the situation by introducing a new `precision` field into the structure. This field gets assigned automatically by `OPT_INTEGER_F()` and tracks the size of the passed value. Like this it becomes possible for the caller to pass arbitrarily-sized integers and the underlying logic knows to handle it correctly by doing range checks. Furthermore, convert the code to use `strtoimax()` intstead of `strtol()` so that we can also parse values larger than `LONG_MAX`. Note that we do not yet assert signedness of the passed variable, which is another source of bugs. This will be handled in a subsequent commit. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

parse-options: rename `OPT_MAGNITUDE()` to `OPT_UNSIGNED()`

2025-04-17T15:15:15Z

With the preceding commit, `OPT_INTEGER()` has learned to support unit factors. Consequently, the major differencen between `OPT_INTEGER()` and `OPT_MAGNITUDE()` isn't the support of unit factors anymore, as both of them do support them now. Instead, the difference is that one handles signed and the other handles unsigned integers. Adapt the name of `OPT_MAGNITUDE()` accordingly by renaming it to `OPT_UNSIGNED()`. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

parse-options.h: .txt -> .adoc fixes

2025-03-03T21:49:24Z

Signed-off-by: Todd Zullinger Signed-off-by: Junio C Hamano

parse-options: introduce die_for_incompatible_opt2()

2025-02-06T20:23:54Z

The functions die_for_incompatible_opt3() and die_for_incompatible_opt4() already exist to die whenever a user specifies three or four options respectively that are not compatible. Introduce die_for_incompatible_opt2() which dies when two options that are incompatible are set. Signed-off-by: Toon Claes Signed-off-by: Junio C Hamano

parse-options: add show_usage_with_options_if_asked()

2025-01-17T21:30:02Z

Many commands call usage_with_options() when they are asked to give the help message, but it sends the help text to the standard error stream. When the user asked for it with "git cmd -h", the help message is the primary output from the command, hence we should send it to the standard output stream, instead. Introduce a helper function that captures the common pattern if (argc == 2 && !strcmp(argv[1], "-h")) usage_with_options(usage, options); and replaces it with show_usage_with_options_if_asked(argc, argv, usage, options); to help correct code paths. Note that this helper function still exits with status 129, and t0012 insists on it. After converting all the mistaken callers of usage_with_options() to call this new helper, we may want to address it---the end user is asking us to give the help text, and we are doing exactly as asked, so there is no reason to exit with non-zero status. Suggested-by: Jeff King Signed-off-by: Junio C Hamano

t: introduce compatibility options to clar-based tests

2024-12-13T14:48:47Z

Our unit tests that don't yet use the clar unit testing framework ignore any option that they do not understand. It is thus fine to just pass test options we set up globally to those unit tests as they are simply ignored. This makes our life easier because we don't have to special case those options with Meson, where test options are set up globally via `meson test --test-args=`. But our clar-based unit testing framework is way stricter here and will fail in case it is passed an unknown option. Stub out these options with no-ops to make our life a bit easier. Note that this also requires us to remove the `-x` short option for `--exclude`. This is because `-x` has another meaning in our integration tests, as it enables shell tracing. I doubt there are a lot of people out there using it as we only got a small hand full of clar tests in the first place. So better change it now so that we can in the long run improve compatibility between the two different test drivers. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

builtin: pass repository to sub commands

2024-11-26T01:36:08Z

In 9b1cb5070f (builtin: add a repository parameter for builtin functions, 2024-09-13) the repository was passed down to all builtin commands. This allowed the repository to be passed down to lower layers without depending on the global `the_repository` variable. Continue this work by also passing down the repository parameter from the command to sub-commands. This will help pass down the repository to other subsystems and cleanup usage of global variables like 'the_repository' and 'the_hash_algo'. Signed-off-by: Karthik Nayak Signed-off-by: Junio C Hamano

parse-options: cast long name for OPTION_ALIAS

2024-06-07T17:30:53Z

We assign the long name for OPTION_ALIAS options to a non-constant value field. We know that the variable will never be written to, but this will cause warnings once we enable `-Wwrite-strings`. Cast away the constness to be prepared for this change. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano