On Friday, 15 August 2025 02:38:45 CEST Junio C Hamano wrote: > "Julia Evans via GitGitGadget" <gitgitgadget@xxxxxxxxx> 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".
