From: Ben Knoble <ben.knoble@gmail.com>
Date: Wed, 29 Oct 2025 16:14:45 GMT
Subject: Re: [PATCH] bisect: update usage and docs to match each other
Message-ID: <A3B6994C-508A-4052-AD19-C5D773C0CC9F@gmail.com>
In-Reply-To: <pull.2084.git.git.1761690461697.gitgitgadget@gmail.com>


> Le 28 oct. 2025 à 18:27, Ruoyu Zhong via GitGitGadget <gitgitgadget@gmail.com> a écrit :
> 
> From: Ruoyu Zhong <zhongruoyu@outlook.com>
> 
> Update the usage string of `git bisect` and documentation to match each
> other. While at it, also:
> 
> 1. Move the synopsis of `git bisect` subcommands to the synopsis
>   section, so that the test `t0450-txt-doc-vs-help.sh` can pass.
> 
> 2. Document the `git bisect next` subcommand, which exists in the code
>   but is missing from the documentation.
> 
> See also: [1].
> 
> [1]: https://lore.kernel.org/git/3DA38465-7636-4EEF-B074-53E4628F5355@gmail.com/
> 
> Suggested-by: Ben Knoble <ben.knoble@gmail.com>
> Signed-off-by: Ruoyu Zhong <zhongruoyu@outlook.com>
> ---
>    bisect: update usage and docs to match each other
> 
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2084%2FZhongRuoyu%2Fgit-bisect-docs-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2084/ZhongRuoyu/git-bisect-docs-v1
> Pull-Request: https://github.com/git/git/pull/2084
> 
> Documentation/git-bisect.adoc | 43 +++++++++++++++++++++--------------
> builtin/bisect.c              | 21 ++++++++++-------
> t/t0450/adoc-help-mismatches  |  1 -
> 3 files changed, 39 insertions(+), 26 deletions(-)
> 
> diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc
> index 58dbb74a15..b0078dda0e 100644
> --- a/Documentation/git-bisect.adoc
> +++ b/Documentation/git-bisect.adoc
> @@ -9,26 +9,22 @@ git-bisect - Use binary search to find the commit that introduced a bug
> SYNOPSIS
> --------
> [verse]
> -'git bisect' <subcommand> <options>
> +'git bisect' start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
> +           [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
> +'git bisect' (bad|new|<term-new>) [<rev>]
> +'git bisect' (good|old|<term-old>) [<rev>...]
> +'git bisect' terms [--term-(good|old) | --term-(bad|new)]
> +'git bisect' skip [(<rev>|<range>)...]
> +'git bisect' next
> +'git bisect' reset [<commit>]
> +'git bisect' (visualize|view)
> +'git bisect' replay <logfile>
> +'git bisect' log
> +'git bisect' run <cmd> [<arg>...]
> +'git bisect' help
> 
> DESCRIPTION
> -----------
> -The command takes various subcommands, and different options depending
> -on the subcommand:
> -
> - git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
> -          [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
> - git bisect (bad|new|<term-new>) [<rev>]
> - git bisect (good|old|<term-old>) [<rev>...]
> - git bisect terms [--term-(good|old) | --term-(bad|new)]
> - git bisect skip [(<rev>|<range>)...]
> - git bisect reset [<commit>]
> - git bisect (visualize|view)
> - git bisect replay <logfile>
> - git bisect log
> - git bisect run <cmd> [<arg>...]
> - git bisect help
> -
> This command uses a binary search algorithm to find which commit in
> your project's history introduced a bug. You use it by first telling
> it a "bad" commit that is known to contain the bug, and a "good"
> @@ -295,6 +291,19 @@ $ git bisect skip v2.5 v2.5..v2.6
> This tells the bisect process that the commits between `v2.5` and
> `v2.6` (inclusive) should be skipped.
> 
> +Bisect next
> +~~~~~~~~~~~
> +
> +Normally, after marking a revision as good or bad, Git automatically
> +computes and checks out the next revision to test. However, if you need to
> +explicitly request the next bisection step, you can use:
> +
> +------------
> +$ git bisect next
> +------------
> +
> +You might use this to resume the bisection process after interrupting it
> +by checking out a different revision.
> 
> Cutting down bisection by giving more parameters to bisect start
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> diff --git a/builtin/bisect.c b/builtin/bisect.c
> index 8b8d870cd1..a500993bcb 100644
> --- a/builtin/bisect.c
> +++ b/builtin/bisect.c
> @@ -27,13 +27,14 @@ static GIT_PATH_FUNC(git_path_bisect_first_parent, "BISECT_FIRST_PARENT")
> static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
> 
> #define BUILTIN_GIT_BISECT_START_USAGE \
> -    N_("git bisect start [--term-(new|bad)=<term> --term-(old|good)=<term>]" \
> -       "    [--no-checkout] [--first-parent] [<bad> [<good>...]] [--]" \
> -       "    [<pathspec>...]")
> -#define BUILTIN_GIT_BISECT_STATE_USAGE \
> -    N_("git bisect (good|bad) [<rev>...]")
> +    N_("git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]\n" \
> +       "                 [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]")
> +#define BUILTIN_GIT_BISECT_BAD_USAGE \
> +    N_("git bisect (bad|new|<term-new>) [<rev>]")
> +#define BUILTIN_GIT_BISECT_GOOD_USAGE \
> +    N_("git bisect (good|old|<term-old>) [<rev>...]")
> #define BUILTIN_GIT_BISECT_TERMS_USAGE \
> -    "git bisect terms [--term-good | --term-bad]"
> +    "git bisect terms [--term-(good|old) | --term-(bad|new)]"
> #define BUILTIN_GIT_BISECT_SKIP_USAGE \
>    N_("git bisect skip [(<rev>|<range>)...]")
> #define BUILTIN_GIT_BISECT_NEXT_USAGE \
> @@ -41,17 +42,20 @@ static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
> #define BUILTIN_GIT_BISECT_RESET_USAGE \
>    N_("git bisect reset [<commit>]")
> #define BUILTIN_GIT_BISECT_VISUALIZE_USAGE \
> -    "git bisect visualize"
> +    "git bisect (visualize|view)"
> #define BUILTIN_GIT_BISECT_REPLAY_USAGE \
>    N_("git bisect replay <logfile>")
> #define BUILTIN_GIT_BISECT_LOG_USAGE \
>    "git bisect log"
> #define BUILTIN_GIT_BISECT_RUN_USAGE \
>    N_("git bisect run <cmd> [<arg>...]")
> +#define BUILTIN_GIT_BISECT_HELP_USAGE \
> +    "git bisect help"
> 
> static const char * const git_bisect_usage[] = {
>    BUILTIN_GIT_BISECT_START_USAGE,
> -    BUILTIN_GIT_BISECT_STATE_USAGE,
> +    BUILTIN_GIT_BISECT_BAD_USAGE,
> +    BUILTIN_GIT_BISECT_GOOD_USAGE,
>    BUILTIN_GIT_BISECT_TERMS_USAGE,
>    BUILTIN_GIT_BISECT_SKIP_USAGE,
>    BUILTIN_GIT_BISECT_NEXT_USAGE,
> @@ -60,6 +64,7 @@ static const char * const git_bisect_usage[] = {
>    BUILTIN_GIT_BISECT_REPLAY_USAGE,
>    BUILTIN_GIT_BISECT_LOG_USAGE,
>    BUILTIN_GIT_BISECT_RUN_USAGE,
> +    BUILTIN_GIT_BISECT_HELP_USAGE,
>    NULL
> };
> 
> diff --git a/t/t0450/adoc-help-mismatches b/t/t0450/adoc-help-mismatches
> index 2c6ecd5fc8..8ee2d3f7c8 100644
> --- a/t/t0450/adoc-help-mismatches
> +++ b/t/t0450/adoc-help-mismatches
> @@ -2,7 +2,6 @@ add
> am
> apply
> archive
> -bisect
> blame
> branch
> check-ref-format
> 
> base-commit: 57da342c786f59eaeb436c18635cc1c7597733d9
> --
> gitgitgadget

Nothing particularly surprising here, I think. Thanks!