[PATCH v2 0/4] checkout/restore: fix `git checkout -p HEAD...` bug

As reported earlier[0], `git checkout -p HEAD...` results in the following error:

	$ git checkout -p HEAD...
	usage: git diff-index [-m] [--cached] [<common-diff-options>] <tree-ish> [<path>...]
	common diff options:
	  -z            output diff-raw with lines terminated with NUL.
	  -p            output patch format.
	  -u            synonym for -p.
	  --patch-with-raw
			output both a patch and the diff-raw format.
	  --stat        show diffstat instead of patch.
	  --numstat     show numeric diffstat instead of patch.
	  --patch-with-stat
			output a patch and prepend its diffstat.
	  --name-only   show only names of changed files.
	  --name-status show names and status of changed files.
	  --full-index  show full object name on index lines.
	  --abbrev=<n>  abbreviate object names in diff-tree header and diff-raw.
	  -R            swap input file pairs.
	  -B            detect complete rewrites.
	  -M            detect renames.
	  -C            detect copies.
	  --find-copies-harder
			try unchanged files as candidate for copy detection.
	  -l<n>         limit rename attempts up to <n> paths.
	  -O<file>      reorder diffs according to the <file>.
	  -S<string>    find filepair whose only one side contains the string.
	  --pickaxe-all
			show all files diff when -S is used and hit is found.
	  -a  --text    treat all files as text.

	Cannot close git diff-index --cached --numstat --summary HEAD... -- () at <redacted>/libexec/git-core/git-add--interactive line 183.

Since it was decided that <tree-ish> should also officially support the merge-base revs, fix `git checkout -p <rev>...` and officially document the support.

Changes since v1:

* Add two NEEDSWORK commits

* Be more precise in the inline code comment

[0]: https://lore.kernel.org/git/20200929061830.GA40759@generichostname/

Denton Liu (4):
  builtin/checkout: fix `git checkout -p HEAD...` bug
  Doc: document "A...B" form for <tree-ish> in checkout and switch
  add-patch: add NEEDSWORK about comparing commits
  t2016: add a NEEDSWORK about the PERL prerequisite

 Documentation/git-checkout.txt |  4 ++++
 Documentation/git-restore.txt  |  4 ++++
 add-patch.c                    |  8 ++++++++
 builtin/checkout.c             | 15 ++++++++++++++-
 git-add--interactive.perl      |  7 +++++++
 t/t2016-checkout-patch.sh      | 11 +++++++++++
 t/t2071-restore-patch.sh       |  8 ++++++++
 7 files changed, 56 insertions(+), 1 deletion(-)

Range-diff against v1:
1:  54f221411f ! 1:  723d74febe builtin/checkout: fix `git checkout -p HEAD...` bug
    @@ builtin/checkout.c: static int checkout_paths(const struct checkout_opts *opts,
     +		char rev_oid[GIT_MAX_HEXSZ + 1];
     +
     +		/*
    -+		 * Since rev can be in the form of `<a>...<b>`, we must replace
    -+		 * the name with the hex of the commit for the
    -+		 * run_add_interactive() machinery to work properly. However,
    -+		 * there is special logic for the HEAD case so we mustn't
    -+		 * replace that.
    ++		 * Since rev can be in the form of `<a>...<b>` (which is not
    ++		 * recognized by diff-index), we will always replace the name
    ++		 * with the hex of the commit (whether it's in `...` form or
    ++		 * not) for the run_add_interactive() machinery to work
    ++		 * properly. However, there is special logic for the HEAD case
    ++		 * so we mustn't replace that.
     +		 */
     +		if (rev && strcmp(rev, "HEAD"))
     +			rev = oid_to_hex_r(rev_oid, &new_branch_info->commit->object.oid);
2:  75920c1a25 = 2:  a0ed2f313d Doc: document "A...B" form for <tree-ish> in checkout and switch
-:  ---------- > 3:  44ee78450e add-patch: add NEEDSWORK about comparing commits
-:  ---------- > 4:  a20544f18a t2016: add a NEEDSWORK about the PERL prerequisite