1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-05-12 08:16:08 +02:00

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>
This commit is contained in:
Brian Lyles 2024-03-25 18:16:49 -05:00 committed by Junio C Hamano
parent 0af38890ad
commit 64a443efe4
2 changed files with 29 additions and 16 deletions

View File

@ -66,13 +66,19 @@ OPTIONS
--quoted-cr=<action>:: --quoted-cr=<action>::
This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]). This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]).
--empty=(stop|drop|keep):: --empty=(drop|keep|stop)::
By default, or when the option is set to 'stop', the command How to handle an e-mail message lacking a patch:
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. `drop`;;
When this option is set to 'keep', create an empty commit, The e-mail message will be skipped.
recording the contents of the e-mail message as its log. `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:: -m::
--message-id:: --message-id::

View File

@ -289,17 +289,24 @@ See also INCOMPATIBLE OPTIONS below.
+ +
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 How to handle commits that are not empty to start and are not
clean cherry-picks of any upstream commit, but which become clean cherry-picks of any upstream commit, but which become
empty after rebasing (because they contain a subset of already empty after rebasing (because they contain a subset of already
upstream changes). With drop (the default), commits that upstream changes):
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 `ask`;;
commit the empty changes. The rebase will halt when the commit is applied, allowing you to
When the `-i`/`--interactive` option is used, the default becomes ask. choose whether to drop it, edit files more, or just commit the empty
Otherwise, when the `--exec` option is used, the default becomes keep. 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` Note that commits which start empty are kept (unless `--no-keep-empty`
is specified), and commits which are clean cherry-picks (as determined 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 Similar to the apply backend, by default the merge backend drops
commits that become empty unless `-i`/`--interactive` is specified (in commits that become empty unless `-i`/`--interactive` is specified (in
which case it stops and asks the user what to do). The merge backend 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. of handling commits that become empty.
Directory rename detection Directory rename detection