doc: git-add: clarify DESCRIPTION section #1952
+33
−31
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,7 +3,7 @@ git-add(1) | |
|
|
||
|
There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans via GitGitGadget" <[email protected]> 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".There was a problem hiding this comment. On the Git mailing list, Jean-Noël AVILA wrote (reply to this): On Friday, 15 August 2025 02:38:45 CEST Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <[email protected]> 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".
There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): Jean-Noël AVILA <[email protected]> writes:
> On Friday, 15 August 2025 02:38:45 CEST Junio C Hamano wrote:
>> "Julia Evans via GitGitGadget" <[email protected]> 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. |
||
| NAME | ||
| ---- | ||
| git-add - Add new or changed files to the index | ||
|
|
||
| SYNOPSIS | ||
|
There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> Motivations for this change:
>
> 1. Listing a huge number of options is visually overwhelming when
> opening a man page for an unfamiliar command. It makes it harder
> to understand the command's core syntax, like `git add <filename>`
For "git add", which has only one mode of operation, this may be
good.
Note that in general this is not necessarily a good idea, when a
command works in different modes (like "git branch" that can
list/enumerate or create/delete/manipulate), as not all the options
can be used in all the modes the command supports. The "usage" part
of the output from "git branch -h" hits a good balance, and may want
to use as a model.
There is t0450 that aspires to ensure the short usage "git <cmd> -h"
matches the synopsis section of "git help <cmd>" for all <cmd>; right
now we have too many exceptions, and we should move towards making
these exceptions smaller.
> 2. For options which can be passed independently of any other options,
> including them in the SYNOPSIS does not add any information which you
> can't already get from reading the OPTIONS section.
Except that you have to scan a lot of text, which is quite
inefficient when you *know* the general idea behind the option you
want to use, and are only looking for the exact spelling of it (e.g.
"was it spelled --ignore-removed?")
> `git add` has
> some mutually exclusive options, namely:
> [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]]
> but personally I already find that line so hard to parse that
> removing it doesn't remove a lot of information
It is a very good point why we may want to have these cues to
express "these go together" (my earlier example of "branch") and
"only one of these is used". I tend to agree with you that these
are not necessarily very easy to read.
While it is important to make it easier for new readers to learn, we
should also keep in mind that nobody remains to be a newbie forever.
> [synopsis]
> -git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
> - [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]
> - [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
> - [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
> - [--] [<pathspec>...]
This being a long single line and with redundant "--long|-s" may be
making it unnecessarily ugly. Have you considered folding lines and
simplifying "[--long | -s]" into "[-s]" and see if it makes easier
to follow? Documentation/git-commit.adoc may serve as a better
model.
> +git add [<options>] [--] [<pathspec>...]
>
> DESCRIPTION
> -----------There was a problem hiding this comment. On the Git mailing list, "Julia Evans" wrote (reply to this): Thanks for the comments. I think for now I'll just remove this patch
from the series since I don't see a clear way forward and I think it'll
make it easier to focus on the other changes.
> Note that in general this is not necessarily a good idea, when a
> command works in different modes (like "git branch" that can
> list/enumerate or create/delete/manipulate), as not all the options
> can be used in all the modes the command supports.
I've been thinking about that as well: I have some ideas I've been working on
for how to clarify the usage of different "modes" of a command by giving the
modes names, will share those when I get to a command with modes.
> Except that you have to scan a lot of text, which is quite
> inefficient when you *know* the general idea behind the option you
> want to use, and are only looking for the exact spelling of it (e.g.
> "was it spelled --ignore-removed?")
That's fair. Something that I hadn't considered is that how easy the OPTIONS
section is to scan depends on how the man page is formatted: some man
page viewers will bold the options (which I think makes them easier to scan),
but some won't.
> While it is important to make it easier for new readers to learn, we
> should also keep in mind that nobody remains to be a newbie forever.
> Have you considered folding lines and
> simplifying "[--long | -s]" into "[-s]" and see if it makes easier
> to follow? Documentation/git-commit.adoc may serve as a better
> model.
Hmm, here's what it looks like with the long options removed.
To me it doesn't feel like a big enough improvement, and it's harder
to tell what some of the short options (like `-n`) mean.
git add [-p] [-v] [-n] [-f] [-i] [-e] [-A | --no-all | -u]
[--sparse] [--intent-to-add | -N] [--refresh] [--ignore-errors]
[--ignore-missing] [--renormalize] [--chmod=(+|-)x]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...] |
||
| -------- | ||
|
|
@@ -16,37 +16,38 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [- | |
|
|
||
| DESCRIPTION | ||
| ----------- | ||
| 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 | ||
|
There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans via GitGitGadget" <[email protected]> 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.There was a problem hiding this comment. On the Git mailing list, "Julia Evans" wrote (reply to this): 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,
JuliaThere was a problem hiding this comment. On the Git mailing list, "D. Ben Knoble" wrote (reply to this): On Fri, Aug 15, 2025 at 12:10 PM Julia Evans <[email protected]> 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 KnobleThere was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans" <[email protected]> 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.There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "D. Ben Knoble" <[email protected]> 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.
|
||
| a commit. | ||
|
|
||
| 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. | ||
|
|
||
| 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 | ||
| 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 | ||
|
There was a problem hiding this comment. On the Git mailing list, Chris Torek wrote (reply to this): On Tue, Aug 12, 2025 at 1:35 PM Julia Evans via GitGitGadget
<[email protected]> wrote:
> +TERMINOLOGY NOTE
> +----------------
> +
> +Git uses the terms "staging area", "index" and "cache" interchangeably
> +for historical reasons. Many commands have flags like `--staged`,
> +`--index`, or `--cached`, and they all refer to the index.
> +
I think this is also a good idea. Unfortunately, `git apply` has two
different meanings for `--index` vs `--cached` (I believe it's the
*only* exception to the "means the same thing" rule...).
ChrisThere was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): Chris Torek <[email protected]> writes:
> On Tue, Aug 12, 2025 at 1:35 PM Julia Evans via GitGitGadget
> <[email protected]> wrote:
>> +TERMINOLOGY NOTE
>> +----------------
>> +
>> +Git uses the terms "staging area", "index" and "cache" interchangeably
>> +for historical reasons. Many commands have flags like `--staged`,
>> +`--index`, or `--cached`, and they all refer to the index.
>> +
>
> I think this is also a good idea. Unfortunately, `git apply` has two
> different meanings for `--index` vs `--cached` (I believe it's the
> *only* exception to the "means the same thing" rule...).
Yes, I think the first sentence is an excellent addition, even
though I do not know if "git add" is the best place to teach it.
However, it will be disservice to users to say "they all refer to
the index" here. Yes, it is technically correct that they all refer
to the index, but that much any intelligent readers can infer after
reading the first sentance that historically these three words were
used to refer to the same "index". And what I think is bad in that
second sentence is that it implies they may mean the same thing
without saying that. It is perfectly fine to say that these three
words express some operation around the index (sometimes called the
staging area). It also is fine to say that "--staged" is sometimes
used as synonym for `--cached`.
But at least `--cached` and `--index` mean quite different things.
As "git help cli" explains, an operation that can affect only the
index would use "--cached" and both the index and the working tree
would use "--index".
It may be that "apply" is currently the only exception (I did not
check), but it certainly is not guaranteed to stay to be the only
exception. If a command wants to work on both the contents in the
index and in the working tree, such a command is very much welcomed
to use the option "--index" to trigger such a mode of operation.
Conclusion? I would rather see "Many commands have ..." sentence
struck out. After all, that does not need to be taught to those who
came here to learn about "git add".
Thanks.There was a problem hiding this comment. On the Git mailing list, "Julia Evans" wrote (reply to this): That sounds good to me, I'll remove the second sentence.
On Tue, Aug 12, 2025, at 5:36 PM, Junio C Hamano wrote:
> Chris Torek <[email protected]> writes:
>
>> On Tue, Aug 12, 2025 at 1:35 PM Julia Evans via GitGitGadget
>> <[email protected]> wrote:
>>> +TERMINOLOGY NOTE
>>> +----------------
>>> +
>>> +Git uses the terms "staging area", "index" and "cache" interchangeably
>>> +for historical reasons. Many commands have flags like `--staged`,
>>> +`--index`, or `--cached`, and they all refer to the index.
>>> +
>>
>> I think this is also a good idea. Unfortunately, `git apply` has two
>> different meanings for `--index` vs `--cached` (I believe it's the
>> *only* exception to the "means the same thing" rule...).
>
> Yes, I think the first sentence is an excellent addition, even
> though I do not know if "git add" is the best place to teach it.
>
> However, it will be disservice to users to say "they all refer to
> the index" here. Yes, it is technically correct that they all refer
> to the index, but that much any intelligent readers can infer after
> reading the first sentance that historically these three words were
> used to refer to the same "index". And what I think is bad in that
> second sentence is that it implies they may mean the same thing
> without saying that. It is perfectly fine to say that these three
> words express some operation around the index (sometimes called the
> staging area). It also is fine to say that "--staged" is sometimes
> used as synonym for `--cached`.
>
> But at least `--cached` and `--index` mean quite different things.
>
> As "git help cli" explains, an operation that can affect only the
> index would use "--cached" and both the index and the working tree
> would use "--index".
>
> It may be that "apply" is currently the only exception (I did not
> check), but it certainly is not guaranteed to stay to be the only
> exception. If a command wants to work on both the contents in the
> index and in the working tree, such a command is very much welcomed
> to use the option "--index" to trigger such a mode of operation.
>
> Conclusion? I would rather see "Many commands have ..." sentence
> struck out. After all, that does not need to be taught to those who
> came here to learn about "git add".
>
> Thanks.There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> 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 <[email protected]>
---
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. |
||
| ignore the file. | ||
|
|
||
| [NOTE] | ||
| Git uses the terms "staging area", "index" and "cache" interchangeably | ||
| for historical reasons. | ||
|
|
||
| OPTIONS | ||
| ------- | ||
|
|
@@ -451,6 +452,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 | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, Junio C Hamano wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, "Julia Evans" wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, Junio C Hamano wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, "Julia Evans" wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, "D. Ben Knoble" wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, Junio C Hamano wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, "Julia Evans" wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, Junio C Hamano wrote (reply to this):