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>
Brian Lyles committed
Mar 25, 2024 at 18:16 UTC
64a443efe4846d9cf09c7ff50cb9a6660fb49b50
2 files changed
+29
-16
Documentation/git-am.txt
+13
-7
@@ -66,13 +66,19 @@ OPTIONS
66
--quoted-cr=<action>::
67
This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]).
68
69
---empty=(stop|drop|keep)::
70
- By default, or when the option is set to 'stop', the command
71
- errors out on an input e-mail message lacking a patch
72
- and stops in the middle of the current am session. When this
73
- option is set to 'drop', skip such an e-mail message instead.
74
- When this option is set to 'keep', create an empty commit,
75
- recording the contents of the e-mail message as its log.
69
+--empty=(drop|keep|stop)::
70
+ How to handle an e-mail message lacking a patch:
71
++
72
+--
73
+`drop`;;
74
+ The e-mail message will be skipped.
75
+`keep`;;
76
+ An empty commit will be created, with the contents of the e-mail
77
+ message as its log.
78
+`stop`;;
79
+ The command will fail, stopping in the middle of the current `am`
80
+ session. This is the default behavior.
81
+--
82
83
-m::
84
--message-id::
Documentation/git-rebase.txt
+16
-9
@@ -289,17 +289,24 @@ See also INCOMPATIBLE OPTIONS below.
289
+
290
See also INCOMPATIBLE OPTIONS below.
291
292
---empty=(drop|keep|ask)::
292
+--empty=(ask|drop|keep)::
293
How to handle commits that are not empty to start and are not
294
clean cherry-picks of any upstream commit, but which become
295
empty after rebasing (because they contain a subset of already
296
- upstream changes). With drop (the default), commits that
297
- become empty are dropped. With keep, such commits are kept.
298
- With ask, the rebase will halt when an empty commit is applied
299
- allowing you to choose whether to drop it, edit files more, or just
300
- commit the empty changes.
301
- When the `-i`/`--interactive` option is used, the default becomes ask.
302
- Otherwise, when the `--exec` option is used, the default becomes keep.
296
+ upstream changes):
297
++
298
+--
299
+`ask`;;
300
+ The rebase will halt when the commit is applied, allowing you to
301
+ choose whether to drop it, edit files more, or just commit the empty
302
+ changes. This option is implied when `-i`/`--interactive` is
303
+ specified.
304
+`drop`;;
305
+ The commit will be dropped. This is the default behavior.
306
+`keep`;;
307
+ The commit will be kept. This option is implied when `--exec` is
308
+ specified unless `-i`/`--interactive` is also specified.
309
+--
310
+
311
Note that commits which start empty are kept (unless `--no-keep-empty`
312
is specified), and commits which are clean cherry-picks (as determined
@@ -704,7 +711,7 @@ be dropped automatically with `--no-keep-empty`).
711
Similar to the apply backend, by default the merge backend drops
712
commits that become empty unless `-i`/`--interactive` is specified (in
713
which case it stops and asks the user what to do). The merge backend
707
-also has an `--empty=(drop|keep|ask)` option for changing the behavior
714
+also has an `--empty=(ask|drop|keep)` option for changing the behavior
715
of handling commits that become empty.
716
717
Directory rename detection