Re: git commit --only -- $path when $path already has staged content

> Junio C Hamano <gitster@pobox.com> writes:
> 
>> In other words, you give paths from the command line to tell the
>> command that you want to record the contents of them in the working
>> tree as a whole to be recorded in the resulting commit.
> 
> ... and --only/--include only makes difference wrt what happens to
> contents from the other paths.
> 
> Perhaps the attached would clarify it better, but there may have to
> be some tutorial material to teach users that fundamentally there
> are two ways to use Git, one to prepare what to be committed in the
> index and run "git commit" without any paths, and the other to
> pretty much ignore the index and run "git commit" with paths (or
> with "-a"), and mixing two are considered to be rare exception.
> 
> You would (1) work with an elaborate sequence to build the next
> commit in the index using "add path" and "add -p", (2) notice a
> change that can go before what you are building (e.g. trivial
> typofix) outside the paths you are touching, and (3) edit that path
> and do "git commit <path>".  That is the only scenario that makes
> some sense to mix the two modes.
> 
> Imagine the change (2) you want to jump over your changes in (1)
> happens to be in a path you are working with the index, e.g. after
> running:
> 
> 	git add -p hello.rb
> 
> and picking only parts of changes you made to hello.rb into the
> index, you found a trivial typo in the same file but in an unrelated
> place (i.e. "git diff hello.rb" at that point would not show the
> typo either in the preimage or the context).  There is no way to
> make the typofix first without disrupting what you did so far, and
> "git commit -o" would not help (you would instead do a "git stash"
> to save away the work in progress, make _only_ the typofix in the
> same file, commit and then unstash, or something).
> 
> So in short, stick to either work with the index or ignore the
> index; do not mix the two workflows and you would not have to worry
> about "-o" or "-i".

>  Documentation/git-commit.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 0bbc8f5..d6c4af1 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -250,7 +250,7 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
>  
>  -o::
>  --only::
> -	Make a commit only from the paths specified on the
> +	Make a commit only from the working tree contents of 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,