am: support --empty=(die|drop|keep) option and --allow-empty option to handle empty patches

Since that git has supported the --always option for the git-format-patch command to create a patch with an empty commit message, git-am should support applying and committing with empty patches.

----------------------------------------------------------------------------

Changes since v1:

1. add a case when not passing the --always option.
2. rename the --always option to --allow-empty.

----------------------------------------------------------------------------

Changes since v2:

1. rename the --allow-empty option to --empty-commit.
2. introduce three different strategies (die|skip|asis) when trying to record empty patches as empty commits.

----------------------------------------------------------------------------

Changes since v3:

1. generate the missed file for test cases.
2. grep -f cannot be used under Mac OS.

----------------------------------------------------------------------------

Changes since v4:

1. rename the --empty-commit option to --empty.
2. rename three different strategies (die|skip|asis) to die, drop and keep correspondingly.

----------------------------------------------------------------------------

Changes since v5:

1. throw an error when passing --empty option without value.

----------------------------------------------------------------------------

Changes since v6:

1. add i18n resources.

----------------------------------------------------------------------------

Changes since v7:

1. update code according to the seen branch.
2. fix the wrong document of git-am.
3. sign off commits by a real name.

----------------------------------------------------------------------------

Changes since v8:

1. update the committer's name with my real name to fix DCO of GGG.

----------------------------------------------------------------------------

Changes since v9:

1. imitate the signed name format of

    https://lore.kernel.org/git/[email protected]
    .

----------------------------------------------------------------------------

Changes since v11:

1. introduce an interactive option --allow-empty for git-am to record empty patches in the middle of an am session.

----------------------------------------------------------------------------

Changes since v12:

1. record the empty patch as an empty commit only when there are no changes.
2. fix indentation problems.
3. simplify "to keep recording" to "to record".
4. add a test case for skipping empty patches via the --skip option.

----------------------------------------------------------------------------

Changes since v13:

1. add an additional description about the 'die' value.

----------------------------------------------------------------------------

Changes since v14:

1. reimplement the 'die' value and stop the whole session. (Expected a reroll)
2. the --allow-empty option is a valid resume value only when: (Expected a reroll)
* index has not changed
* lacking a patch

----------------------------------------------------------------------------

Changes since v15:

1. rename "die" to "stop".

----------------------------------------------------------------------------

Changes since v16:

1. fix the typo from "had" to "has" in the comment.

----------------------------------------------------------------------------

Changes since v17:

1. add trailing comma, show tips of creating an empty commit, and use "%B" to construct test cases.
2. remove the error "Invalid resume value.".
3. hint "--allow-empty" after "--skip".

----------------------------------------------------------------------------

Changes since v18:

1. remove strict checking of "--allow-empty".

徐沛文 (Aleen) (3):
doc: git-format-patch: describe the option --always
am: support --empty=<option> to handle empty patches
am: support --allow-empty to record specific empty patches

 Documentation/git-am.txt           |  16 ++++-
 Documentation/git-format-patch.txt |   6 +-
 builtin/am.c                       |  89 ++++++++++++++++++++----
 t/t4150-am.sh                      | 107 +++++++++++++++++++++++++++++
 t/t7512-status-help.sh             |   1 +
 wt-status.c                        |   8 ++-
 6 files changed, 211 insertions(+), 16 deletions(-)

base-commit: abe6bb3905392d5eb6b01fa6e54d7e784e0522aa
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1076%2Faleen42%2Fnext-v19
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1076/aleen42/next-v19
Pull-Request: https://github.com/gitgitgadget/git/pull/1076

Range-diff vs v18:

 1:  a524ca6adfa = 1:  a524ca6adfa doc: git-format-patch: describe the option --always
 2:  56953d416d9 = 2:  56953d416d9 am: support --empty=<option> to handle empty patches
 3:  4c3077f9384 ! 3:  37875e8d313 am: support --allow-empty to record specific empty patches
     @@ Commit message
          This option helps to record specific empty patches in the middle
          of an am session, which does create empty commits only when:
      
     -        1. index has not changed
     +        1. the index has not changed
              2. lacking a branch
      
     +    When the index has changed, "--allow-empty" will create a non-empty
     +    commit like passing "--continue" or "--resolved".
     +
          Signed-off-by: 徐沛文 (Aleen) <[email protected]>
      
       ## Documentation/git-am.txt ##
     @@ builtin/am.c: next:
      -static void am_resolve(struct am_state *state)
      +static void am_resolve(struct am_state *state, int allow_empty)
       {
     -+	int index_changed;
     -+
       	validate_resume_state(state);
       
       	say(state, stdout, _("Applying: %.*s"), linelen(state->msg), state->msg);
       
     --	if (!repo_index_has_changes(the_repository, NULL, NULL)) {
     + 	if (!repo_index_has_changes(the_repository, NULL, NULL)) {
      -		printf_ln(_("No changes - did you forget to use 'git add'?\n"
      -			"If there is nothing left to stage, chances are that something else\n"
      -			"already introduced the same changes; you might want to skip this patch."));
     -+	index_changed = repo_index_has_changes(the_repository, NULL, NULL);
     -+	if (allow_empty &&
     -+	    !(!index_changed && is_empty_or_missing_file(am_path(state, "patch"))))
     - 		die_user_resolve(state);
     -+
     -+	if (!index_changed) {
     -+		if (allow_empty) {
     +-		die_user_resolve(state);
     ++		if (allow_empty && is_empty_or_missing_file(am_path(state, "patch"))) {
      +			printf_ln(_("No changes - recorded it as an empty commit."));
      +		} else {
      +			printf_ln(_("No changes - did you forget to use 'git add'?\n"
     @@ t/t4150-am.sh: test_expect_success 'record as an empty commit when meeting e-mai
      +	grep -f actual expected
      +'
      +
     -+test_expect_success 'cannot create empty commits when the index is changed' '
     ++test_expect_success 'create an non-empty commit when the index IS changed though "--allow-empty" is given' '
      +	git checkout empty-commit^ &&
      +	test_must_fail git am empty-commit.patch >err &&
      +	: >empty-file &&
      +	git add empty-file &&
     -+	test_must_fail git am --allow-empty >err &&
     -+	! grep "To record the empty patch as an empty commit, run \"git am --allow-empty\"." err
     ++	git am --allow-empty &&
     ++	git show empty-commit --format="%B" >expected &&
     ++	git show HEAD --format="%B" >actual &&
     ++	grep -f actual expected &&
     ++	git diff HEAD^..HEAD --name-only
      +'
      +
      +test_expect_success 'cannot create empty commits when there is a clean index due to merge conflicts' '

gitgitgadget