checkout: add --working-tree-only optionjc/checkout-working-tree-only

"git checkout <tree-ish> <pathspec>" has always copied the blob from
the tree-ish to the index before checking them out to the working tree.

Some users may want to grab a blob out of a tree-ish directly to the
working tree, without updating the index, so that "git diff" can be
used to assess the damage and adjust the file contents taken from a
different branch to be more appropriate for the current branch.

The new option "--working-tree-only" allows exactly that.

In the hindsight, when a command works on the working tree and/or
the index, the usual convention is:

 - with no other option, the command works only on the working tree;

 - with "--cached" option, the command works only on the index; and

 - with "--index" option, the command works on both the working tree
   and the index.

So we probably should have triggered the default behaviour under the
"--index" option, and triggered this "--working-tree-only" mode of
behaviour when "--index" option is not given.  From the same point
of view, "git checkout --cached <tree-ish> <pathspec>" would have
done the same as "git reset <tree-ish> <pathspec>" would do.  And
that may have made the command set a bit more consistent.

But that is merely a hindsight being 20/20, oh well.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

1 files changed, 20 insertions, 0 deletions

diff --git a/t/t2022-checkout-paths.sh b/t/t2022-checkout-paths.sh
index f46d0499bc..9ad74cebb2 100755
--- a/t/t2022-checkout-paths.sh
+++ b/t/t2022-checkout-paths.sh
@@ -78,4 +78,24 @@ test_expect_success 'do not touch files that are already up-to-date' '
 	test_cmp expect actual
 '
 
+test_expect_success 'working-tree-only option leaves checked out files unadded' '
+	git reset --hard &&
+	git checkout -b pu next &&
+	echo another line >>file1 &&
+	echo exists >file3 &&
+	git add file3 &&
+	git commit -a -m "another commit" &&
+	git checkout next &&
+
+	! grep "another line" file1 &&
+	git checkout --working-tree-only pu file1 file3 &&
+	grep "another line" file1 &&
+	test_must_fail git grep --cached "another line" file1 &&
+
+	grep exists file3 &&
+	git ls-files file3 >actual &&
+	>expect &&
+	test_cmp expect actual
+'
+
 test_done