Re: [PATCH 2/5] doc: git-add: start man page with an example

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 12, 2025, 21:01 UTC
Message-ID: <xmqqbjoks19f.fsf@gitster.g>
In-Reply-To: <310d2c1d8f7f68ae52ddd29f0ccb0a0364aba1a2.1755029249.git.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 5 quoted lines

> - Remove the snapshot-based explanation of the index and replace it with
>   a diff-based explanation because I don't feel that it's useful in this
>   context to emphasize that git uses a snapshot-based model: the main
>   way most git users interact with the index is through `git diff` or
>   `git status`, which is a completely diff-based view of the index.

But isn't it the source of the most end-user confusion that they cannot wean themselves off of the diff/patch worldview?

How would you explain what the users would see in their "git diff", "git diff --cached", and "git commit" after doing "edit && add && edit", if you explain "add" to be storing the "diff" made by the first edit? Does their "git diff" after the second "edit" take that previously stored "diff" and another "diff" made by the second "edit" and magically combine them together to present a single "diff"?

> -git-add - Add file contents to the index
> +git-add - Add new or changed files to the index

In other words, I do think "new or changed" is a good thing to say, but the word "contents" is fundamental here. "Add contents of new or changed files to the index" would be good.

> +Add new or changed files to the index (also known as "staging area") to
> +prepare for a commit.

OK, but saying "files" here adds another kind of confusion. What is "added" is not the fact that these paths are kept track of by Git. Instead we add the snapshot of the contents at the time of 'git add'.

Wouldn't "add file X" confuse folks who still remember how other SCMs before Git operated (i.e. "file X is now known, so if I make further changes to X next 'commit' command will record it") into thinking that Git would do the same?

Show 6 quoted lines

> +By default, `git commit` only commits changes that you've added to the
> +index. For example, if you've edited `file.c` and want to commit your
> +changes, you can run:
> +
> +   git add file.c
> +   git commit

What happens when you did "edit && add && edit && add"? It commits the two changes you added to the index? I do not think it is productive to hide the fact that you are preparing a snapshot of the "next commit" in the index (or "staging the contents for the next commit in the staging area") with various forms "git add", including "git add -p".

And to help form that mental model, it would help to avoid phrasing "commit your changes" (as if you are somehow dealing with "diff/patch") and instead saying "commit the result of your changes" (stressing that the "state" matters), I would think.

De-stressing the fact that we are taking a snapshot should probably be considered a documentation regression here. Thanks to "git add" taking a snapshot, users can further make experimental changes in the working tree files freely and then come back to the exact contents back by checking the path out of the index with "git checkout -- <path>". Thanks to "git commit" taking a snapshot, users can even go back to the last commit by taking the exact contents back by checking the path out of the HEAD with "git checkout HEAD -- <path>".

I'll stop here and let others express their opinions without further commenting for now.

Thanks for working on these updates.