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

2.28.0.942.g77c4c6094c