> 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"" Comments not related to the term "index": * "Would prefer something more direct like "git lets you gradually build the contents of the next commit by adding things to the staging area..."" * "I wish this came first in the description." * One person said they appreciated "you must use the add command [after making any changes]", since that confused them when they started using git > This command can be performed multiple times before a commit. It only adds the > content of the specified file(s) at the time the add command is run; if you > want subsequent changes included in the next commit, then you must run git add > again to add the new content to the index. No comments other than "Can be improved to be more clear." > Ignored files reached by directory recursion or filename globbing performed > by Git (quote your globs before the shell) 4 people did not understand what "(quote your globs before the shell)" meant. ("Does it mean that I need to escape glob quotation marks?"). > The git status command can be used to obtain a summary of which files have > changes that are staged for the next commit. Nobody said they were confused by this. One person said they were happy it was mentioned, and one person suggested replacing "obtain" with "get". Things people said they learned from the man page: 1. "I did not know that the globs would be treated potentially differently if expanded by the shell before getting to git." 2. "I never knew git could do globbing." 3. "I didn't know you could remove paths with add" Things people suggested adding: 1. "This should also document how to undo the effects of "git add". I'm always confused between how best to do so between "git restore" and "git reset"."
