{"thread":{"id":"64401","subject":"[PATCH] bisect: update usage and docs to match each other","startedAt":"2025-10-28T22:27:43Z","lastAt":"2025-10-29T16:14:57Z","messageCount":2,"participants":["Ruoyu Zhong via GitGitGadget","Ben Knoble"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"529840","messageId":"pull.2084.git.git.1761690461697.gitgitgadget@gmail.com","threadId":"64401","inReplyTo":null,"subject":"[PATCH] bisect: update usage and docs to match each other","fromName":"Ruoyu Zhong via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-28T22:27:41Z","receivedAt":"2025-10-28T22:27:43Z","isPatch":true,"sender":{"key":"zhongruoyu@outlook.com","avatar":"https://avatars.githubusercontent.com/u/25842576?v=4"},"body":"From: Ruoyu Zhong <zhongruoyu@outlook.com>\n\nUpdate the usage string of `git bisect` and documentation to match each\nother. While at it, also:\n\n1. Move the synopsis of `git bisect` subcommands to the synopsis\n   section, so that the test `t0450-txt-doc-vs-help.sh` can pass.\n\n2. Document the `git bisect next` subcommand, which exists in the code\n   but is missing from the documentation.\n\nSee also: [1].\n\n[1]: https://lore.kernel.org/git/3DA38465-7636-4EEF-B074-53E4628F5355@gmail.com/\n\nSuggested-by: Ben Knoble <ben.knoble@gmail.com>\nSigned-off-by: Ruoyu Zhong <zhongruoyu@outlook.com>\n---\n    bisect: update usage and docs to match each other\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2084%2FZhongRuoyu%2Fgit-bisect-docs-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2084/ZhongRuoyu/git-bisect-docs-v1\nPull-Request: https://github.com/git/git/pull/2084\n\n Documentation/git-bisect.adoc | 43 +++++++++++++++++++++--------------\n builtin/bisect.c              | 21 ++++++++++-------\n t/t0450/adoc-help-mismatches  |  1 -\n 3 files changed, 39 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc\nindex 58dbb74a15..b0078dda0e 100644\n--- a/Documentation/git-bisect.adoc\n+++ b/Documentation/git-bisect.adoc\n@@ -9,26 +9,22 @@ git-bisect - Use binary search to find the commit that introduced a bug\n SYNOPSIS\n --------\n [verse]\n-'git bisect' <subcommand> <options>\n+'git bisect' start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]\n+\t\t   [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]\n+'git bisect' (bad|new|<term-new>) [<rev>]\n+'git bisect' (good|old|<term-old>) [<rev>...]\n+'git bisect' terms [--term-(good|old) | --term-(bad|new)]\n+'git bisect' skip [(<rev>|<range>)...]\n+'git bisect' next\n+'git bisect' reset [<commit>]\n+'git bisect' (visualize|view)\n+'git bisect' replay <logfile>\n+'git bisect' log\n+'git bisect' run <cmd> [<arg>...]\n+'git bisect' help\n \n DESCRIPTION\n -----------\n-The command takes various subcommands, and different options depending\n-on the subcommand:\n-\n- git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]\n-\t\t  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]\n- git bisect (bad|new|<term-new>) [<rev>]\n- git bisect (good|old|<term-old>) [<rev>...]\n- git bisect terms [--term-(good|old) | --term-(bad|new)]\n- git bisect skip [(<rev>|<range>)...]\n- git bisect reset [<commit>]\n- git bisect (visualize|view)\n- git bisect replay <logfile>\n- git bisect log\n- git bisect run <cmd> [<arg>...]\n- git bisect help\n-\n This command uses a binary search algorithm to find which commit in\n your project's history introduced a bug. You use it by first telling\n it a \"bad\" commit that is known to contain the bug, and a \"good\"\n@@ -295,6 +291,19 @@ $ git bisect skip v2.5 v2.5..v2.6\n This tells the bisect process that the commits between `v2.5` and\n `v2.6` (inclusive) should be skipped.\n \n+Bisect next\n+~~~~~~~~~~~\n+\n+Normally, after marking a revision as good or bad, Git automatically\n+computes and checks out the next revision to test. However, if you need to\n+explicitly request the next bisection step, you can use:\n+\n+------------\n+$ git bisect next\n+------------\n+\n+You might use this to resume the bisection process after interrupting it\n+by checking out a different revision.\n \n Cutting down bisection by giving more parameters to bisect start\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\ndiff --git a/builtin/bisect.c b/builtin/bisect.c\nindex 8b8d870cd1..a500993bcb 100644\n--- a/builtin/bisect.c\n+++ b/builtin/bisect.c\n@@ -27,13 +27,14 @@ static GIT_PATH_FUNC(git_path_bisect_first_parent, \"BISECT_FIRST_PARENT\")\n static GIT_PATH_FUNC(git_path_bisect_run, \"BISECT_RUN\")\n \n #define BUILTIN_GIT_BISECT_START_USAGE \\\n-\tN_(\"git bisect start [--term-(new|bad)=<term> --term-(old|good)=<term>]\" \\\n-\t   \"    [--no-checkout] [--first-parent] [<bad> [<good>...]] [--]\" \\\n-\t   \"    [<pathspec>...]\")\n-#define BUILTIN_GIT_BISECT_STATE_USAGE \\\n-\tN_(\"git bisect (good|bad) [<rev>...]\")\n+\tN_(\"git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]\\n\" \\\n+\t   \"                 [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]\")\n+#define BUILTIN_GIT_BISECT_BAD_USAGE \\\n+\tN_(\"git bisect (bad|new|<term-new>) [<rev>]\")\n+#define BUILTIN_GIT_BISECT_GOOD_USAGE \\\n+\tN_(\"git bisect (good|old|<term-old>) [<rev>...]\")\n #define BUILTIN_GIT_BISECT_TERMS_USAGE \\\n-\t\"git bisect terms [--term-good | --term-bad]\"\n+\t\"git bisect terms [--term-(good|old) | --term-(bad|new)]\"\n #define BUILTIN_GIT_BISECT_SKIP_USAGE \\\n \tN_(\"git bisect skip [(<rev>|<range>)...]\")\n #define BUILTIN_GIT_BISECT_NEXT_USAGE \\\n@@ -41,17 +42,20 @@ static GIT_PATH_FUNC(git_path_bisect_run, \"BISECT_RUN\")\n #define BUILTIN_GIT_BISECT_RESET_USAGE \\\n \tN_(\"git bisect reset [<commit>]\")\n #define BUILTIN_GIT_BISECT_VISUALIZE_USAGE \\\n-\t\"git bisect visualize\"\n+\t\"git bisect (visualize|view)\"\n #define BUILTIN_GIT_BISECT_REPLAY_USAGE \\\n \tN_(\"git bisect replay <logfile>\")\n #define BUILTIN_GIT_BISECT_LOG_USAGE \\\n \t\"git bisect log\"\n #define BUILTIN_GIT_BISECT_RUN_USAGE \\\n \tN_(\"git bisect run <cmd> [<arg>...]\")\n+#define BUILTIN_GIT_BISECT_HELP_USAGE \\\n+\t\"git bisect help\"\n \n static const char * const git_bisect_usage[] = {\n \tBUILTIN_GIT_BISECT_START_USAGE,\n-\tBUILTIN_GIT_BISECT_STATE_USAGE,\n+\tBUILTIN_GIT_BISECT_BAD_USAGE,\n+\tBUILTIN_GIT_BISECT_GOOD_USAGE,\n \tBUILTIN_GIT_BISECT_TERMS_USAGE,\n \tBUILTIN_GIT_BISECT_SKIP_USAGE,\n \tBUILTIN_GIT_BISECT_NEXT_USAGE,\n@@ -60,6 +64,7 @@ static const char * const git_bisect_usage[] = {\n \tBUILTIN_GIT_BISECT_REPLAY_USAGE,\n \tBUILTIN_GIT_BISECT_LOG_USAGE,\n \tBUILTIN_GIT_BISECT_RUN_USAGE,\n+\tBUILTIN_GIT_BISECT_HELP_USAGE,\n \tNULL\n };\n \ndiff --git a/t/t0450/adoc-help-mismatches b/t/t0450/adoc-help-mismatches\nindex 2c6ecd5fc8..8ee2d3f7c8 100644\n--- a/t/t0450/adoc-help-mismatches\n+++ b/t/t0450/adoc-help-mismatches\n@@ -2,7 +2,6 @@ add\n am\n apply\n archive\n-bisect\n blame\n branch\n check-ref-format\n\nbase-commit: 57da342c786f59eaeb436c18635cc1c7597733d9\n-- \ngitgitgadget\n"},{"id":"529876","messageId":"A3B6994C-508A-4052-AD19-C5D773C0CC9F@gmail.com","threadId":"64401","inReplyTo":"pull.2084.git.git.1761690461697.gitgitgadget@gmail.com","subject":"Re: [PATCH] bisect: update usage and docs to match each other","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-10-29T16:14:45Z","receivedAt":"2025-10-29T16:14:57Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 28 oct. 2025 à 18:27, Ruoyu Zhong via GitGitGadget <gitgitgadget@gmail.com> a écrit :\n> \n> From: Ruoyu Zhong <zhongruoyu@outlook.com>\n> \n> Update the usage string of `git bisect` and documentation to match each\n> other. While at it, also:\n> \n> 1. Move the synopsis of `git bisect` subcommands to the synopsis\n>   section, so that the test `t0450-txt-doc-vs-help.sh` can pass.\n> \n> 2. Document the `git bisect next` subcommand, which exists in the code\n>   but is missing from the documentation.\n> \n> See also: [1].\n> \n> [1]: https://lore.kernel.org/git/3DA38465-7636-4EEF-B074-53E4628F5355@gmail.com/\n> \n> Suggested-by: Ben Knoble <ben.knoble@gmail.com>\n> Signed-off-by: Ruoyu Zhong <zhongruoyu@outlook.com>\n> ---\n>    bisect: update usage and docs to match each other\n> \n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2084%2FZhongRuoyu%2Fgit-bisect-docs-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2084/ZhongRuoyu/git-bisect-docs-v1\n> Pull-Request: https://github.com/git/git/pull/2084\n> \n> Documentation/git-bisect.adoc | 43 +++++++++++++++++++++--------------\n> builtin/bisect.c              | 21 ++++++++++-------\n> t/t0450/adoc-help-mismatches  |  1 -\n> 3 files changed, 39 insertions(+), 26 deletions(-)\n> \n> diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc\n> index 58dbb74a15..b0078dda0e 100644\n> --- a/Documentation/git-bisect.adoc\n> +++ b/Documentation/git-bisect.adoc\n> @@ -9,26 +9,22 @@ git-bisect - Use binary search to find the commit that introduced a bug\n> SYNOPSIS\n> --------\n> [verse]\n> -'git bisect' <subcommand> <options>\n> +'git bisect' start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]\n> +           [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]\n> +'git bisect' (bad|new|<term-new>) [<rev>]\n> +'git bisect' (good|old|<term-old>) [<rev>...]\n> +'git bisect' terms [--term-(good|old) | --term-(bad|new)]\n> +'git bisect' skip [(<rev>|<range>)...]\n> +'git bisect' next\n> +'git bisect' reset [<commit>]\n> +'git bisect' (visualize|view)\n> +'git bisect' replay <logfile>\n> +'git bisect' log\n> +'git bisect' run <cmd> [<arg>...]\n> +'git bisect' help\n> \n> DESCRIPTION\n> -----------\n> -The command takes various subcommands, and different options depending\n> -on the subcommand:\n> -\n> - git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]\n> -          [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]\n> - git bisect (bad|new|<term-new>) [<rev>]\n> - git bisect (good|old|<term-old>) [<rev>...]\n> - git bisect terms [--term-(good|old) | --term-(bad|new)]\n> - git bisect skip [(<rev>|<range>)...]\n> - git bisect reset [<commit>]\n> - git bisect (visualize|view)\n> - git bisect replay <logfile>\n> - git bisect log\n> - git bisect run <cmd> [<arg>...]\n> - git bisect help\n> -\n> This command uses a binary search algorithm to find which commit in\n> your project's history introduced a bug. You use it by first telling\n> it a \"bad\" commit that is known to contain the bug, and a \"good\"\n> @@ -295,6 +291,19 @@ $ git bisect skip v2.5 v2.5..v2.6\n> This tells the bisect process that the commits between `v2.5` and\n> `v2.6` (inclusive) should be skipped.\n> \n> +Bisect next\n> +~~~~~~~~~~~\n> +\n> +Normally, after marking a revision as good or bad, Git automatically\n> +computes and checks out the next revision to test. However, if you need to\n> +explicitly request the next bisection step, you can use:\n> +\n> +------------\n> +$ git bisect next\n> +------------\n> +\n> +You might use this to resume the bisection process after interrupting it\n> +by checking out a different revision.\n> \n> Cutting down bisection by giving more parameters to bisect start\n> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> diff --git a/builtin/bisect.c b/builtin/bisect.c\n> index 8b8d870cd1..a500993bcb 100644\n> --- a/builtin/bisect.c\n> +++ b/builtin/bisect.c\n> @@ -27,13 +27,14 @@ static GIT_PATH_FUNC(git_path_bisect_first_parent, \"BISECT_FIRST_PARENT\")\n> static GIT_PATH_FUNC(git_path_bisect_run, \"BISECT_RUN\")\n> \n> #define BUILTIN_GIT_BISECT_START_USAGE \\\n> -    N_(\"git bisect start [--term-(new|bad)=<term> --term-(old|good)=<term>]\" \\\n> -       \"    [--no-checkout] [--first-parent] [<bad> [<good>...]] [--]\" \\\n> -       \"    [<pathspec>...]\")\n> -#define BUILTIN_GIT_BISECT_STATE_USAGE \\\n> -    N_(\"git bisect (good|bad) [<rev>...]\")\n> +    N_(\"git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]\\n\" \\\n> +       \"                 [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]\")\n> +#define BUILTIN_GIT_BISECT_BAD_USAGE \\\n> +    N_(\"git bisect (bad|new|<term-new>) [<rev>]\")\n> +#define BUILTIN_GIT_BISECT_GOOD_USAGE \\\n> +    N_(\"git bisect (good|old|<term-old>) [<rev>...]\")\n> #define BUILTIN_GIT_BISECT_TERMS_USAGE \\\n> -    \"git bisect terms [--term-good | --term-bad]\"\n> +    \"git bisect terms [--term-(good|old) | --term-(bad|new)]\"\n> #define BUILTIN_GIT_BISECT_SKIP_USAGE \\\n>    N_(\"git bisect skip [(<rev>|<range>)...]\")\n> #define BUILTIN_GIT_BISECT_NEXT_USAGE \\\n> @@ -41,17 +42,20 @@ static GIT_PATH_FUNC(git_path_bisect_run, \"BISECT_RUN\")\n> #define BUILTIN_GIT_BISECT_RESET_USAGE \\\n>    N_(\"git bisect reset [<commit>]\")\n> #define BUILTIN_GIT_BISECT_VISUALIZE_USAGE \\\n> -    \"git bisect visualize\"\n> +    \"git bisect (visualize|view)\"\n> #define BUILTIN_GIT_BISECT_REPLAY_USAGE \\\n>    N_(\"git bisect replay <logfile>\")\n> #define BUILTIN_GIT_BISECT_LOG_USAGE \\\n>    \"git bisect log\"\n> #define BUILTIN_GIT_BISECT_RUN_USAGE \\\n>    N_(\"git bisect run <cmd> [<arg>...]\")\n> +#define BUILTIN_GIT_BISECT_HELP_USAGE \\\n> +    \"git bisect help\"\n> \n> static const char * const git_bisect_usage[] = {\n>    BUILTIN_GIT_BISECT_START_USAGE,\n> -    BUILTIN_GIT_BISECT_STATE_USAGE,\n> +    BUILTIN_GIT_BISECT_BAD_USAGE,\n> +    BUILTIN_GIT_BISECT_GOOD_USAGE,\n>    BUILTIN_GIT_BISECT_TERMS_USAGE,\n>    BUILTIN_GIT_BISECT_SKIP_USAGE,\n>    BUILTIN_GIT_BISECT_NEXT_USAGE,\n> @@ -60,6 +64,7 @@ static const char * const git_bisect_usage[] = {\n>    BUILTIN_GIT_BISECT_REPLAY_USAGE,\n>    BUILTIN_GIT_BISECT_LOG_USAGE,\n>    BUILTIN_GIT_BISECT_RUN_USAGE,\n> +    BUILTIN_GIT_BISECT_HELP_USAGE,\n>    NULL\n> };\n> \n> diff --git a/t/t0450/adoc-help-mismatches b/t/t0450/adoc-help-mismatches\n> index 2c6ecd5fc8..8ee2d3f7c8 100644\n> --- a/t/t0450/adoc-help-mismatches\n> +++ b/t/t0450/adoc-help-mismatches\n> @@ -2,7 +2,6 @@ add\n> am\n> apply\n> archive\n> -bisect\n> blame\n> branch\n> check-ref-format\n> \n> base-commit: 57da342c786f59eaeb436c18635cc1c7597733d9\n> --\n> gitgitgadget\n\nNothing particularly surprising here, I think. Thanks!"}]}