Re: [PATCH v2 3/4] doc: git-add: make explanation less dry

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Aug 21, 2025, 20:36 UTC
Message-ID: <2320029.iZASKD2KPV@cayenne>
In-Reply-To: <007dd7bb-352e-4682-8ca2-8256d9a47e07@app.fastmail.com>

On Tuesday, 19 August 2025 14:57:07 CEST Julia Evans wrote:

Show 6 quoted lines

> > Yes, you can lose your novice status and it is hard to take it back
> > ;-)  I agree with you that the next best thing you can do is to see
> > how well folks who still have that status do.
> 
> I've returned with some data! I got feedback on the `git-add` man page from
> 13 Git users. It's a group of pretty experienced users: half of them have

been

> using Git for 5-10 years, and about half for 10+ years. Even though there

are

> no "novices" here, they still provided useful feedback about what's

confusing.

Show 5 quoted lines

> 
> Here's what I took away from the feedback and a summary of the comments.
> First, what I took away:
> 
> * The term "index" is hard to understand even for very experienced Git

users,

>   and even for some users who say that they are extremely comfortable with

Git.

> * The second sentence in the man page is too long and hard to parse.
> * The "(quote your globs before the shell)" phrasing is confusing.
> * I thought mentioning that you can use `git reset` to undo a `git add` was

Show 8 quoted lines

>   good idea.
> * Leaving something similar to the existing phrasing around "snapshot" seems
>   fine, nobody in this group was confused, though of course this is a group
>   of people who already understand how `git add` works.
> 
> Here's my summary of the comments on the existing man page. I collected them
> using this little tool I built: https://text-feedback.wizardzines.com/git-add/.
> I'm happy to also figure out how to best share the "raw" comments if folks

would

> find that helpful. I've quoted the current man page text for context.
> 
> > 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.

> 
> This was the paragraph with the most "this is confusing" comments. Here are

the

> main themes:
> 
> 1. 7 people (more than half) said that they find the term "index" confusing.

>    few example quotes:
>    * "updates the index" sounds like it increments something"
>    * "Is the index not just the content that is staged for commit? Do I as

an

> 	 end user need to care about the difference? I've not heard the

staged

> 	 content referred to as the index before, even in git command

outputs."

> 2. 3 people said the second sentence is too long and hard to parse
> 3. 2 people said that "It *typically* adds the current content of existing
>    paths" is confusing (What's meant by "typically"? When does it not do

that?

Show 9 quoted lines

>    is this referring to git add -A?)
> 
> > 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.
> 
> Nobody said they were confused by this, other than continued confusion

around

Show 5 quoted lines

> the term "index", like:
> 
> * "Why quotes around "index" here but not when I first encounter the word
>   index?"
> * "I'm guessing index is used through git man pages and staging area is a

newer

>   way of saying this 🤔"
> * "Can we just say staging area? I don't think of adding changes to the

"index""

For the term index, the glossary-contents.adoc file says:
[[def_index]]index::
	A collection of files with stat information, whose contents are 
stored
	as objects. The index is a stored version of your
	<<def_working_tree,working tree>>. Truth be told, it can also 
contain a second, and even
	a third version of a working tree, which are used
	when <<def_merge,merging>>.

"Truth to be told", this definition of the index makes things even muddier to me.

If I understand correctly the first ages of git, it seems that the index was a file containing the list of the staged files (deletion included) with their stat information and hash, the actual file contents being stored in the cache. So it was like an index for a book, keeping track of the name of changed files with pointers to the contents of modified ones.