Re: git 1.8.0.rc0.18.gf84667d trouble with "git commit -p file"

On Sat, Oct 6, 2012 at 12:07 PM, Jeff King [off-list ref] wrote:

Are you sure?  Does "--only" mean "only the changes I am about to mark"
or "only the paths I am about to tell you about"? Without partial hunk
selection (i.e., "commit -p"), they were the same; a path you mention is
a path which will be either be staged in its entirety or not. Specifying
(or omitting) the path was sufficient to say what you wanted. But with
"-p", I can see three useful possibilities:

  1. Do not include F in the commit, even if changes are staged in the
     index (i.e., take HEAD exactly).

  2. Include F in the commit, and stage partial changes on top of what is
     already staged.

  3. Include F in the commit, and stage partial changes on top of HEAD.

In cases 2 and 3, we are still taking "only the path" F. But we are
not taking "only what is about to be staged" in 2. And I can see both
being useful (2 because it is more convenient not to re-approve staged
changes, and 3 because there is no way to unstage changes via "-p").

I think I didn't consider 2. as a viable alternative because
re-approving hunks is not a problem (there are typically very few
hunks per file, and you'll recognise them if you've already staged
them) but not being able to unstage is a big problem (as it restricts
what commits I can make with --patch without changing my index).

But of course we're not specifying paths. So to me it is "include the
changes I am about to stage via -p", as opposed to "--only use the
changes I am about to stage via -p". I think the current behavior is
morally equivalent to how --include works with paths (which includes the
paths along with the current index, rather than only committing the
paths).

Or am I missing something about the distinction you're making? It seems
to me that the end behavior of thinking about it either way would be the
same.

The way I was thinking about it was to treat the index and the command
line as two orthogonal parts of the commit. --include and --only
control the inclusion/exclusion of the index; while the command line
arguments control which (currently unstaged) things are included. This
led me to the conclusion that "git commit --include" is equivalent to
"git commit", "git commit --include --all" is the same as "git commit
--all" which is why I tried to change the validation logic. (You are
correct that "--include --only" and "--interactive --all" still make
no sense).

Here's a re-roll of the patch with --only docs tweaked.

Conrad

----8<----

Clarify that --interactive/--patch add to the existing index to avoid
confusion like [1].

Make explicit that --only does not work with --interactive/--patch and
clean up wording around --only --amend.

[1] http://thread.gmane.org/gmane.comp.version-control.git/207108

Signed-off-by: Conrad Irwin <redacted>
---
 Documentation/git-commit.txt | 35 +++++++++++++++++------------------
 1 file changed, 17 insertions(+), 18 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 9594ac8..680d2bf 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt

@@ -41,9 +41,9 @@ The content to be added can be specified in several ways:
    actual commit;

 5. by using the --interactive or --patch switches with the 'commit' command
-   to decide one by one which files or hunks should be part of the commit,
-   before finalizing the operation. See the ``Interactive Mode'' section of
-   linkgit:git-add[1] to learn how to operate these modes.
+   to add files or hunks to the current index before committing. See the
+   ``Interactive Mode'' section of linkgit:git-add[1] to learn how to
+   operate these modes.

 The `--dry-run` option can be used to obtain a
 summary of what is included by any of the above for the next

@@ -63,10 +63,14 @@ OPTIONS

 -p::
 --patch::
-	Use the interactive patch selection interface to chose
-	which changes to commit. See linkgit:git-add[1] for
+	Use the interactive patch selection interface to add hunks
+	to the index before committing. See linkgit:git-add[1] for
 	details.

+--interactive::
+	Use the ``Interactive mode'' of linkgit:git-add[1] to edit
+	the index before committing.
+
 -C <commit>::
 --reuse-message=<commit>::
 	Take an existing commit object, and reuse the log message

@@ -215,22 +219,17 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)

 -i::
 --include::
-	Before making a commit out of staged contents so far,
-	stage the contents of paths given on the command line
-	as well.  This is usually not what you want unless you
-	are concluding a conflicted merge.
+	In addition to the paths specified on the command line,
+	include the current contents of the index in the commit.

 -o::
 --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.
-	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
-	already been staged.
+	Only commit changes to the paths specified on the command line,
+	do not include the current contents of the index. This is
+	the default mode of operation when paths are specified.
+	If this option is specified with --amend it can be used
+	to reword the last commit without changing its contents.
+	This mode cannot be used with --patch or --interactive.

 -u[<mode>]::
 --untracked-files[=<mode>]::

-- 
1.7.12.289.g0ce9864