Re: [PATCH v2 1/4] doc: git-add: start man page with an example

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

Jean-Noël AVILA <jn.avila@free.fr> writes:

> On Friday, 15 August 2025 02:38:45 CEST Junio C Hamano wrote:
>> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>> ...
>> > +By default, `git commit` only commits changes that you've added to the
>> > +index.
>
> I do not understand this addition. I may not be missing knowledge, but this 
> behavior is not only "by default", it's the only behavior of git: commits are 
> made with the content of the index. Let's not make it more complicated than it 
> is already.

I'll only react to "the only behaviour" part, without "more
complicated" part.

I think Julia is referring to the fact that you can record the state
that is different from what is in the index (or, what has been
accumulated in the index by the past use of "git add" command that
is being discussed here) with "git commit [-i] <pathspec>".  You can
do

    $ edit fileA fileB ;# assume both are tracked
    $ git add fileA
    $ git commit fileB

and the resulting commit will record the contents for fileA found in
its parent (i.e. the result of "git add fileA" is not reflected).
If the last step were

    $ git commit -i fileB

then the resulting commit will record the contents for both fileA
you added with the last "git add" on it, and contents for fileB
found in the working tree at the time of "git commit -i" was run
(i.e. "git add fileB" was not required)..

By default, after the edit of fileA&B and the add of fileA, "git
commit" would not be aware of what is currently in fileB in the
working tree, and records the same contents as its parent for all
paths except for fileA, which would record what was last added with
"git add" to the index.

>> > For example, if you've edited `file.c` and want to commit your
>> 
>> > +changes, you can run:
>> Likewise.  "and want to record the resulting contents".
>> 
>> > ...
>> > -Please see linkgit:git-commit[1] for alternative ways to add content to a
>> > -commit.
>> 
>> In the original, this comment does look a bit out of place (as the
>> text around there does not talk about `git commit`), but as you said
>> that by default 'git commit' makes an as-is commit above, it may be
>> a good idea to move this sentence there.  `git commit <pathspec>` is
>> a handy thing to know even for beginners, and making your next commit
>> is what the user is working towards by using "git add".

And this relates to "more complicated" part of your comment.

I think keeping "by default" above and also keeping this comment
that hints about non-as-is commits made with "git commit <pathspec>"
is slightly more preferrable than dropping both of them altogether.
With only four additional lines, we cover basic "edit && add && commit"
cycle fairly completely.

I am also fine to drop the mention of 'git commit' altogether, but
it feels somewhat incomplete to not talk about commit when teaching
add.  After all, add is one of the primary ways to prepare for the
next commit---putting it the other way around, you want to learn add
primarily because you eventually would want to make a commit.

In any case, only having one (i.e. "by default") and dropping the
other ("see linkgit:git-commit"), like the patch did, did not make
much sense to me.

Thanks.