docs: clean up `--empty` formatting in git-rebase(1) and git-am(1)

Both of these pages document very similar `--empty` options, but with
different styles. The exact behavior of these `--empty` options differs
somewhat, but consistent styling in the docs is still beneficial. This
commit aims to make them more consistent.

Break the possible values for `--empty` into separate sections for
readability. Alphabetical order is chosen for consistency.

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

Signed-off-by: Brian Lyles <brianmlyles@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 463a3c660024e08b494caa3e22b4d4c417f46e0c..624a6e6fe4f9752fb518223d45cc524b8d3c8bd7 100644 (file)
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -66,13 +66,19 @@ OPTIONS
 --quoted-cr=<action>::
        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.
+--empty=(drop|keep|stop)::
+       How to handle an e-mail message lacking a patch:
++
+--
+`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.
+`stop`;;
+       The command will fail, stopping in the middle of the current `am`
+       session. This is the default behavior.
+--
 
 -m::
 --message-id::

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index a602e8fa81f214863f948a545f240b5e51242dda..17133bf382535bf5640a8cc64728feaa595147d2 100644 (file)
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -289,17 +289,24 @@ See also INCOMPATIBLE OPTIONS below.
 +
 See also INCOMPATIBLE OPTIONS below.
 
---empty=(drop|keep|ask)::
+--empty=(ask|drop|keep)::
        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, 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.
-       When the `-i`/`--interactive` option is used, the default becomes ask.
-       Otherwise, when the `--exec` option is used, the default becomes keep.
+       upstream changes):
++
+--
+`ask`;;
+       The rebase will halt when the 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 `-i`/`--interactive` is
+       specified.
+`drop`;;
+       The commit will be dropped. This is the default behavior.
+`keep`;;
+       The commit will be kept. This option is implied when `--exec` is
+       specified unless `-i`/`--interactive` is also specified.
+--
 +
 Note that commits which start empty are kept (unless `--no-keep-empty`
 is specified), and commits which are clean cherry-picks (as determined
@@ -704,7 +711,7 @@ be dropped automatically with `--no-keep-empty`).
 Similar to the apply backend, by default the merge backend drops
 commits that become empty unless `-i`/`--interactive` is specified (in
 which case it stops and asks the user what to do).  The merge backend
-also has an `--empty=(drop|keep|ask)` option for changing the behavior
+also has an `--empty=(ask|drop|keep)` option for changing the behavior
 of handling commits that become empty.
 
 Directory rename detection