Subject: [PATCH 2/4] docs: Clean up `--empty` formatting in `git-rebase` and `git-am`

From: [email-masked]
Date: Thu, 18 Jan 2024 23:59:18 -0600

From: Brian Lyles <[email-masked]>

Both of these pages document very similar `--empty` options, but with
different styles. This commit aims to make them more consistent.

In a future commit, we'll be documenting a new `--empty` option for
`git-cherry-pick`, making the consistency even more relevant.

Signed-off-by: Brian Lyles <[email-masked]>
---
 Documentation/git-am.txt     | 18 ++++++++++++------
 Documentation/git-rebase.txt | 17 ++++++++++++-----
 2 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index e080458d6c..77df5e606a 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -67,12 +67,18 @@ OPTIONS
 	This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]).
 
 --empty=(stop|drop|keep)::
-	By default, or when the option is set to 'stop', the command
-	errors out on an input e-mail message lacking a patch
-	and stops in the middle of the current am session. When this
-	option is set to 'drop', skip such an e-mail message instead.
-	When this option is set to 'keep', create an empty commit,
-	recording the contents of the e-mail message as its log.
+	How to handle an e-mail message lacking a patch:
++
+--
+`stop`;;
+	The command will fail, stopping in the middle of the current `am`
+	session. This is the default behavior.
+`drop`;;
+	The e-mail message will be skipped.
+`keep`;;
+	An empty commit will be created, with the contents of the e-mail
+	message as its log.
+--
 
 -m::
 --message-id::
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index b4526ca246..3ee85f6d86 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -293,13 +293,20 @@ See also INCOMPATIBLE OPTIONS below.
 	How to handle commits that are not empty to start and are not
 	clean cherry-picks of any upstream commit, but which become
 	empty after rebasing (because they contain a subset of already
-	upstream changes).  With drop (the default), commits that
-	become empty are dropped.  With keep, such commits are kept.
-	With ask (implied by `--interactive`), the rebase will halt when
-	an empty commit is applied allowing you to choose whether to
-	drop it, edit files more, or just commit the empty changes.
+	upstream changes):
++
+--
+`drop`;;
+	The empty commit will be dropped. This is the default behavior.
+`keep`;;
+	The empty commit will be kept.
+`ask`;;
+	The rebase will halt when the empty commit is applied, allowing you to
+	choose whether to drop it, edit files more, or just commit the empty
+	changes. This option is implied when `--interactive` is specified.
 	Other options, like `--exec`, will use the default of drop unless
 	`-i`/`--interactive` is explicitly specified.
+--
 +
 Note that commits which start empty are kept (unless `--no-keep-empty`
 is specified), and commits which are clean cherry-picks (as determined
-- 
2.41.0