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

[Junio C Hamano <gitster@pobox.com>]

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

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

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