Subject: Re: Can I checkout a single file without altering index?

From: Jonathan Nieder <[email-masked]>
Date: Fri, 15 Oct 2010 14:32:52 -0500

Jeff King wrote:
> On Fri, Oct 15, 2010 at 01:43:02PM -0500, Jonathan Nieder wrote:
>> Neal Kreitzinger wrote:

>>> However, there is an option in git-commit to copy files directly from the 
>>> working-tree to the object-store by totally bypassing the index
>>
>> What option is this?  I thought "git commit --include" added content
>> to the index.
>
> git commit -o|--only, which is the same as "git commit <paths>". Of
> course it still uses an index, to create the tree, but it uses a
> temporary one based on HEAD instead of the current index contents.

Ah, it's stranger than that.

	 * A partial commit.
	 *
	 * (0) find the set of affected paths;
	 * (1) get lock on the real index file;
	 * (2) update the_index with the given paths;
	 * (3) write the_index out to the real index (still locked);
	 * (4) get lock on the false index file;
	 * (5) reset the_index from HEAD;
	 * (6) update the_index the same way as (2);
	 * (7) write the_index out to the false index file;
	 * (8) return the name of the false index file (still locked);

The net effect being that the index will match the work tree for the
listed paths when the operation is over, while other files are
untouched.
-- 8< --
Subject: Documentation: clarify "commit --only" description

>>From the current description, one might imagine that "git commit
<pathspec>" bypasses the index completely.  Clarify what it does
do to the index:

 - paths matching <pathspec> are updated to match the work tree
 - paths not matching <pathspec> are left alone

so readers can have a better idea of what the index represents
before and after such an operation.

Signed-off-by: Jonathan Nieder <[email-masked]>
---
 I'm not so happy with the wording.  Hopefully this gives the idea...

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 42fb1f5..6bb3eff 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -191,9 +191,10 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
 --only::
 	Make a commit only from the paths specified on the
 	command line, disregarding any contents that have been
-	staged so far. This is the default mode of operation of
-	'git commit' if any paths are given on the command line,
-	in which case this option can be omitted.
+	staged so far.  The state of other files in the index is
+	preserved and will not affect the commit.  This is the
+	default mode of operation of 'git commit' if any paths are given
+	on the command line, in which case this option can be omitted.
 	If this option is specified together with '--amend', then
 	no paths need to be specified, which can be used to amend
 	the last commit without committing changes that have