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 02:38:45 CEST Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> > -git-add - Add file contents to the index
> > +git-add - Add new or changed files to the index
> 
> Does it add much value to say "new or changed" here?  The command can
> also be used to "stage" a removal of a path, e.g.
> 
>     $ rm tracked-file
>     $ git add -u
> 
> so if the updated text is an attempt to give more details on what
> kind of modifications are captured, it would be better to say "add
> new, removed, or modified files".
> 

The way I see it is that git add *captures* a part of the current state of the 
working tree (be it addition/removal of contents of files or subtrees of the 
working dir) for the next commit. A commit *is* a snapshot of the state of the 
project. The concept of snapshot is central to understanding the behavior of 
git and its internals.

> > +Add new or changed files to the index to prepare for a commit. The
> > +"index" (also known as "staging area") is where Git stores the changes
> > +that will be in the next commit.
> 
> I won't repeat myself about change-snapshot duality, but I do not
> think the new text is the best we can do.
> 
>     Update contents recorded in the index to prepare for the next
>     commit.  The index (also known as "staging area") is where Git
>     stores the contents that will be in the next commit.

Particularly, the "stores the changes that..." part is really not what the 
reader should remember.

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

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