From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>
Cc: "Julia Evans" <gitgitgadget@gmail•com>,
git@vger•kernel.org, "Chris Torek" <chris.torek@gmail•com>,
"D. Ben Knoble" <ben.knoble@gmail•com>,
"Jean-Noël AVILA" <jn.avila@free•fr>
Subject: Re: [PATCH v2 3/4] doc: git-add: make explanation less dry
Date: Tue, 19 Aug 2025 08:57:07 -0400 [thread overview]
Message-ID: <007dd7bb-352e-4682-8ca2-8256d9a47e07@app.fastmail.com> (raw)
In-Reply-To: <xmqqsehspdtr.fsf@gitster.g>
> 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"."
next prev parent reply other threads:[~2025-08-19 12:57 UTC|newest]
Thread overview: 59+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-08-12 20:07 [PATCH 0/5] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-12 20:07 ` [PATCH 1/5] doc: git-add: remove options from SYNOPSIS Julia Evans via GitGitGadget
2025-08-12 20:41 ` Junio C Hamano
2025-08-13 16:58 ` Julia Evans
2025-08-13 20:47 ` Jean-Noël AVILA
2025-08-12 20:07 ` [PATCH 2/5] doc: git-add: start man page with an example Julia Evans via GitGitGadget
2025-08-12 21:01 ` Junio C Hamano
2025-08-12 21:40 ` Julia Evans
2025-08-12 22:12 ` Junio C Hamano
2025-08-12 22:45 ` Julia Evans
2025-08-13 17:22 ` D. Ben Knoble
2025-08-14 0:41 ` Junio C Hamano
2025-08-14 2:59 ` Julia Evans
2025-08-15 5:38 ` Junio C Hamano
2025-08-12 20:07 ` [PATCH 3/5] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
2025-08-13 17:24 ` D. Ben Knoble
2025-08-12 20:07 ` [PATCH 4/5] doc: git-add: make explanation less dry Julia Evans via GitGitGadget
2025-08-12 20:07 ` [PATCH 5/5] doc: git-add: explain inconsistent terminology Julia Evans via GitGitGadget
2025-08-12 20:51 ` Chris Torek
2025-08-12 21:36 ` Junio C Hamano
2025-08-12 21:43 ` Julia Evans
2025-08-13 23:20 ` [PATCH v2 0/4] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-13 23:20 ` [PATCH v2 1/4] doc: git-add: start man page with an example Julia Evans via GitGitGadget
2025-08-15 0:38 ` Junio C Hamano
2025-08-15 13:34 ` Jean-Noël AVILA
2025-08-15 16:33 ` Junio C Hamano
2025-08-17 18:37 ` Jean-Noël AVILA
2025-08-19 20:01 ` Julia Evans
2025-08-13 23:20 ` [PATCH v2 2/4] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
2025-08-14 0:59 ` D. Ben Knoble
2025-08-14 22:10 ` Junio C Hamano
2025-08-13 23:20 ` [PATCH v2 3/4] doc: git-add: make explanation less dry Julia Evans via GitGitGadget
2025-08-14 22:22 ` Junio C Hamano
2025-08-15 16:10 ` Julia Evans
2025-08-15 18:25 ` D. Ben Knoble
2025-08-15 20:01 ` Junio C Hamano
2025-08-16 14:15 ` D. Ben Knoble
2025-08-15 19:47 ` Junio C Hamano
2025-08-19 12:57 ` Julia Evans [this message]
2025-08-21 20:36 ` Jean-Noël AVILA
2025-08-13 23:20 ` [PATCH v2 4/4] doc: git-add: explain inconsistent terminology Julia Evans via GitGitGadget
2025-08-14 22:49 ` Junio C Hamano
2025-08-19 20:09 ` Julia Evans
2025-08-19 20:46 ` [PATCH v3 0/3] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-19 20:46 ` [PATCH v3 1/3] Git 2.51 Junio C Hamano via GitGitGadget
2025-08-19 21:06 ` rsbecker
2025-08-19 21:37 ` Junio C Hamano
2025-08-19 21:44 ` D. Ben Knoble
2025-08-19 21:48 ` Julia Evans
2025-08-19 21:49 ` rsbecker
2025-08-19 20:46 ` [PATCH v3 2/3] doc: git-add: clarify intro & add an example Julia Evans via GitGitGadget
2025-08-21 20:08 ` Junio C Hamano
2025-08-22 20:37 ` Julia Evans
2025-08-19 20:46 ` [PATCH v3 3/3] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
2025-08-21 20:09 ` Junio C Hamano
2025-08-29 11:55 ` [PATCH v4 0/2] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-29 11:55 ` [PATCH v4 1/2] doc: git-add: clarify intro & add an example Julia Evans via GitGitGadget
2025-08-29 11:55 ` [PATCH v4 2/2] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
2025-08-29 17:11 ` [PATCH v4 0/2] doc: git-add: clarify DESCRIPTION section Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=007dd7bb-352e-4682-8ca2-8256d9a47e07@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=ben.knoble@gmail$(echo .)com \
--cc=chris.torek@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=gitster@pobox$(echo .)com \
--cc=jn.avila@free$(echo .)fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox