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

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Friday, 15 August 2025 18:33:47 CEST Junio C Hamano wrote:
> 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.
> 

Thanks for the explanation, I had forgotten this form of git commit. For the 
record, when I teach about add/commit, I never talk about the direct commit 
form, to present things in the most repeatable/unambiguous form.

The `git commit <pathspec>` form may be of use for old-timers who were doing 
so with previous SCMs. But as stated elsewhere, young newcomers do not have to 
fight against finger memory. The explanation that you provided describes a 
quite complicated process with options, so this feature seems to be reserved 
to advanced users.
 
The manual pages in section 1 are mostly reference stuff for a given command, 
and this way of referring here to alternate usage of git commit is a bit off-
topic to me. For how to organize workflows, there are some pages in section 7.

My stance is as follow: yes, being complete is important in a reference piece 
of documentation, but throwing a "by default" on `git commit` here, without 
further explanation, sends the reader in an unsure state, which is detrimental 
to understanding at this early stage of the documentation.

Otherwise, the idea of the simple example as an introduction is a good 
addition before delving into more formal and comprehensive explanation. The 
only caveat is to not introduce wrong concepts that may need to be reverted 
later.
 

> >> > 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.

I'm not for dropping them, but for deferring the mention of this special 
workflow later in the explanation, with the reference to `git commit`.

BR

Jean-Noël