Subject: [PATCH v2 0/6] doc: convert another batch of files to synopsis style

From: "Jean-Noël Avila via GitGitGadget" <[email-masked]>
Date: Mon, 25 May 2026 10:28:21 +0000

This time, 5 new conversions:

 * git-bisect
 * git-grep
 * git-am
 * git-apply
 * git-imap-send

This batch was an opportunity to test AI-helped conversion.

Changes since v1:

 * clarify the use of synopsis vs code block in git-bisect, which also
   include using '$'

Jean-Noël Avila (6):
  doc: convert git-bisect to synopsis style
  doc: git bisect: clarify the usage of the synopsis vs actual command
  doc: convert git-grep synopsis and options to new style
  doc: convert git-am synopsis and options to new style
  doc: convert git-apply synopsis and options to new style
  doc: convert git-imap-send synopsis and options to new style

 Documentation/asciidoc.conf.in                |   6 +
 Documentation/config/am.adoc                  |   6 +-
 Documentation/config/apply.adoc               |  17 +-
 Documentation/config/grep.adoc                |  36 ++--
 Documentation/config/imap.adoc                |  30 +--
 Documentation/format-patch-caveats.adoc       |   2 +-
 .../format-patch-end-of-commit-message.adoc   |   4 +-
 Documentation/git-am.adoc                     | 132 ++++++------
 Documentation/git-apply.adoc                  | 125 +++++------
 Documentation/git-bisect.adoc                 | 109 +++++-----
 Documentation/git-grep.adoc                   | 196 +++++++++---------
 Documentation/git-imap-send.adoc              |  24 +--
 12 files changed, 346 insertions(+), 341 deletions(-)

base-commit: 56a4f3c3a221adf1df9b39da69b8a6890f803157
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2117%2Fjnavila%2Fbisect-synopsis-style-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2117/jnavila/bisect-synopsis-style-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2117

Range-diff vs v1:

 1:  dca7f192f1 ! 1:  7284281fe0 doc: convert git-bisect to synopsis style
     @@ Documentation/git-bisect.adoc: that, as it cleans up the old bisection state.)
       With an optional argument, you can return to a different commit
       instead:
       
     +-------------------------------------------------
      +[synopsis]
     - ------------------------------------------------
       $ 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
      @@ Documentation/git-bisect.adoc: To use "old" and "new" instead of "good" and bad, you must run `git
       bisect start` without commits as argument and then run the following
       commands to add the commits:
       
     +-------------------------------------------------
      +[synopsis]
     - ------------------------------------------------
       git bisect old [<rev>]
     - ------------------------------------------------
     +-------------------------------------------------
       
       to indicate that a commit was before the sought change, or
       
     +-------------------------------------------------
      +[synopsis]
     - ------------------------------------------------
       git bisect new [<rev>...]
     - ------------------------------------------------
     -@@ Documentation/git-bisect.adoc: to indicate that it was after.
     +-------------------------------------------------
     + 
     + to indicate that it was after.
       
       To get a reminder of the currently used terms, use
       
     +-------------------------------------------------
      +[synopsis]
     - ------------------------------------------------
       git bisect terms
     - ------------------------------------------------
     +-------------------------------------------------
     + 
     + You can get just the old term with `git bisect terms --term-old`
     + or `git bisect terms --term-good`; `git bisect terms --term-new`
      @@ Documentation/git-bisect.adoc: If you would like to use your own terms instead of "bad"/"good" or
       subcommands like `reset`, `start`, ...) by starting the
       bisection using
       
     +-------------------------------------------------
      +[synopsis]
     - ------------------------------------------------
       git bisect start --term-old <term-old> --term-new <term-new>
     - ------------------------------------------------
     +-------------------------------------------------
     + 
     + For example, if you are looking for a commit that introduced a
     + performance regression, you might use
      @@ Documentation/git-bisect.adoc: of `git bisect good` and `git bisect bad` to mark commits.
       Bisect visualize/view
       ~~~~~~~~~~~~~~~~~~~~~
 -:  ---------- > 2:  4fb33dd440 doc: git bisect: clarify the usage of the synopsis vs actual command
 2:  1b4efce1b2 = 3:  fceaf195e8 doc: convert git-grep synopsis and options to new style
 3:  4ab60a95f4 = 4:  b9c2adfa1d doc: convert git-am synopsis and options to new style
 4:  437e3f99c7 = 5:  60a420ea38 doc: convert git-apply synopsis and options to new style
 5:  dbe4d20b4b = 6:  d88824bf09 doc: convert git-imap-send synopsis and options to new style

-- 
gitgitgadget