* [PATCH v2 1/4] doc: git-add: start man page with an example
2025-08-13 23:20 ` [PATCH v2 0/4] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
@ 2025-08-13 23:20 ` Julia Evans via GitGitGadget
2025-08-15 0:38 ` Junio C Hamano
2025-08-13 23:20 ` [PATCH v2 2/4] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
` (3 subsequent siblings)
4 siblings, 1 reply; 59+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-08-13 23:20 UTC (permalink / raw)
To: git
Cc: Chris Torek, D. Ben Knoble, Jean-Noël AVILA, Julia Evans,
Julia Evans
From: Julia Evans <julia@jvns.ca>
- Replace the intro paragraph of the `git-add` man page with an
example to try to clarify it for new users. The goal here is use less
jargon but communicate essentially the same information.
- Give an example of how to add only part of the changes to the file
- Remove the snapshot-based explanation of the index and replace it with
a diff-based explanation because I don't feel that it's useful in this
context to emphasize that git uses a snapshot-based model: the main
way most git users interact with the index is through `git diff` or
`git status`, which is a completely diff-based view of the index.
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-add.adoc | 32 +++++++++++++++-----------------
1 file changed, 15 insertions(+), 17 deletions(-)
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index b7a735824d6c..949b016e6fa2 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -3,7 +3,7 @@ git-add(1)
NAME
----
-git-add - Add file contents to the index
+git-add - Add new or changed files to the index
SYNOPSIS
--------
@@ -16,18 +16,20 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-
DESCRIPTION
-----------
-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.
-
-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.
+Add new or changed files to the index to prepare for a commit. The
+"index" (also known as "staging area") is where Git stores the changes
+that will be in the next commit.
+
+By default, `git commit` only commits changes that you've added to the
+index. For example, if you've edited `file.c` and want to commit your
+changes, you can run:
+
+ git add file.c
+ git commit
+
+You can also add only part of your changes to a file with `git add -p`.
+Please see linkgit:git-commit[1] for alternative ways to add content to
+a commit.
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
@@ -44,10 +46,6 @@ directory recursion or filename globbing performed by Git (quote your
globs before the shell) will be silently ignored. The `git add` command can
be used to add ignored files with the `-f` (force) option.
-Please see linkgit:git-commit[1] for alternative ways to add content to a
-commit.
-
-
OPTIONS
-------
`<pathspec>...`::
--
gitgitgadget
^ permalink raw reply related [flat|nested] 59+ messages in thread* Re: [PATCH v2 1/4] doc: git-add: start man page with an example
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
0 siblings, 1 reply; 59+ messages in thread
From: Junio C Hamano @ 2025-08-15 0:38 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, Chris Torek, D. Ben Knoble, Jean-Noël AVILA,
Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> -git-add - Add file contents to the index
> +git-add - Add new or changed files to the index
Does it add much value to say "new or changed" here? The command can
also be used to "stage" a removal of a path, e.g.
$ rm tracked-file
$ git add -u
so if the updated text is an attempt to give more details on what
kind of modifications are captured, it would be better to say "add
new, removed, or modified files".
> +Add new or changed files to the index to prepare for a commit. The
> +"index" (also known as "staging area") is where Git stores the changes
> +that will be in the next commit.
I won't repeat myself about change-snapshot duality, but I do not
think the new text is the best we can do.
Update contents recorded in the index to prepare for the next
commit. The index (also known as "staging area") is where Git
stores the contents that will be in the next commit.
> +By default, `git commit` only commits changes that you've added to the
> +index.
> For example, if you've edited `file.c` and want to commit your
> +changes, you can run:
Likewise. "and want to record the resulting contents".
> ...
> -Please see linkgit:git-commit[1] for alternative ways to add content to a
> -commit.
In the original, this comment does look a bit out of place (as the
text around there does not talk about `git commit`), but as you said
that by default 'git commit' makes an as-is commit above, it may be
a good idea to move this sentence there. `git commit <pathspec>` is
a handy thing to know even for beginners, and making your next commit
is what the user is working towards by using "git add".
^ permalink raw reply [flat|nested] 59+ messages in thread* Re: [PATCH v2 1/4] doc: git-add: start man page with an example
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
0 siblings, 1 reply; 59+ messages in thread
From: Jean-Noël AVILA @ 2025-08-15 13:34 UTC (permalink / raw)
To: Julia Evans via GitGitGadget, Junio C Hamano
Cc: git, Chris Torek, D. Ben Knoble, Julia Evans
On Friday, 15 August 2025 02:38:45 CEST Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> > -git-add - Add file contents to the index
> > +git-add - Add new or changed files to the index
>
> Does it add much value to say "new or changed" here? The command can
> also be used to "stage" a removal of a path, e.g.
>
> $ rm tracked-file
> $ git add -u
>
> so if the updated text is an attempt to give more details on what
> kind of modifications are captured, it would be better to say "add
> new, removed, or modified files".
>
The way I see it is that git add *captures* a part of the current state of the
working tree (be it addition/removal of contents of files or subtrees of the
working dir) for the next commit. A commit *is* a snapshot of the state of the
project. The concept of snapshot is central to understanding the behavior of
git and its internals.
> > +Add new or changed files to the index to prepare for a commit. The
> > +"index" (also known as "staging area") is where Git stores the changes
> > +that will be in the next commit.
>
> I won't repeat myself about change-snapshot duality, but I do not
> think the new text is the best we can do.
>
> Update contents recorded in the index to prepare for the next
> commit. The index (also known as "staging area") is where Git
> stores the contents that will be in the next commit.
Particularly, the "stores the changes that..." part is really not what the
reader should remember.
>
> > +By default, `git commit` only commits changes that you've added to the
> > +index.
I do not understand this addition. I may not be missing knowledge, but this
behavior is not only "by default", it's the only behavior of git: commits are
made with the content of the index. Let's not make it more complicated than it
is already.
> > For example, if you've edited `file.c` and want to commit your
>
> > +changes, you can run:
> Likewise. "and want to record the resulting contents".
>
> > ...
> > -Please see linkgit:git-commit[1] for alternative ways to add content to a
> > -commit.
>
> In the original, this comment does look a bit out of place (as the
> text around there does not talk about `git commit`), but as you said
> that by default 'git commit' makes an as-is commit above, it may be
> a good idea to move this sentence there. `git commit <pathspec>` is
> a handy thing to know even for beginners, and making your next commit
> is what the user is working towards by using "git add".
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v2 1/4] doc: git-add: start man page with an example
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
0 siblings, 1 reply; 59+ messages in thread
From: Junio C Hamano @ 2025-08-15 16:33 UTC (permalink / raw)
To: Jean-Noël AVILA
Cc: Julia Evans via GitGitGadget, git, Chris Torek, D. Ben Knoble,
Julia Evans
Jean-Noël AVILA <jn.avila@free.fr> writes:
> On Friday, 15 August 2025 02:38:45 CEST Junio C Hamano wrote:
>> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>> ...
>> > +By default, `git commit` only commits changes that you've added to the
>> > +index.
>
> I do not understand this addition. I may not be missing knowledge, but this
> behavior is not only "by default", it's the only behavior of git: commits are
> made with the content of the index. Let's not make it more complicated than it
> is already.
I'll only react to "the only behaviour" part, without "more
complicated" part.
I think Julia is referring to the fact that you can record the state
that is different from what is in the index (or, what has been
accumulated in the index by the past use of "git add" command that
is being discussed here) with "git commit [-i] <pathspec>". You can
do
$ edit fileA fileB ;# assume both are tracked
$ git add fileA
$ git commit fileB
and the resulting commit will record the contents for fileA found in
its parent (i.e. the result of "git add fileA" is not reflected).
If the last step were
$ git commit -i fileB
then the resulting commit will record the contents for both fileA
you added with the last "git add" on it, and contents for fileB
found in the working tree at the time of "git commit -i" was run
(i.e. "git add fileB" was not required)..
By default, after the edit of fileA&B and the add of fileA, "git
commit" would not be aware of what is currently in fileB in the
working tree, and records the same contents as its parent for all
paths except for fileA, which would record what was last added with
"git add" to the index.
>> > For example, if you've edited `file.c` and want to commit your
>>
>> > +changes, you can run:
>> Likewise. "and want to record the resulting contents".
>>
>> > ...
>> > -Please see linkgit:git-commit[1] for alternative ways to add content to a
>> > -commit.
>>
>> In the original, this comment does look a bit out of place (as the
>> text around there does not talk about `git commit`), but as you said
>> that by default 'git commit' makes an as-is commit above, it may be
>> a good idea to move this sentence there. `git commit <pathspec>` is
>> a handy thing to know even for beginners, and making your next commit
>> is what the user is working towards by using "git add".
And this relates to "more complicated" part of your comment.
I think keeping "by default" above and also keeping this comment
that hints about non-as-is commits made with "git commit <pathspec>"
is slightly more preferrable than dropping both of them altogether.
With only four additional lines, we cover basic "edit && add && commit"
cycle fairly completely.
I am also fine to drop the mention of 'git commit' altogether, but
it feels somewhat incomplete to not talk about commit when teaching
add. After all, add is one of the primary ways to prepare for the
next commit---putting it the other way around, you want to learn add
primarily because you eventually would want to make a commit.
In any case, only having one (i.e. "by default") and dropping the
other ("see linkgit:git-commit"), like the patch did, did not make
much sense to me.
Thanks.
^ permalink raw reply [flat|nested] 59+ messages in thread* Re: [PATCH v2 1/4] doc: git-add: start man page with an example
2025-08-15 16:33 ` Junio C Hamano
@ 2025-08-17 18:37 ` Jean-Noël AVILA
2025-08-19 20:01 ` Julia Evans
0 siblings, 1 reply; 59+ messages in thread
From: Jean-Noël AVILA @ 2025-08-17 18:37 UTC (permalink / raw)
To: Junio C Hamano
Cc: Julia Evans via GitGitGadget, git, Chris Torek, D. Ben Knoble,
Julia Evans
On Friday, 15 August 2025 18:33:47 CEST Junio C Hamano wrote:
> Jean-Noël AVILA <jn.avila@free.fr> writes:
> > On Friday, 15 August 2025 02:38:45 CEST Junio C Hamano wrote:
> >> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> >> ...
> >>
> >> > +By default, `git commit` only commits changes that you've added to the
> >> > +index.
> >
> > I do not understand this addition. I may not be missing knowledge, but
this
> > behavior is not only "by default", it's the only behavior of git: commits
are
> > made with the content of the index. Let's not make it more complicated
than it
> > is already.
>
> I'll only react to "the only behaviour" part, without "more
> complicated" part.
>
> I think Julia is referring to the fact that you can record the state
> that is different from what is in the index (or, what has been
> accumulated in the index by the past use of "git add" command that
> is being discussed here) with "git commit [-i] <pathspec>". You can
> do
>
> $ edit fileA fileB ;# assume both are tracked
> $ git add fileA
> $ git commit fileB
>
> and the resulting commit will record the contents for fileA found in
> its parent (i.e. the result of "git add fileA" is not reflected).
> If the last step were
>
> $ git commit -i fileB
>
> then the resulting commit will record the contents for both fileA
> you added with the last "git add" on it, and contents for fileB
> found in the working tree at the time of "git commit -i" was run
> (i.e. "git add fileB" was not required)..
>
> By default, after the edit of fileA&B and the add of fileA, "git
> commit" would not be aware of what is currently in fileB in the
> working tree, and records the same contents as its parent for all
> paths except for fileA, which would record what was last added with
> "git add" to the index.
>
Thanks for the explanation, I had forgotten this form of git commit. For the
record, when I teach about add/commit, I never talk about the direct commit
form, to present things in the most repeatable/unambiguous form.
The `git commit <pathspec>` form may be of use for old-timers who were doing
so with previous SCMs. But as stated elsewhere, young newcomers do not have to
fight against finger memory. The explanation that you provided describes a
quite complicated process with options, so this feature seems to be reserved
to advanced users.
The manual pages in section 1 are mostly reference stuff for a given command,
and this way of referring here to alternate usage of git commit is a bit off-
topic to me. For how to organize workflows, there are some pages in section 7.
My stance is as follow: yes, being complete is important in a reference piece
of documentation, but throwing a "by default" on `git commit` here, without
further explanation, sends the reader in an unsure state, which is detrimental
to understanding at this early stage of the documentation.
Otherwise, the idea of the simple example as an introduction is a good
addition before delving into more formal and comprehensive explanation. The
only caveat is to not introduce wrong concepts that may need to be reverted
later.
> >> > For example, if you've edited `file.c` and want to commit your
> >>
> >> > +changes, you can run:
> >> Likewise. "and want to record the resulting contents".
> >>
> >> > ...
> >> > -Please see linkgit:git-commit[1] for alternative ways to add content
to a
> >> > -commit.
> >>
> >> In the original, this comment does look a bit out of place (as the
> >> text around there does not talk about `git commit`), but as you said
> >> that by default 'git commit' makes an as-is commit above, it may be
> >> a good idea to move this sentence there. `git commit <pathspec>` is
> >> a handy thing to know even for beginners, and making your next commit
> >> is what the user is working towards by using "git add".
>
> And this relates to "more complicated" part of your comment.
>
> I think keeping "by default" above and also keeping this comment
> that hints about non-as-is commits made with "git commit <pathspec>"
> is slightly more preferrable than dropping both of them altogether.
> With only four additional lines, we cover basic "edit && add && commit"
> cycle fairly completely.
>
> I am also fine to drop the mention of 'git commit' altogether, but
> it feels somewhat incomplete to not talk about commit when teaching
> add. After all, add is one of the primary ways to prepare for the
> next commit---putting it the other way around, you want to learn add
> primarily because you eventually would want to make a commit.
>
> In any case, only having one (i.e. "by default") and dropping the
> other ("see linkgit:git-commit"), like the patch did, did not make
> much sense to me.
>
> Thanks.
I'm not for dropping them, but for deferring the mention of this special
workflow later in the explanation, with the reference to `git commit`.
BR
Jean-Noël
^ permalink raw reply [flat|nested] 59+ messages in thread* Re: [PATCH v2 1/4] doc: git-add: start man page with an example
2025-08-17 18:37 ` Jean-Noël AVILA
@ 2025-08-19 20:01 ` Julia Evans
0 siblings, 0 replies; 59+ messages in thread
From: Julia Evans @ 2025-08-19 20:01 UTC (permalink / raw)
To: Jean-Noël AVILA, Junio C Hamano
Cc: Julia Evans, git, Chris Torek, D. Ben Knoble
>> I think Julia is referring to the fact that you can record the state
>> that is different from what is in the index (or, what has been
>> accumulated in the index by the past use of "git add" command that
>> is being discussed here) with "git commit [-i] <pathspec>". You can
>> do
>>
>> $ edit fileA fileB ;# assume both are tracked
>> $ git add fileA
>> $ git commit fileB
I was actually thinking of `git commit -a`, but it amounts to the same thing.
I'm going to remove the "By default": I agree it introduces some
unnecessary confusion, similar to the "It typically adds..." in the current
version of the man page. I'll instead be more explicit:
"When you run `git commit` without any other arguments.."
^ permalink raw reply [flat|nested] 59+ messages in thread
* [PATCH v2 2/4] doc: git-add: simplify discussion of ignored files
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-13 23:20 ` 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
` (2 subsequent siblings)
4 siblings, 2 replies; 59+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-08-13 23:20 UTC (permalink / raw)
To: git
Cc: Chris Torek, D. Ben Knoble, Jean-Noël AVILA, Julia Evans,
Julia Evans
From: Julia Evans <julia@jvns.ca>
- Mention the --force option earlier
- Remove the explanation of shell globbing vs git's internal glob
system, it's a common gotcha but I don't think this is an appropriate
place to explain that concept. There's some discussion of the gotchas
around globbing and `git add` in the EXAMPLES section which I think
is clearer.
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-add.adoc | 11 +++++------
1 file changed, 5 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index 949b016e6fa2..75e223f6b1ea 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -39,12 +39,11 @@ you must run `git add` again to add the new content to the index.
The `git status` command can be used to obtain a summary of which
files have changes that are staged for the next commit.
-The `git add` command will not add ignored files by default. If any
-ignored files were explicitly specified on the command line, `git add`
-will fail with a list of ignored files. Ignored files reached by
-directory recursion or filename globbing performed by Git (quote your
-globs before the shell) will be silently ignored. The `git add` command can
-be used to add ignored files with the `-f` (force) option.
+`git add` will not add ignored files by default. You can use the
+`--force` option to add ignored files. If you explicitly specify the
+exact filename of an ignored file (e.g. `git add ignored.txt`), `git
+add` will fail with a list of ignored files. Otherwise it will silently
+ignore the file.
OPTIONS
-------
--
gitgitgadget
^ permalink raw reply related [flat|nested] 59+ messages in thread* Re: [PATCH v2 2/4] doc: git-add: simplify discussion of ignored files
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
1 sibling, 0 replies; 59+ messages in thread
From: D. Ben Knoble @ 2025-08-14 0:59 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, Chris Torek, Jean-Noël AVILA, Julia Evans
On Wed, Aug 13, 2025 at 7:20 PM Julia Evans via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Julia Evans <julia@jvns.ca>
>
> - Mention the --force option earlier
> - Remove the explanation of shell globbing vs git's internal glob
> system, it's a common gotcha but I don't think this is an appropriate
> place to explain that concept. There's some discussion of the gotchas
> around globbing and `git add` in the EXAMPLES section which I think
> is clearer.
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
> Documentation/git-add.adoc | 11 +++++------
> 1 file changed, 5 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
> index 949b016e6fa2..75e223f6b1ea 100644
> --- a/Documentation/git-add.adoc
> +++ b/Documentation/git-add.adoc
> @@ -39,12 +39,11 @@ you must run `git add` again to add the new content to the index.
> The `git status` command can be used to obtain a summary of which
> files have changes that are staged for the next commit.
>
> -The `git add` command will not add ignored files by default. If any
> -ignored files were explicitly specified on the command line, `git add`
> -will fail with a list of ignored files. Ignored files reached by
> -directory recursion or filename globbing performed by Git (quote your
> -globs before the shell) will be silently ignored. The `git add` command can
> -be used to add ignored files with the `-f` (force) option.
> +`git add` will not add ignored files by default. You can use the
Not worth a re-roll on its own, but this is another instance where
starting a sentence with `git add` seems odd to me.
The range-diff in v2 looked good to me overall.
--
D. Ben Knoble
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v2 2/4] doc: git-add: simplify discussion of ignored files
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
1 sibling, 0 replies; 59+ messages in thread
From: Junio C Hamano @ 2025-08-14 22:10 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, Chris Torek, D. Ben Knoble, Jean-Noël AVILA,
Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> -The `git add` command will not add ignored files by default. If any
> -ignored files were explicitly specified on the command line, `git add`
> -will fail with a list of ignored files. Ignored files reached by
> -directory recursion or filename globbing performed by Git (quote your
> -globs before the shell) will be silently ignored. The `git add` command can
> -be used to add ignored files with the `-f` (force) option.
> +`git add` will not add ignored files by default. You can use the
> +`--force` option to add ignored files. If you explicitly specify the
> +exact filename of an ignored file (e.g. `git add ignored.txt`), `git
> +add` will fail with a list of ignored files. Otherwise it will silently
> +ignore the file.
I think we no longer need to say "explicitly" now that we added
"exact".
The earlier text used "explicitly" because it wanted to say that
"git add t/ 'ig*.txt'" silently ignores "t/ignored-file.txt" and
"ignored-file.txt" because these files are not explicitly named
(they were only implicitly named via recursion or globbing). Your
new wording "exact filename" already covers these cases.
Do we discuss that "git add t/" attempts to add everything that is
not ignored under the t/ directory elsewhere in this document after
these patches? If we do, then I am 100% OK with the decision to
stop talking about globs and recursion in this paragraph. Otherwise,
I would want to see some mention of this "naming directory names its
contents recursively" somewhere in the document (it does not have to
be, but can naturally be, in this paragraph).
Thanks.
^ permalink raw reply [flat|nested] 59+ messages in thread
* [PATCH v2 3/4] doc: git-add: make explanation less dry
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-13 23:20 ` [PATCH v2 2/4] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
@ 2025-08-13 23:20 ` Julia Evans via GitGitGadget
2025-08-14 22:22 ` Junio C Hamano
2025-08-13 23:20 ` [PATCH v2 4/4] doc: git-add: explain inconsistent terminology Julia Evans via GitGitGadget
2025-08-19 20:46 ` [PATCH v3 0/3] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
4 siblings, 1 reply; 59+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-08-13 23:20 UTC (permalink / raw)
To: git
Cc: Chris Torek, D. Ben Knoble, Jean-Noël AVILA, Julia Evans,
Julia Evans
From: Julia Evans <julia@jvns.ca>
- use examples
- mention `git diff --staged`
- link to git diff man page
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-add.adoc | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index 75e223f6b1ea..6a6f5223419f 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -31,13 +31,13 @@ You can also add only part of your changes to a file with `git add -p`.
Please see linkgit:git-commit[1] for alternative ways to add content to
a commit.
-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.
+The `git add` command only adds the changes at the time that you run it.
+If you edit `file.c` after adding it, you need to run `git add file.c`
+again before committing.
-The `git status` command can be used to obtain a summary of which
-files have changes that are staged for the next commit.
+If you want to check which changes have been added, you can run
+`git status` to print out a summary of the changes that will be committed
+or run `git diff --staged` to see the full diff.
`git add` will not add ignored files by default. You can use the
`--force` option to add ignored files. If you explicitly specify the
@@ -448,6 +448,7 @@ linkgit:git-rm[1]
linkgit:git-reset[1]
linkgit:git-mv[1]
linkgit:git-commit[1]
+linkgit:git-diff[1]
linkgit:git-update-index[1]
GIT
--
gitgitgadget
^ permalink raw reply related [flat|nested] 59+ messages in thread
* Re: [PATCH v2 3/4] doc: git-add: make explanation less dry
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
0 siblings, 1 reply; 59+ messages in thread
From: Junio C Hamano @ 2025-08-14 22:22 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, Chris Torek, D. Ben Knoble, Jean-Noël AVILA,
Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> -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.
> +The `git add` command only adds the changes at the time that you run it.
> +If you edit `file.c` after adding it, you need to run `git add file.c`
> +again before committing.
I somehow find the text before this change easier to understand
(except for one thing). "If you edit `file.c` after adding it" in
the new text says the same thing as "if you want subsequent ... in
the next commit" in the original but in a much better way.
> -The `git status` command can be used to obtain a summary of which
> -files have changes that are staged for the next commit.
> +If you want to check which changes have been added, you can run
> +`git status` to print out a summary of the changes that will be committed
> +or run `git diff --staged` to see the full diff.
Rewrite "diff --staged" to "diff --cached", simply because that is
how "git diff -h" shows. After all, "--staged" is explained as a
"synonym" (and by definition, a synonym is something that you do not
have to use, as you can use the real thing).
"status" gives paths in two groups, "changes to be committed" and
"changes not staged for commit". Explaining the use of "diff
--cached" to inspect what the user will be committing is a great
addition here, as it is a sensible way to sanity-check the result of
your index manipulations. In addition, we also should talk about
"diff" to inspect what the user will be leaving out---in other
words, what the user might have forgotten to add, which is equally
if not more useful sanity-check you can do before you commit.
Thanks.
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v2 3/4] doc: git-add: make explanation less dry
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 19:47 ` Junio C Hamano
0 siblings, 2 replies; 59+ messages in thread
From: Julia Evans @ 2025-08-15 16:10 UTC (permalink / raw)
To: Junio C Hamano, Julia Evans
Cc: git, Chris Torek, D. Ben Knoble, Jean-Noël AVILA
Hi,
> I somehow find the text before this change easier to understand
> (except for one thing). "If you edit `file.c` after adding it" in
> the new text says the same thing as "if you want subsequent ... in
> the next commit" in the original but in a much better way.
I really appreciate all of this feedback. It makes me wonder if there would
be a better way to approach this man page. Usually when I'm revising a technical
explanation, I find people who are currently users of the software but who have
trouble understanding how it works. Then I ask them to give feedback on what's
confusing to them about the explanation or what questions they have.
I do this because I find that often people who are extremely comfortable
with using the software (including me, which is why I usually spend so much
time collecting feedback like this!) can lose sight of what's confusing to an
"average user". And every time I'm part of a discussion about documentation for
an open source project it seems a bit strange to me for a group of people who
all already understand the concept to be discussing what would be clearest to an
"average user": surely the users themselves should be the judge of what's clear
to them!
I'm still pretty new to writing open source documentation so I don't know if
collecting user feedback like this is a normal part of the process, but I always
learn a lot from this type of feedback and it's pretty easy for me to collect
it.
> Rewrite "diff --staged" to "diff --cached"
Will use `diff --cached`.
> In addition, we also should talk about
> "diff" to inspect what the user will be leaving out---in other
> words, what the user might have forgotten to add, which is equally
> if not more useful sanity-check you can do before you commit.
That makes sense to me.
best,
Julia
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v2 3/4] doc: git-add: make explanation less dry
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-15 19:47 ` Junio C Hamano
1 sibling, 1 reply; 59+ messages in thread
From: D. Ben Knoble @ 2025-08-15 18:25 UTC (permalink / raw)
To: Julia Evans
Cc: Junio C Hamano, Julia Evans, git, Chris Torek,
Jean-Noël AVILA
On Fri, Aug 15, 2025 at 12:10 PM Julia Evans <julia@jvns.ca> wrote:
>
> Hi,
>
> > I somehow find the text before this change easier to understand
> > (except for one thing). "If you edit `file.c` after adding it" in
> > the new text says the same thing as "if you want subsequent ... in
> > the next commit" in the original but in a much better way.
>
> I really appreciate all of this feedback. It makes me wonder if there would
> be a better way to approach this man page. Usually when I'm revising a technical
> explanation, I find people who are currently users of the software but who have
> trouble understanding how it works. Then I ask them to give feedback on what's
> confusing to them about the explanation or what questions they have.
>
> I do this because I find that often people who are extremely comfortable
> with using the software (including me, which is why I usually spend so much
> time collecting feedback like this!) can lose sight of what's confusing to an
> "average user".
The curse of knowledge ;)
> And every time I'm part of a discussion about documentation for
> an open source project it seems a bit strange to me for a group of people who
> all already understand the concept to be discussing what would be clearest to an
> "average user": surely the users themselves should be the judge of what's clear
> to them!
>
> I'm still pretty new to writing open source documentation so I don't know if
> collecting user feedback like this is a normal part of the process, but I always
> learn a lot from this type of feedback and it's pretty easy for me to collect
> it.
Whether it is or isn't normal, we could probably still benefit from
that perspective.
As Junio likes to say, a mistake being old is no good reason to carry
it forward into the future (or replicate it). I'll take that to mean
we also have an opportunity to improve the inputs to documentation (as
"leaving out such a perspective" would be the "mistake"—note I'm not
ascribing intent, malicious or otherwise!).
--
D. Ben Knoble
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v2 3/4] doc: git-add: make explanation less dry
2025-08-15 18:25 ` D. Ben Knoble
@ 2025-08-15 20:01 ` Junio C Hamano
2025-08-16 14:15 ` D. Ben Knoble
0 siblings, 1 reply; 59+ messages in thread
From: Junio C Hamano @ 2025-08-15 20:01 UTC (permalink / raw)
To: D. Ben Knoble
Cc: Julia Evans, Julia Evans, git, Chris Torek, Jean-Noël AVILA
"D. Ben Knoble" <ben.knoble@gmail.com> writes:
> As Junio likes to say, a mistake being old is no good reason to carry
> it forward into the future (or replicate it).
I say no such thing, though. What I say about past mistakes is that
you shouldn't use it as an excuse to make similar ones in the
future.
I'd prefer to let a sleeping dog lie.
But in the context of this discussion, I think what we carefully and
honestly need to look at are not past mistakes. It is importance to
adjust to the new world we live in.
In early days of Git, people from older SCM systems did not grok the
index very well, so our explanation of the concept of index and
adding content to it may have focused on teaching the difference
between our system and the back-then-major SCM systems. Unless you
have used Bitkeeper, the "you can commit and your doing so would not
bother anybody else" plus "you can rewrite your private history
until you can pretend to be a super developer who came to the best
solution with a single attempt" freedom were something quite new,
and we needed to educate folks the way to think and work well in the
distributed world. Earlier in one of my messages, I said "making a
commit and switching to another commit is cheap", and that comment
came out of habit, but that is only understood by folks who have
used older SCM systems we displaced.
But with so many new users who haven't even touched anything other
than Git, none of the above examples certainly may not be the best
way to teach these things to these new crop of users.
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v2 3/4] doc: git-add: make explanation less dry
2025-08-15 20:01 ` Junio C Hamano
@ 2025-08-16 14:15 ` D. Ben Knoble
0 siblings, 0 replies; 59+ messages in thread
From: D. Ben Knoble @ 2025-08-16 14:15 UTC (permalink / raw)
To: Junio C Hamano
Cc: Julia Evans, Julia Evans, git, Chris Torek, Jean-Noël AVILA
On Fri, Aug 15, 2025 at 4:01 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
>
> > As Junio likes to say, a mistake being old is no good reason to carry
> > it forward into the future (or replicate it).
>
> I say no such thing, though. What I say about past mistakes is that
> you shouldn't use it as an excuse to make similar ones in the
> future.
Fair; my apologies for misrepresenting your position :)
> I'd prefer to let a sleeping dog lie.
>
> But in the context of this discussion, I think what we carefully and
> honestly need to look at are not past mistakes. It is importance to
> adjust to the new world we live in.
Agreed, and I could have made this clearer.
--
D. Ben Knoble
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v2 3/4] doc: git-add: make explanation less dry
2025-08-15 16:10 ` Julia Evans
2025-08-15 18:25 ` D. Ben Knoble
@ 2025-08-15 19:47 ` Junio C Hamano
2025-08-19 12:57 ` Julia Evans
1 sibling, 1 reply; 59+ messages in thread
From: Junio C Hamano @ 2025-08-15 19:47 UTC (permalink / raw)
To: Julia Evans
Cc: Julia Evans, git, Chris Torek, D. Ben Knoble,
Jean-Noël AVILA
"Julia Evans" <julia@jvns.ca> writes:
> ... Then I ask them to give feedback on what's
> confusing to them about the explanation or what questions they have.
>
> I do this because I find that often people who are extremely comfortable
> with using the software (including me, which is why I usually spend so much
> time collecting feedback like this!) can lose sight of what's confusing to an
> "average user".
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.
> And every time I'm part of a discussion about documentation for
> an open source project it seems a bit strange to me for a group of people who
> all already understand the concept to be discussing what would be clearest to an
> "average user": surely the users themselves should be the judge of what's clear
> to them!
Yes, with one caveat, which is that you need to be careful to avoid
throwing them into local optima. A simplified world view may make
it look easier to swallow, but depending on the kind of white lies
you throw at them, some of them they may have to unlearn to further
understand the system.
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v2 3/4] doc: git-add: make explanation less dry
2025-08-15 19:47 ` Junio C Hamano
@ 2025-08-19 12:57 ` Julia Evans
2025-08-21 20:36 ` Jean-Noël AVILA
0 siblings, 1 reply; 59+ messages in thread
From: Julia Evans @ 2025-08-19 12:57 UTC (permalink / raw)
To: Junio C Hamano
Cc: Julia Evans, git, Chris Torek, D. Ben Knoble,
Jean-Noël AVILA
> 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"."
^ permalink raw reply [flat|nested] 59+ messages in thread* Re: [PATCH v2 3/4] doc: git-add: make explanation less dry
2025-08-19 12:57 ` Julia Evans
@ 2025-08-21 20:36 ` Jean-Noël AVILA
0 siblings, 0 replies; 59+ messages in thread
From: Jean-Noël AVILA @ 2025-08-21 20:36 UTC (permalink / raw)
To: Junio C Hamano, Julia Evans; +Cc: Julia Evans, git, Chris Torek, D. Ben Knoble
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.
^ permalink raw reply [flat|nested] 59+ messages in thread
* [PATCH v2 4/4] doc: git-add: explain inconsistent terminology
2025-08-13 23:20 ` [PATCH v2 0/4] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
` (2 preceding siblings ...)
2025-08-13 23:20 ` [PATCH v2 3/4] doc: git-add: make explanation less dry Julia Evans via GitGitGadget
@ 2025-08-13 23:20 ` Julia Evans via GitGitGadget
2025-08-14 22:49 ` Junio C Hamano
2025-08-19 20:46 ` [PATCH v3 0/3] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
4 siblings, 1 reply; 59+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-08-13 23:20 UTC (permalink / raw)
To: git
Cc: Chris Torek, D. Ben Knoble, Jean-Noël AVILA, Julia Evans,
Julia Evans
From: Julia Evans <julia@jvns.ca>
I think the fact that git uses these three terms interchangeably is
extremely confusing and that it deserves to be noted.
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-add.adoc | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index 6a6f5223419f..0b887e1d60ca 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -45,6 +45,10 @@ exact filename of an ignored file (e.g. `git add ignored.txt`), `git
add` will fail with a list of ignored files. Otherwise it will silently
ignore the file.
+[NOTE]
+Git uses the terms "staging area", "index" and "cache" interchangeably
+for historical reasons.
+
OPTIONS
-------
`<pathspec>...`::
--
gitgitgadget
^ permalink raw reply related [flat|nested] 59+ messages in thread* Re: [PATCH v2 4/4] doc: git-add: explain inconsistent terminology
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
0 siblings, 1 reply; 59+ messages in thread
From: Junio C Hamano @ 2025-08-14 22:49 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, Chris Torek, D. Ben Knoble, Jean-Noël AVILA,
Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Julia Evans <julia@jvns.ca>
>
> I think the fact that git uses these three terms interchangeably is
> extremely confusing and that it deserves to be noted.
We tend to avoid saying "I think" in our proposed log messages, as
we do not churn the code and documentation merely to match personal
preferences.
I do not necessarily think "git add --help" is an appropriate place
to leave this note, by the way. We should start from teaching "git
help glossary", which does not mention "staging area" at all, which
is a sign that it is somewhat outdated. It does not use the verb
'to stage' even once, either.
Here is my attempt to improve the situation by giving a definition
of "staging area" in the glossary. Luckily, "cache" already has its
own entry, describing it as an old synonym to the 'index', so I
didn't have to do anything there. Also the description of 'index'
has a bit too much implementation detail, which I toned down.
---
Subject: glossary: talk about "staging area"
Surprisingly, "git help glossary" does not mention the 'staging
area' synonym for the index, or the verb 'to stage'. As "git
status" output uses the latter (i.e. "Changes not staged for
commit"), we should not leave it undefined what the verb means.
Rewrite the definition of the `index` somewhat to reduce the level
of implementation detail exposed, and focus more on the fact that it
is a mapping from pathnames to the contents at these paths. And
mention the `staging area` there, as well as giving its own glossary
entry.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Documentation/glossary-content.adoc | 20 +++++++++++++++-----
1 file changed, 15 insertions(+), 5 deletions(-)
diff --git c/Documentation/glossary-content.adoc w/Documentation/glossary-content.adoc
index e423e4765b..10f0c21e88 100644
--- c/Documentation/glossary-content.adoc
+++ w/Documentation/glossary-content.adoc
@@ -247,11 +247,15 @@ for a more flexible and robust system to do the same thing.
of Git you had to make them executable.
[[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>>.
+ The index stores the mapping from filenames to their contents
+ to prepare the contents of the next commit by updating the
+ object recorded for each path (for this reason, people often
+ say that the index is "like the staging area" when explaining
+ the concept), together with other information to detect which
+ working tree files are modified efficiently.
+ During a conflicted <<def_merge,merge>>, the index can have
+ multiple versions of contents at higher stages for the same
+ path.
[[def_index_entry]]index entry::
The information regarding a particular file, stored in the
@@ -650,6 +654,12 @@ the `refs/tags/` hierarchy is used to represent local tags..
is created by giving the `--depth` option to linkgit:git-clone[1], and
its history can be later deepened with linkgit:git-fetch[1].
+[[def_stage]]staging area::
+ A synonym for <<def_index,index>>. Adding contents to the
+ index to update the mapping from the filename to its contents
+ is often called "to stage" (verb), as people explain the index
+ is like a staging area to prepare for the next commit.
+
[[def_stash]]stash entry::
An <<def_object,object>> used to temporarily store the contents of a
<<def_dirty,dirty>> working directory and the index for future reuse.
^ permalink raw reply related [flat|nested] 59+ messages in thread
* Re: [PATCH v2 4/4] doc: git-add: explain inconsistent terminology
2025-08-14 22:49 ` Junio C Hamano
@ 2025-08-19 20:09 ` Julia Evans
0 siblings, 0 replies; 59+ messages in thread
From: Julia Evans @ 2025-08-19 20:09 UTC (permalink / raw)
To: Junio C Hamano, Julia Evans
Cc: git, Chris Torek, D. Ben Knoble, Jean-Noël AVILA
> Here is my attempt to improve the situation by giving a definition
> of "staging area" in the glossary. Luckily, "cache" already has its
> own entry, describing it as an old synonym to the 'index', so I
> didn't have to do anything there. Also the description of 'index'
> has a bit too much implementation detail, which I toned down.
I love the idea of improving the glossary, but I'm concerned that
glossary isn't very discoverable -- I didn't even know Git had
a glossary until relatively recently.
I think we can be much more brief about resolving this confusion though --
from the user feedback, all users seem to want to know is whether "index" and
"staging area" mean the same thing, and that we can clear that up in just a few
words -- 'index (also known as "staging area")'.
^ permalink raw reply [flat|nested] 59+ messages in thread
* [PATCH v3 0/3] doc: git-add: clarify DESCRIPTION section
2025-08-13 23:20 ` [PATCH v2 0/4] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
` (3 preceding siblings ...)
2025-08-13 23:20 ` [PATCH v2 4/4] doc: git-add: explain inconsistent terminology Julia Evans via GitGitGadget
@ 2025-08-19 20:46 ` Julia Evans via GitGitGadget
2025-08-19 20:46 ` [PATCH v3 1/3] Git 2.51 Junio C Hamano via GitGitGadget
` (3 more replies)
4 siblings, 4 replies; 59+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-08-19 20:46 UTC (permalink / raw)
To: git; +Cc: Chris Torek, D. Ben Knoble, Jean-Noël AVILA, Julia Evans
* Emphasize "contents" more than "files" in the introduction
* Delete the terminology note, and just keep a single parenthetical "(also
known as "staging area")"
* Be more explicit about what "By default" means
* Don't mention git diff --cached, mentioning more and more related
commands felt like it was starting to get messy (what about git diff?
what about git reset? what about git rm?).
* Leave the "This command can be performed multiple times before a
commit"... paragraph alone since the only 2 users who commented on it
said it was clear and helpful already.
* Move "Please see linkgit:git-commit[1].." back to the end, where it used
to be
Julia Evans (2):
doc: git-add: clarify intro & add an example
doc: git-add: simplify discussion of ignored files
Junio C Hamano (1):
Git 2.51
Documentation/git-add.adoc | 34 ++++++++++++++++------------------
GIT-VERSION-GEN | 2 +-
2 files changed, 17 insertions(+), 19 deletions(-)
base-commit: e5ab6b3e5a3f0a94a429526e0fe6f491955ac053
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1952%2Fjvns%2Fclarify-add-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1952/jvns/clarify-add-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1952
Range-diff vs v2:
-: ----------- > 1: c44beea485f Git 2.51
1: d041d09589b ! 2: 080720c0599 doc: git-add: start man page with an example
@@ Metadata
Author: Julia Evans <julia@jvns.ca>
## Commit message ##
- doc: git-add: start man page with an example
+ doc: git-add: clarify intro & add an example
- - Replace the intro paragraph of the `git-add` man page with an
- example to try to clarify it for new users. The goal here is use less
- jargon but communicate essentially the same information.
- - Give an example of how to add only part of the changes to the file
- - Remove the snapshot-based explanation of the index and replace it with
- a diff-based explanation because I don't feel that it's useful in this
- context to emphasize that git uses a snapshot-based model: the main
- way most git users interact with the index is through `git diff` or
- `git status`, which is a completely diff-based view of the index.
+ - Add a basic example of how "git add" is normally used
+ - It's not technically true that you *must* use the `add` command to
+ add changes before running `git commit`, because `git commit -a`
+ exists. Instead say that you *can* use the `add` command.
+ - Mention early on that "index" is another word for "staging area",
+ since Git very rarely uses the word "index" in its output
+ (`git status`) uses the term "staged", and many Git users are
+ unfamiliar with the term "index"
+ - Remove "It typically adds" (it's not clear what "typically" means),
+ and instead mention that `git add -p` can be used to add
+ partial contents
+ - Currently the introduction is somewhat repetitive ("to prepare the
+ content staged for the next commit" ... "this snapshot that is taken
+ as the contents of the next commit."), replace with a single sentence
+ ("The "index" [...] is where Git stores the contents of the next
+ commit.")
Signed-off-by: Julia Evans <julia@jvns.ca>
## Documentation/git-add.adoc ##
-@@ Documentation/git-add.adoc: git-add(1)
-
- NAME
- ----
--git-add - Add file contents to the index
-+git-add - Add new or changed files to the index
-
- SYNOPSIS
- --------
@@ Documentation/git-add.adoc: git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-
DESCRIPTION
@@ Documentation/git-add.adoc: git add [--verbose | -v] [--dry-run | -n] [--force |
-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.
-+Add new or changed files to the index to prepare for a commit. The
-+"index" (also known as "staging area") is where Git stores the changes
-+that will be in the next commit.
++Add contents of new or changed files to the index. The "index" (also
++known as "staging area") is where Git stores the contents of the next
++commit.
+
-+By default, `git commit` only commits changes that you've added to the
-+index. For example, if you've edited `file.c` and want to commit your
-+changes, you can run:
++When you run `git commit` without any other arguments, it will only
++commit staged changes. For example, if you've edited `file.c` and want
++to commit your changes to that file, you can run:
+
+ git add file.c
+ git commit
+
+You can also add only part of your changes to a file with `git add -p`.
-+Please see linkgit:git-commit[1] for alternative ways to add content to
-+a commit.
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
-@@ Documentation/git-add.adoc: directory recursion or filename globbing performed by Git (quote your
- globs before the shell) will be silently ignored. The `git add` command can
- be used to add ignored files with the `-f` (force) option.
-
--Please see linkgit:git-commit[1] for alternative ways to add content to a
--commit.
--
--
- OPTIONS
- -------
- `<pathspec>...`::
2: 63c9e0361dc ! 3: fc2ec305a9e doc: git-add: simplify discussion of ignored files
@@ Commit message
- Mention the --force option earlier
- Remove the explanation of shell globbing vs git's internal glob
- system, it's a common gotcha but I don't think this is an appropriate
- place to explain that concept. There's some discussion of the gotchas
- around globbing and `git add` in the EXAMPLES section which I think
- is clearer.
+ system, since users are confused by it and there's a clearer
+ discussion in the EXAMPLES section.
Signed-off-by: Julia Evans <julia@jvns.ca>
@@ Documentation/git-add.adoc: you must run `git add` again to add the new content
-directory recursion or filename globbing performed by Git (quote your
-globs before the shell) will be silently ignored. The `git add` command can
-be used to add ignored files with the `-f` (force) option.
-+`git add` will not add ignored files by default. You can use the
-+`--force` option to add ignored files. If you explicitly specify the
-+exact filename of an ignored file (e.g. `git add ignored.txt`), `git
-+add` will fail with a list of ignored files. Otherwise it will silently
-+ignore the file.
++The `git add` command will not add ignored files by default. You can
++use the `--force` option to add ignored files. If you specify the exact
++filename of an ignored file, `git add` will fail with a list of ignored
++files. Otherwise it will silently ignore the file.
- OPTIONS
- -------
+ Please see linkgit:git-commit[1] for alternative ways to add content to a
+ commit.
3: ce1eafb0286 < -: ----------- doc: git-add: make explanation less dry
4: 9e595f9ad59 < -: ----------- doc: git-add: explain inconsistent terminology
--
gitgitgadget
^ permalink raw reply [flat|nested] 59+ messages in thread* [PATCH v3 1/3] Git 2.51
2025-08-19 20:46 ` [PATCH v3 0/3] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
@ 2025-08-19 20:46 ` Junio C Hamano via GitGitGadget
2025-08-19 21:06 ` rsbecker
2025-08-19 20:46 ` [PATCH v3 2/3] doc: git-add: clarify intro & add an example Julia Evans via GitGitGadget
` (2 subsequent siblings)
3 siblings, 1 reply; 59+ messages in thread
From: Junio C Hamano via GitGitGadget @ 2025-08-19 20:46 UTC (permalink / raw)
To: git
Cc: Chris Torek, D. Ben Knoble, Jean-Noël AVILA, Julia Evans,
Junio C Hamano
From: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
GIT-VERSION-GEN | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN
index be801415bddc..64cbc5833536 100755
--- a/GIT-VERSION-GEN
+++ b/GIT-VERSION-GEN
@@ -1,6 +1,6 @@
#!/bin/sh
-DEF_VER=v2.51.0-rc2
+DEF_VER=v2.51.0
LF='
'
--
gitgitgadget
^ permalink raw reply related [flat|nested] 59+ messages in thread* RE: [PATCH v3 1/3] Git 2.51
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
0 siblings, 1 reply; 59+ messages in thread
From: rsbecker @ 2025-08-19 21:06 UTC (permalink / raw)
To: 'Junio C Hamano via GitGitGadget', git
Cc: 'Chris Torek', 'D. Ben Knoble',
'Jean-Noël AVILA', 'Julia Evans',
'Junio C Hamano'
On August 19, 2025 4:46 PM, Junio C Hamano wrote:
>Signed-off-by: Junio C Hamano <gitster@pobox.com>
>---
> GIT-VERSION-GEN | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
>diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN index
>be801415bddc..64cbc5833536 100755
>--- a/GIT-VERSION-GEN
>+++ b/GIT-VERSION-GEN
>@@ -1,6 +1,6 @@
> #!/bin/sh
>
>-DEF_VER=v2.51.0-rc2
>+DEF_VER=v2.51.0
>
> LF='
> '
Will this cause a re-roll of the git 2.51.0 release?
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v3 1/3] Git 2.51
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:49 ` rsbecker
0 siblings, 2 replies; 59+ messages in thread
From: Junio C Hamano @ 2025-08-19 21:37 UTC (permalink / raw)
To: rsbecker
Cc: 'Junio C Hamano via GitGitGadget', git,
'Chris Torek', 'D. Ben Knoble',
'Jean-Noël AVILA', 'Julia Evans'
<rsbecker@nexbridge.com> writes:
> On August 19, 2025 4:46 PM, Junio C Hamano wrote:
>>Signed-off-by: Junio C Hamano <gitster@pobox.com>
>>---
>> GIT-VERSION-GEN | 2 +-
>> 1 file changed, 1 insertion(+), 1 deletion(-)
>>
>>diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN index
>>be801415bddc..64cbc5833536 100755
>>--- a/GIT-VERSION-GEN
>>+++ b/GIT-VERSION-GEN
>>@@ -1,6 +1,6 @@
>> #!/bin/sh
>>
>>-DEF_VER=v2.51.0-rc2
>>+DEF_VER=v2.51.0
>>
>> LF='
>> '
>
> Will this cause a re-roll of the git 2.51.0 release?
I don't know. This is not something I did.
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v3 1/3] Git 2.51
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
1 sibling, 1 reply; 59+ messages in thread
From: D. Ben Knoble @ 2025-08-19 21:44 UTC (permalink / raw)
To: Junio C Hamano
Cc: rsbecker, Junio C Hamano via GitGitGadget, git, Chris Torek,
Jean-Noël AVILA, Julia Evans
On Tue, Aug 19, 2025 at 5:37 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> <rsbecker@nexbridge.com> writes:
>
> > On August 19, 2025 4:46 PM, Junio C Hamano wrote:
> >>Signed-off-by: Junio C Hamano <gitster@pobox.com>
> >>---
> >> GIT-VERSION-GEN | 2 +-
> >> 1 file changed, 1 insertion(+), 1 deletion(-)
> >>
> >>diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN index
> >>be801415bddc..64cbc5833536 100755
> >>--- a/GIT-VERSION-GEN
> >>+++ b/GIT-VERSION-GEN
> >>@@ -1,6 +1,6 @@
> >> #!/bin/sh
> >>
> >>-DEF_VER=v2.51.0-rc2
> >>+DEF_VER=v2.51.0
> >>
> >> LF='
> >> '
> >
> > Will this cause a re-roll of the git 2.51.0 release?
>
> I don't know. This is not something I did.
I also don't see any such PRs at GitGitGadget:
https://github.com/gitgitgadget/git/pulls?q=2.51.0
But when triple-checking the lore archive, I realized that I think
this is a result of Julia's PR getting rebased on top of 2.51.0?
https://github.com/gitgitgadget/git/pull/1952/commits
Perhaps Julia didn't use `--keep-base`, which I often forget to do
when rebasing for contribution to Git (it's common in my other
projects to omit it when working on the next version of a series).
Indeed, fetching the published branch shows it's sitting on top of the
v2.51.0 tag.
--
D. Ben Knoble
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v3 1/3] Git 2.51
2025-08-19 21:44 ` D. Ben Knoble
@ 2025-08-19 21:48 ` Julia Evans
0 siblings, 0 replies; 59+ messages in thread
From: Julia Evans @ 2025-08-19 21:48 UTC (permalink / raw)
To: D. Ben Knoble, Junio C Hamano
Cc: rsbecker, Julia Evans, git, Chris Torek, Jean-Noël AVILA
> Perhaps Julia didn't use `--keep-base`, which I often forget to do
> when rebasing for contribution to Git (it's common in my other
> projects to omit it when working on the next version of a series).
> Indeed, fetching the published branch shows it's sitting on top of the
> v2.51.0 tag.
>
> --
> D. Ben Knoble
Ah yeah, I didn't know I needed to do that. I can rebase on top of
whatever the original base was instead.
^ permalink raw reply [flat|nested] 59+ messages in thread
* RE: [PATCH v3 1/3] Git 2.51
2025-08-19 21:37 ` Junio C Hamano
2025-08-19 21:44 ` D. Ben Knoble
@ 2025-08-19 21:49 ` rsbecker
1 sibling, 0 replies; 59+ messages in thread
From: rsbecker @ 2025-08-19 21:49 UTC (permalink / raw)
To: 'Junio C Hamano'
Cc: 'Junio C Hamano via GitGitGadget', git,
'Chris Torek', 'D. Ben Knoble',
'Jean-Noël AVILA', 'Julia Evans'
On August 19, 2025 5:38 PM, Junio C Hamano wrote:
><rsbecker@nexbridge.com> writes:
>
>> On August 19, 2025 4:46 PM, Junio C Hamano wrote:
>>>Signed-off-by: Junio C Hamano <gitster@pobox.com>
>>>---
>>> GIT-VERSION-GEN | 2 +-
>>> 1 file changed, 1 insertion(+), 1 deletion(-)
>>>
>>>diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN index
>>>be801415bddc..64cbc5833536 100755
>>>--- a/GIT-VERSION-GEN
>>>+++ b/GIT-VERSION-GEN
>>>@@ -1,6 +1,6 @@
>>> #!/bin/sh
>>>
>>>-DEF_VER=v2.51.0-rc2
>>>+DEF_VER=v2.51.0
>>>
>>> LF='
>>> '
>>
>> Will this cause a re-roll of the git 2.51.0 release?
>
>I don't know. This is not something I did.
Thanks, though, for the info.
^ permalink raw reply [flat|nested] 59+ messages in thread
* [PATCH v3 2/3] doc: git-add: clarify intro & add an example
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 20:46 ` Julia Evans via GitGitGadget
2025-08-21 20:08 ` Junio C Hamano
2025-08-19 20:46 ` [PATCH v3 3/3] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
2025-08-29 11:55 ` [PATCH v4 0/2] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
3 siblings, 1 reply; 59+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-08-19 20:46 UTC (permalink / raw)
To: git
Cc: Chris Torek, D. Ben Knoble, Jean-Noël AVILA, Julia Evans,
Julia Evans
From: Julia Evans <julia@jvns.ca>
- Add a basic example of how "git add" is normally used
- It's not technically true that you *must* use the `add` command to
add changes before running `git commit`, because `git commit -a`
exists. Instead say that you *can* use the `add` command.
- Mention early on that "index" is another word for "staging area",
since Git very rarely uses the word "index" in its output
(`git status`) uses the term "staged", and many Git users are
unfamiliar with the term "index"
- Remove "It typically adds" (it's not clear what "typically" means),
and instead mention that `git add -p` can be used to add
partial contents
- Currently the introduction is somewhat repetitive ("to prepare the
content staged for the next commit" ... "this snapshot that is taken
as the contents of the next commit."), replace with a single sentence
("The "index" [...] is where Git stores the contents of the next
commit.")
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-add.adoc | 24 ++++++++++++------------
1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index b7a735824d6c..19f99b0e7f6f 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -16,18 +16,18 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-
DESCRIPTION
-----------
-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.
-
-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.
+Add contents of new or changed files to the index. The "index" (also
+known as "staging area") is where Git stores the contents of the next
+commit.
+
+When you run `git commit` without any other arguments, it will only
+commit staged changes. For example, if you've edited `file.c` and want
+to commit your changes to that file, you can run:
+
+ git add file.c
+ git commit
+
+You can also add only part of your changes to a file with `git add -p`.
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
--
gitgitgadget
^ permalink raw reply related [flat|nested] 59+ messages in thread* Re: [PATCH v3 2/3] doc: git-add: clarify intro & add an example
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
0 siblings, 1 reply; 59+ messages in thread
From: Junio C Hamano @ 2025-08-21 20:08 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, Chris Torek, D. Ben Knoble, Jean-Noël AVILA,
Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> DESCRIPTION
> -----------
> -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.
> -
> -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.
> +Add contents of new or changed files to the index. The "index" (also
> +known as "staging area") is where Git stores the contents of the next
> +commit.
Much nicer than the preimage text that is quite awkwardly phrased.
I however would not say "Git stores the contents", as it is you the
user who does the storing. I may phrase it more like "... is what
you use to prepare the contents for the next commit." probably.
> +When you run `git commit` without any other arguments, it will only
> +commit staged changes. For example, if you've edited `file.c` and want
> +to commit your changes to that file, you can run:
> +
> + git add file.c
> + git commit
> +
> +You can also add only part of your changes to a file with `git add -p`.
Great.
^ permalink raw reply [flat|nested] 59+ messages in thread
* Re: [PATCH v3 2/3] doc: git-add: clarify intro & add an example
2025-08-21 20:08 ` Junio C Hamano
@ 2025-08-22 20:37 ` Julia Evans
0 siblings, 0 replies; 59+ messages in thread
From: Julia Evans @ 2025-08-22 20:37 UTC (permalink / raw)
To: Junio C Hamano, Julia Evans
Cc: git, Chris Torek, D. Ben Knoble, Jean-Noël AVILA
"what you use to prepare the contents for the next commit" sounds
good to me, will make those changes.
On Thu, Aug 21, 2025, at 4:08 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> DESCRIPTION
>> -----------
>> -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.
>> -
>> -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.
>> +Add contents of new or changed files to the index. The "index" (also
>> +known as "staging area") is where Git stores the contents of the next
>> +commit.
>
> Much nicer than the preimage text that is quite awkwardly phrased.
>
> I however would not say "Git stores the contents", as it is you the
> user who does the storing. I may phrase it more like "... is what
> you use to prepare the contents for the next commit." probably.
>
>> +When you run `git commit` without any other arguments, it will only
>> +commit staged changes. For example, if you've edited `file.c` and want
>> +to commit your changes to that file, you can run:
>> +
>> + git add file.c
>> + git commit
>> +
>> +You can also add only part of your changes to a file with `git add -p`.
>
> Great.
^ permalink raw reply [flat|nested] 59+ messages in thread
* [PATCH v3 3/3] doc: git-add: simplify discussion of ignored files
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 20:46 ` [PATCH v3 2/3] doc: git-add: clarify intro & add an example Julia Evans via GitGitGadget
@ 2025-08-19 20:46 ` 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
3 siblings, 1 reply; 59+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-08-19 20:46 UTC (permalink / raw)
To: git
Cc: Chris Torek, D. Ben Knoble, Jean-Noël AVILA, Julia Evans,
Julia Evans
From: Julia Evans <julia@jvns.ca>
- Mention the --force option earlier
- Remove the explanation of shell globbing vs git's internal glob
system, since users are confused by it and there's a clearer
discussion in the EXAMPLES section.
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-add.adoc | 10 ++++------
1 file changed, 4 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index 19f99b0e7f6f..bf793d289493 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -37,12 +37,10 @@ you must run `git add` again to add the new content to the index.
The `git status` command can be used to obtain a summary of which
files have changes that are staged for the next commit.
-The `git add` command will not add ignored files by default. If any
-ignored files were explicitly specified on the command line, `git add`
-will fail with a list of ignored files. Ignored files reached by
-directory recursion or filename globbing performed by Git (quote your
-globs before the shell) will be silently ignored. The `git add` command can
-be used to add ignored files with the `-f` (force) option.
+The `git add` command will not add ignored files by default. You can
+use the `--force` option to add ignored files. If you specify the exact
+filename of an ignored file, `git add` will fail with a list of ignored
+files. Otherwise it will silently ignore the file.
Please see linkgit:git-commit[1] for alternative ways to add content to a
commit.
--
gitgitgadget
^ permalink raw reply related [flat|nested] 59+ messages in thread
* Re: [PATCH v3 3/3] doc: git-add: simplify discussion of ignored files
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
0 siblings, 0 replies; 59+ messages in thread
From: Junio C Hamano @ 2025-08-21 20:09 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, Chris Torek, D. Ben Knoble, Jean-Noël AVILA,
Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> -The `git add` command will not add ignored files by default. If any
> -ignored files were explicitly specified on the command line, `git add`
> -will fail with a list of ignored files. Ignored files reached by
> -directory recursion or filename globbing performed by Git (quote your
> -globs before the shell) will be silently ignored. The `git add` command can
> -be used to add ignored files with the `-f` (force) option.
> +The `git add` command will not add ignored files by default. You can
> +use the `--force` option to add ignored files. If you specify the exact
> +filename of an ignored file, `git add` will fail with a list of ignored
> +files. Otherwise it will silently ignore the file.
Nice. Much simplified, yet still teaches the same thing.
Thanks.
^ permalink raw reply [flat|nested] 59+ messages in thread
* [PATCH v4 0/2] doc: git-add: clarify DESCRIPTION section
2025-08-19 20:46 ` [PATCH v3 0/3] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
` (2 preceding siblings ...)
2025-08-19 20:46 ` [PATCH v3 3/3] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
@ 2025-08-29 11:55 ` 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
` (2 more replies)
3 siblings, 3 replies; 59+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-08-29 11:55 UTC (permalink / raw)
To: git; +Cc: Chris Torek, D. Ben Knoble, Jean-Noël AVILA, rsbecker,
Julia Evans
Slightly reword the first sentence ("you use" instead of "Git stores")
Julia Evans (2):
doc: git-add: clarify intro & add an example
doc: git-add: simplify discussion of ignored files
Documentation/git-add.adoc | 34 ++++++++++++++++------------------
1 file changed, 16 insertions(+), 18 deletions(-)
base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1952%2Fjvns%2Fclarify-add-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1952/jvns/clarify-add-v4
Pull-Request: https://github.com/gitgitgadget/git/pull/1952
Range-diff vs v3:
1: c44beea485 < -: ---------- Git 2.51
2: 080720c059 ! 1: 57947d5a3e doc: git-add: clarify intro & add an example
@@ Documentation/git-add.adoc: git add [--verbose | -v] [--dry-run | -n] [--force |
-the commit command, you must use the `add` command to add any new or
-modified files to the index.
+Add contents of new or changed files to the index. The "index" (also
-+known as "staging area") is where Git stores the contents of the next
-+commit.
++known as the "staging area") is what you use to prepare the contents of
++the next commit.
+
+When you run `git commit` without any other arguments, it will only
+commit staged changes. For example, if you've edited `file.c` and want
3: fc2ec305a9 = 2: f57effdd2b doc: git-add: simplify discussion of ignored files
--
gitgitgadget
^ permalink raw reply [flat|nested] 59+ messages in thread* [PATCH v4 1/2] doc: git-add: clarify intro & add an example
2025-08-29 11:55 ` [PATCH v4 0/2] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
@ 2025-08-29 11:55 ` 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
2 siblings, 0 replies; 59+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-08-29 11:55 UTC (permalink / raw)
To: git
Cc: Chris Torek, D. Ben Knoble, Jean-Noël AVILA, rsbecker,
Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
- Add a basic example of how "git add" is normally used
- It's not technically true that you *must* use the `add` command to
add changes before running `git commit`, because `git commit -a`
exists. Instead say that you *can* use the `add` command.
- Mention early on that "index" is another word for "staging area",
since Git very rarely uses the word "index" in its output
(`git status`) uses the term "staged", and many Git users are
unfamiliar with the term "index"
- Remove "It typically adds" (it's not clear what "typically" means),
and instead mention that `git add -p` can be used to add
partial contents
- Currently the introduction is somewhat repetitive ("to prepare the
content staged for the next commit" ... "this snapshot that is taken
as the contents of the next commit."), replace with a single sentence
("The "index" [...] is where Git stores the contents of the next
commit.")
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-add.adoc | 24 ++++++++++++------------
1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index b7a735824d..ffe8fd701a 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -16,18 +16,18 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-
DESCRIPTION
-----------
-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.
-
-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.
+Add contents of new or changed files to the index. The "index" (also
+known as the "staging area") is what you use to prepare the contents of
+the next commit.
+
+When you run `git commit` without any other arguments, it will only
+commit staged changes. For example, if you've edited `file.c` and want
+to commit your changes to that file, you can run:
+
+ git add file.c
+ git commit
+
+You can also add only part of your changes to a file with `git add -p`.
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
--
gitgitgadget
^ permalink raw reply related [flat|nested] 59+ messages in thread* [PATCH v4 2/2] doc: git-add: simplify discussion of ignored files
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 ` Julia Evans via GitGitGadget
2025-08-29 17:11 ` [PATCH v4 0/2] doc: git-add: clarify DESCRIPTION section Junio C Hamano
2 siblings, 0 replies; 59+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-08-29 11:55 UTC (permalink / raw)
To: git
Cc: Chris Torek, D. Ben Knoble, Jean-Noël AVILA, rsbecker,
Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
- Mention the --force option earlier
- Remove the explanation of shell globbing vs git's internal glob
system, since users are confused by it and there's a clearer
discussion in the EXAMPLES section.
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-add.adoc | 10 ++++------
1 file changed, 4 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index ffe8fd701a..ad629c46c5 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -37,12 +37,10 @@ you must run `git add` again to add the new content to the index.
The `git status` command can be used to obtain a summary of which
files have changes that are staged for the next commit.
-The `git add` command will not add ignored files by default. If any
-ignored files were explicitly specified on the command line, `git add`
-will fail with a list of ignored files. Ignored files reached by
-directory recursion or filename globbing performed by Git (quote your
-globs before the shell) will be silently ignored. The `git add` command can
-be used to add ignored files with the `-f` (force) option.
+The `git add` command will not add ignored files by default. You can
+use the `--force` option to add ignored files. If you specify the exact
+filename of an ignored file, `git add` will fail with a list of ignored
+files. Otherwise it will silently ignore the file.
Please see linkgit:git-commit[1] for alternative ways to add content to a
commit.
--
gitgitgadget
^ permalink raw reply related [flat|nested] 59+ messages in thread
* Re: [PATCH v4 0/2] doc: git-add: clarify DESCRIPTION section
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 ` Junio C Hamano
2 siblings, 0 replies; 59+ messages in thread
From: Junio C Hamano @ 2025-08-29 17:11 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, Chris Torek, D. Ben Knoble, Jean-Noël AVILA, rsbecker,
Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Slightly reword the first sentence ("you use" instead of "Git stores")
The update is appreciated, but the topic has already been in 'next'
for a few days since 2025-08-25 at 0c84501ed2, so we'd need to turn
this into a follow-up incremental fix.
Here is what I came up with and will queue for today's integration
cycle.
--- >8 ---
From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 29 Aug 2025 10:07:42 -0700
Subject: [PATCH] doc: rephrase the purpose of the staging area
From: Julia Evans <julia@jvns.ca>
Git does not really "store the contents of the next commit"
anywhere; rather, you the user use the index to prepare it.
Signed-off-by: Julia Evans <julia@jvns.ca>
[jc; made the change relative to what is already in 'next']
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Documentation/git-add.adoc | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index bf793d2894..ad629c46c5 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -17,8 +17,8 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-
DESCRIPTION
-----------
Add contents of new or changed files to the index. The "index" (also
-known as "staging area") is where Git stores the contents of the next
-commit.
+known as the "staging area") is what you use to prepare the contents of
+the next commit.
When you run `git commit` without any other arguments, it will only
commit staged changes. For example, if you've edited `file.c` and want
--
2.51.0-267-g71e270be43
^ permalink raw reply related [flat|nested] 59+ messages in thread