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

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Tuesday, 19 August 2025 14:57:07 CEST Julia Evans wrote:
> > 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.
> 
> 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 
a
>   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. 
A
>    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?
>    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
> 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.