From: "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail•com>
To: git@vger•kernel.org
Cc: "Jean-Noël Avila" <jn.avila@free•fr>,
"Jean-Noël Avila" <jn.avila@free•fr>
Subject: [PATCH v2 2/6] doc: git bisect: clarify the usage of the synopsis vs actual command
Date: Mon, 25 May 2026 10:28:23 +0000 [thread overview]
Message-ID: <4fb33dd4407a51c5ece6fb467e98c4da1ffa6f0e.1779704908.git.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.2117.v2.git.1779704908.gitgitgadget@gmail.com>
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free•fr>
The difference between a synopsis and an actual command is that the synopsis
is a more abstract representation of the command, which may include
placeholders for arguments and options. The actual command is the specific
instance of the command with all the arguments and options filled in.
The formatting of an actual command is a code block, with the command
prefixed by a dollar sign ($) to indicate that it is a command to be run in
the terminal. It can also include comments with a hash sign (#) to explain
the command or provide additional information, just like in a regular
terminal session.
Signed-off-by: Jean-Noël Avila <jn.avila@free•fr>
---
Documentation/git-bisect.adoc | 19 +++++++++----------
1 file changed, 9 insertions(+), 10 deletions(-)
diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc
index 4765d3b969..d2115b2990 100644
--- a/Documentation/git-bisect.adoc
+++ b/Documentation/git-bisect.adoc
@@ -96,9 +96,8 @@ Bisect reset
After a bisect session, to clean up the bisection state and return to
the original `HEAD`, issue the following command:
-------------------------------------------------
-$ git bisect reset
-------------------------------------------------
+[synopsis]
+git bisect reset
By default, this will return your tree to the commit that was checked
out before `git bisect start`. (A new `git bisect start` will also do
@@ -108,7 +107,8 @@ With an optional argument, you can return to a different commit
instead:
[synopsis]
-$ git bisect reset <commit>
+git bisect reset <commit>
+
For example, `git bisect reset bisect/bad` will check out the first
bad revision, while `git bisect reset HEAD` will leave you on the
@@ -174,13 +174,13 @@ For example, if you are looking for a commit that introduced a
performance regression, you might use
------------------------------------------------
-git bisect start --term-old fast --term-new slow
+$ git bisect start --term-old fast --term-new slow
------------------------------------------------
Or if you are looking for the commit that fixed a bug, you might use
------------------------------------------------
-git bisect start --term-new fixed --term-old broken
+$ git bisect start --term-new fixed --term-old broken
------------------------------------------------
Then, use `git bisect <term-old>` and `git bisect <term-new>` instead
@@ -328,11 +328,10 @@ Bisect run
If you have a script that can tell if the current source code is good
or bad, you can bisect by issuing the command:
-------------
-$ git bisect run my_script arguments
-------------
+[synopsis]
+git bisect run <cmd> [<arg>...]
-Note that the script (`my_script` in the above example) should exit
+Note that _<cmd>_ run with _<arg>_ should exit
with code 0 if the current source code is good/old, and exit with a
code between 1 and 127 (inclusive), except 125, if the current source
code is bad/new.
--
gitgitgadget
next prev parent reply other threads:[~2026-05-25 10:28 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-05-17 20:26 [PATCH 0/5] doc: convert another batch of files to synopsis style Jean-Noël Avila via GitGitGadget
2026-05-17 20:26 ` [PATCH 1/5] doc: convert git-bisect " Jean-Noël Avila via GitGitGadget
2026-05-18 0:26 ` Junio C Hamano
2026-05-18 2:10 ` Junio C Hamano
2026-05-19 21:03 ` Jean-Noël AVILA
2026-05-19 20:57 ` Jean-Noël AVILA
2026-05-17 20:26 ` [PATCH 2/5] doc: convert git-grep synopsis and options to new style Jean-Noël Avila via GitGitGadget
2026-05-17 20:26 ` [PATCH 3/5] doc: convert git-am " Jean-Noël Avila via GitGitGadget
2026-05-17 20:26 ` [PATCH 4/5] doc: convert git-apply " Jean-Noël Avila via GitGitGadget
2026-05-17 20:26 ` [PATCH 5/5] doc: convert git-imap-send " Jean-Noël Avila via GitGitGadget
2026-05-25 10:28 ` [PATCH v2 0/6] doc: convert another batch of files to synopsis style Jean-Noël Avila via GitGitGadget
2026-05-25 10:28 ` [PATCH v2 1/6] doc: convert git-bisect " Jean-Noël Avila via GitGitGadget
2026-05-25 10:28 ` Jean-Noël Avila via GitGitGadget [this message]
2026-05-25 10:28 ` [PATCH v2 3/6] doc: convert git-grep synopsis and options to new style Jean-Noël Avila via GitGitGadget
2026-05-25 10:28 ` [PATCH v2 4/6] doc: convert git-am " Jean-Noël Avila via GitGitGadget
2026-05-25 10:28 ` [PATCH v2 5/6] doc: convert git-apply " Jean-Noël Avila via GitGitGadget
2026-05-25 10:28 ` [PATCH v2 6/6] doc: convert git-imap-send " Jean-Noël Avila via GitGitGadget
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=4fb33dd4407a51c5ece6fb467e98c4da1ffa6f0e.1779704908.git.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=jn.avila@free$(echo .)fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox