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.
