Subject: Re: [PATCH v3 2/3] doc: git-add: clarify intro & add an example

From: "Julia Evans" <[email-masked]>
Date: Fri, 22 Aug 2025 16:37:21 -0400

"what you use to prepare the contents for the next commit" sounds
good to me, will make those changes.

On Thu, Aug 21, 2025, at 4:08 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <[email-masked]> writes:
>
>>  DESCRIPTION
>>  -----------
>> -This command updates the index using the current content found in
>> -the working tree, to prepare the content staged for the next commit.
>> -It typically adds the current content of existing paths as a whole,
>> -but with some options it can also be used to add content with
>> -only part of the changes made to the working tree files applied, or
>> -remove paths that do not exist in the working tree anymore.
>> -
>> -The "index" holds a snapshot of the content of the working tree, and it
>> -is this snapshot that is taken as the contents of the next commit.  Thus
>> -after making any changes to the working tree, and before running
>> -the commit command, you must use the `add` command to add any new or
>> -modified files to the index.
>> +Add contents of new or changed files to the index. The "index" (also
>> +known as "staging area") is where Git stores the contents of the next
>> +commit.
>
> Much nicer than the preimage text that is quite awkwardly phrased.
>
> I however would not say "Git stores the contents", as it is you the
> user who does the storing.  I may phrase it more like "... is what
> you use to prepare the contents for the next commit." probably.
>
>> +When you run `git commit` without any other arguments, it will only
>> +commit staged changes. For example, if you've edited `file.c` and want
>> +to commit your changes to that file, you can run:
>> +
>> +   git add file.c
>> +   git commit
>> +
>> +You can also add only part of your changes to a file with `git add -p`.
>
> Great.