Re: git commit -p with file arguments

[Junio C Hamano <gitster@pobox.com>]

Duy Nguyen <pclouds@gmail.com> writes:

>> At the least I think we should clarify this in the document.
>
> How about something like this? Would it help?
>
> -- 8< --
> Subject: [PATCH] git-commit.txt: clarify --patch mode with pathspec
>
> How pathspec is used, with and without --interactive/--patch, is
> different. But this is not clear from the document. These changes hint
> the user to keep reading (to option #5) instead of stopping at #2 and
> assuming --patch/--interactive behaves the same way.
>
> And since all the options listed here always mention how the index is
> involved (or not) in the final commit, add that bit for #5 as well. This
> "on top of the index" is implied when you head over git-add(1), but if
> you just go straight to the "Interactive mode" and not read what git-add
> is for, you may miss it.
>
> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
> ---

Excellent.  

>  Documentation/git-commit.txt | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index b0a294d..f2ab0ee 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -29,7 +29,8 @@ The content to be added can be specified in several ways:
>  2. by using 'git rm' to remove files from the working tree
>     and the index, again before using the 'commit' command;
>  
> -3. by listing files as arguments to the 'commit' command, in which
> +3. by listing files as arguments to the 'commit' command
> +   (without --interactive or --patch switch), in which
>     case the commit will ignore changes staged in the index, and instead
>     record the current content of the listed files (which must already
>     be known to Git);
> @@ -41,7 +42,8 @@ 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,
> +   to decide one by one which files or hunks should be part of the commit
> +   in addition to contents in the index,
>     before finalizing the operation. See the ``Interactive Mode'' section of
>     linkgit:git-add[1] to learn how to operate these modes.

When re-reading these 5 bullet points, I feel there may be some
unrelated updates needed to clarify (e.g. it is unclear when reading
the description pretending to be a newbie, if it is the "changes"
that is recorded in the index, or if it is the "state"; the answer
is the latter but if the reader's world model is still the former,
the description can mislead to expect a different behaviour).

But regardless of such remaining potential issues, this is a clearly
good change.  Thanks.