doc: git-add: clarify DESCRIPTION section #1952
Open
Conversation
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
|
There are issues in commit 9ca17c4: |
|
There are issues in commit ffdbff5: |
|
There are issues in commit a844a8f: |
|
There are issues in commit 54d36b3: |
|
There are issues in commit f66dbef: |
jvns
force-pushed
the
clarify-add
branch
2 times, most recently
from
f74315b to
f7e8e4c
Compare
|
/submit |
|
Submitted as [email protected] To fetch this version into To fetch this version to local tag |
![gitgitgadget[bot]](https://avatars.githubusercontent.com/in/12836?s=60&v=4){kind=small}
| @@ -8,11 +8,7 @@ git-add - Add file contents 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>...]
| `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.
|
User |
| @@ -3,31 +3,28 @@ 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:
> - 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.
But isn't it the source of the most end-user confusion that they
cannot wean themselves off of the diff/patch worldview?
How would you explain what the users would see in their "git diff",
"git diff --cached", and "git commit" after doing "edit && add &&
edit", if you explain "add" to be storing the "diff" made by the
first edit? Does their "git diff" after the second "edit" take that
previously stored "diff" and another "diff" made by the second
"edit" and magically combine them together to present a single
"diff"?
> -git-add - Add file contents to the index
> +git-add - Add new or changed files to the index
In other words, I do think "new or changed" is a good thing to say,
but the word "contents" is fundamental here. "Add contents of new
or changed files to the index" would be good.
> +Add new or changed files to the index (also known as "staging area") to
> +prepare for a commit.
OK, but saying "files" here adds another kind of confusion. What is
"added" is not the fact that these paths are kept track of by Git.
Instead we add the snapshot of the contents at the time of 'git add'.
Wouldn't "add file X" confuse folks who still remember how other
SCMs before Git operated (i.e. "file X is now known, so if I make
further changes to X next 'commit' command will record it") into
thinking that Git would do the same?
> +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
What happens when you did "edit && add && edit && add"? It commits
the two changes you added to the index? I do not think it is
productive to hide the fact that you are preparing a snapshot of the
"next commit" in the index (or "staging the contents for the next
commit in the staging area") with various forms "git add", including
"git add -p".
And to help form that mental model, it would help to avoid phrasing
"commit your changes" (as if you are somehow dealing with "diff/patch")
and instead saying "commit the result of your changes" (stressing
that the "state" matters), I would think.
De-stressing the fact that we are taking a snapshot should probably
be considered a documentation regression here. Thanks to "git add"
taking a snapshot, users can further make experimental changes in
the working tree files freely and then come back to the exact
contents back by checking the path out of the index with "git
checkout -- <path>". Thanks to "git commit" taking a snapshot,
users can even go back to the last commit by taking the exact
contents back by checking the path out of the HEAD with "git
checkout HEAD -- <path>".
I'll stop here and let others express their opinions without further
commenting for now.
Thanks for working on these updates.
There was a problem hiding this comment.
On the Git mailing list, "Julia Evans" wrote (reply to this):
> But isn't it the source of the most end-user confusion that they
> cannot wean themselves off of the diff/patch worldview?
To me it feels very contextual! My impression is that what's important for Git
users is to be able to think about commits as diffs in some contexts, and as
snapshots in other contexts. For example with `git rebase` I'm usually thinking
of my commits as diffs, but it's very helpful to me to think of a merge commit
as a snapshot, because the merge commit does not have to be a "combination" of
the two sides of the merge, it can have arbitrary extra content.
> Wouldn't "add file X" confuse folks who still remember how other
> SCMs before Git operated (i.e. "file X is now known, so if I make
> further changes to X next 'commit' command will record it") into
> thinking that Git would do the same?
The point about Subversion is interesting: I would expect that most
people learning about Git's data model in 2025 have never used
Subversion.
So while I think it's extremely important to make accurate statements
while talking about Git (and I think it's very possible that this description
is not accurate enough!), I do not think it's so important to specifically
target misconceptions that users coming from Subversion/CVS
may have.
>> +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
>
> What happens when you did "edit && add && edit && add"? It commits
> the two changes you added to the index? I do not think it is
> productive to hide the fact that you are preparing a snapshot of the
> "next commit" in the index (or "staging the contents for the next
> commit in the staging area") with various forms "git add", including
> "git add -p".
It could! It's easy for me to imagine a world where the index
stores an ordered list of diffs, which are applied as patches in
series when I commit. I guess you'd need some sort of
patch + patch + patch + diff workflow to generate the final diff,
but to me that doesn't feel so different from what Git is actually doing in
practice.
In any case, I'll think more about whether I think this is really
an accurate description. I'm always especially interested in the practical
consequences of having misconceptions about Git: for example (and maybe I'm
convincing myself to change my position here!) with `git mv` I think it can
become relevant pretty quickly that commits are snapshots, because if
you move a file and edit it then Git can't always accurately guess that you
intended to "move" the file rather than delete the file and create a new one.
I'd like to be able to have a similarly practical example of why it's important
to think of commits as snapshots in the context of `git add` but I haven't quite
found the right one yet. I've noticed that people will often sort of "reject"
information that does not fit their mental models, and I think "commits are
snapshots, this is important in this context because of
<specific practical consequence>" is much more convincing than just
"commits are snapshots".There was a problem hiding this comment.
On the Git mailing list, Junio C Hamano wrote (reply to this):
"Julia Evans" <[email protected]> writes:
>> Wouldn't "add file X" confuse folks who still remember how other
>> SCMs before Git operated (i.e. "file X is now known, so if I make
>> further changes to X next 'commit' command will record it") into
>> thinking that Git would do the same?
>
> The point about Subversion is interesting: I would expect that most
> people learning about Git's data model in 2025 have never used
> Subversion.
Even though I promised that I won't comment on this thread further
for now, I'd have to respond to this one.
Times change. I didn't have Subversion in mind when I wrote the
above. It was CVS ;-)
Yes, I have heard that for recent crop of developers especially
newgrads, Git is the only SCM they've ever touched. If we can
assume that the data and mental model of Git is natural for our
intended audiences, that is great (we can also forget about the
diff/patch based world view, which comes from how CVS/RCS stored
their revision data, and assume that the snapshot based world view
is natural to our readers).There was a problem hiding this comment.
On the Git mailing list, "Julia Evans" wrote (reply to this):
> Yes, I have heard that for recent crop of developers especially
> newgrads, Git is the only SCM they've ever touched. If we can
> assume that the data and mental model of Git is natural for our
> intended audiences, that is great (we can also forget about the
> diff/patch based world view, which comes from how CVS/RCS stored
> their revision data, and assume that the snapshot based world view
> is natural to our readers).
Git is certainly the only version control system I've ever used: I started using
it when I was a new grad 15 years ago. Everything I know about Subversion or CVS
(almost nothing) I know from reading explanations of Git aimed at their users
or from trying to understand the origin of some of Git's terminology choices :)
re whether the snapshot based world view is "natural" or not to Git users:
I did some very unscientific polls about people's mental models of Git
a while back at https://jvns.ca/blog/2024/03/28/git-poll-results/#commits
That one says that 42% of folks who responded think of commits as "snapshots"
and 50% as "diffs", which feels encouraging to me: after all, the poll doesn't
ask how Git represents commits internally, and many people replied in the
comments to say that they think of commits in both ways depending on the
situation.There was a problem hiding this comment.
On the Git mailing list, "D. Ben Knoble" wrote (reply to this):
On Tue, Aug 12, 2025 at 5:40 PM Julia Evans <[email protected]> wrote:
>
> > But isn't it the source of the most end-user confusion that they
> > cannot wean themselves off of the diff/patch worldview?
>
> To me it feels very contextual! My impression is that what's important for Git
> users is to be able to think about commits as diffs in some contexts, and as
> snapshots in other contexts. For example with `git rebase` I'm usually thinking
> of my commits as diffs, but it's very helpful to me to think of a merge commit
> as a snapshot, because the merge commit does not have to be a "combination" of
> the two sides of the merge, it can have arbitrary extra content.
>
[snip]
>
> >> +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
> >
> > What happens when you did "edit && add && edit && add"? It commits
> > the two changes you added to the index? I do not think it is
> > productive to hide the fact that you are preparing a snapshot of the
> > "next commit" in the index (or "staging the contents for the next
> > commit in the staging area") with various forms "git add", including
> > "git add -p".
>
> It could! It's easy for me to imagine a world where the index
> stores an ordered list of diffs, which are applied as patches in
> series when I commit. I guess you'd need some sort of
> patch + patch + patch + diff workflow to generate the final diff,
> but to me that doesn't feel so different from what Git is actually doing in
> practice.
>
> In any case, I'll think more about whether I think this is really
> an accurate description. I'm always especially interested in the practical
> consequences of having misconceptions about Git: for example (and maybe I'm
> convincing myself to change my position here!) with `git mv` I think it can
> become relevant pretty quickly that commits are snapshots, because if
> you move a file and edit it then Git can't always accurately guess that you
> intended to "move" the file rather than delete the file and create a new one.
>
> I'd like to be able to have a similarly practical example of why it's important
> to think of commits as snapshots in the context of `git add` but I haven't quite
> found the right one yet. I've noticed that people will often sort of "reject"
> information that does not fit their mental models, and I think "commits are
> snapshots, this is important in this context because of
> <specific practical consequence>" is much more convincing than just
> "commits are snapshots".
Less a comment on this patch or diff ;) and more a meta-note: I happen
to have several links saved on the idea of "Snapshot vs. Patch" aka
"commit duality", so I figured I'd share. They reinforce to me, at
least, that the contextual mode of thinking is useful in practice,
even if the snapshot model is the (semantic) storage model [*].
Knowing about snapshots does make it far easier to interact with
objects directly, which also frequently helps me better understand how
to use particular commands.
- https://www.thirtythreeforty.net/posts/2020/01/the-wave-particle-duality-of-git-commits/
- https://roadrunnertwice.dreamwidth.org/596185.html (which references
Julia's work)
- of course, https://jvns.ca/blog/2024/01/05/do-we-think-of-git-commits-as-diffs--snapshots--or-histories/
;)
- https://stackoverflow.com/q/40617288/4400820,
https://stackoverflow.com/q/73646342/4400820,
https://stackoverflow.com/a/27760319/4400820
- https://github.blog/open-source/git/commits-are-snapshots-not-diffs/
- https://lore.kernel.org/git/[email protected]/
What I find is that, while we keep trying to reinforce the snapshot
mentality, there are situations where thinking in diffs is a
reasonable approximation. In the particular case of git-add, most
interactions I observe with the index are diff-based (git diff, git
diff --cached, etc.), but I'm not sure how to usefully clarify the
relationship between those things and the underlying trees involved
(working tree, HEAD, index :0:) in a manual section targeted primarily
at newcomers.
[*]: "Semantic" because deltas in packfiles muddy the _actual_ storage
model somewhat :)
--
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:
> an accurate description. I'm always especially interested in the practical
> consequences of having misconceptions about Git: for example (and maybe I'm
> convincing myself to change my position here!) with `git mv` I think it can
> become relevant pretty quickly that commits are snapshots, because if
> you move a file and edit it then Git can't always accurately guess that you
> intended to "move" the file rather than delete the file and create a new one.
There is an easier-to-understand example. If you pretend that you
"add" series of "diff/patch" to the index as you repeat "edit &&
add" three times, in the mental model of the users, there would be
three set of patches stored in the index somehow. It would be a
fair wish for the users to have to be able to revert only the change
you added with your second "git add" while keeping the first one and
the third (latest) one. You cannot explain why you fundamentally
cannot give them such a new "feature", until you admit that what is
recorded is the latest snapshot and earlier snapshots are discarded.
Another thing that the "collection of diff/patch" view probably
harms understanding of users is merge, which is not a set of diffs,
one for each parent and the merge result. Of course, as a merge is
symmetric across the parents, it is not diff between the first
parent and the merge result, either.There was a problem hiding this comment.
On the Git mailing list, "Julia Evans" wrote (reply to this):
> There is an easier-to-understand example. If you pretend that you
> "add" series of "diff/patch" to the index as you repeat "edit &&
> add" three times, in the mental model of the users, there would be
> three set of patches stored in the index somehow. It would be a
> fair wish for the users to have to be able to revert only the change
> you added with your second "git add" while keeping the first one and
> the third (latest) one. You cannot explain why you fundamentally
> cannot give them such a new "feature", until you admit that what is
> recorded is the latest snapshot and earlier snapshots are discarded.
Thanks, I think this is the perfect example and it gets at something about git
add that i’ve never totally understood: why are the earlier snapshots discarded?
Naively, one might think that:
1. the git index is just a tree object
2. when you commit, Git takes that tree object, attaches a
message, and makes a commit with it
3. git maintains some sort of history (like the reflog) for the past "index"
tree objects
If Git worked that way, I imagine it would be possible to implement the feature
you describe, and I feel like there's some sort of obvious reason (something
to do with performance?) for why the index isn't implemented this way that
I've never learned.
This example makes me think that if we want people to understand the
limitations of the index, it's important to communicate that the past
index snapshots are *discarded* and not just that the index is a snapshot.
- 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 <[email protected]>
- 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 <[email protected]>
|
User |
|
On the Git mailing list, "D. Ben Knoble" wrote (reply to this), regarding 3f4ab61 (outdated): On Tue, Aug 12, 2025 at 4:10 PM Julia Evans via GitGitGadget
<[email protected]> wrote:
>
> From: Julia Evans <[email protected]>
>
> - 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 <[email protected]>
> ---
> 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 99ca2d0f7e21..0c4ca1794c91 100644
> --- a/Documentation/git-add.adoc
> +++ b/Documentation/git-add.adoc
> @@ -34,12 +34,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.
This reads more clearly to me, although I think it's worth trying to
keep the style "The `git add` command" command to avoid strange
punctuation/capitalization at the start of a sentence.
Thanks for working on these :)
--
D. Ben Knoble |
- use examples - mention `git diff --staged` - link to git diff man page Signed-off-by: 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. Signed-off-by: Julia Evans <[email protected]>
|
On the Git mailing list, Jean-Noël AVILA wrote (reply to this), regarding 3a2cc38 (outdated): On Tuesday, 12 August 2025 22:07:25 CEST Julia Evans via GitGitGadget wrote:
> 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>`
> 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. `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
> 3. Some man pages already take this approach, like `git rebase` and
> `git status`
>
> Signed-off-by: Julia Evans <[email protected]>
> ---
> Documentation/git-add.adoc | 6 +-----
> 1 file changed, 1 insertion(+), 5 deletions(-)
>
> diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
> index b7a735824d6c..12afeead6637 100644
> --- a/Documentation/git-add.adoc
> +++ b/Documentation/git-add.adoc
> @@ -8,11 +8,7 @@ git-add - Add file contents to the index
> SYNOPSIS
> --------
> [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>...]
> +git add [<options>] [--] [<pathspec>...]
>
> DESCRIPTION
> -----------
Hello,
I'm not crazy about this change. In its new form, it is almost useless and
formally wrong: according to it, `git add` is a valid invocation. The question
is about how this synopsis section is supposed to be used. For me, this is a
quick refresher of the available options, their exact name and how they can be
combined, a kind of compact overview.
I'm not saying that the current form is good. For instance, I would expect to
see alternative forms such as `git add -u` appear on their own line whereas
other forms require <pathspec>. There are common options that could be hidden
into the [<options>] stuff, even if it kills a bit the "compact summary"
feature of the synopsis, but as you said, these are independent and can be
found under the 'OPTIONS' section.
The design of the man pages predates some more modern approaches to organizing
technical documentation e.g. https://diataxis.fr/ and https://help.adobe.com/
en_US/framemaker/2019/using/using-framemaker-2019/user-guide/
frm_structauthdita_sd_dita-topics.html. Thus they are mixing different aims/
approaches in a single document. Anyway, we can agree to classify some of the
manual page sections into the more modern typing. For instance, I think
SYNOPSIS falls under the "reference" type, and as such should be as
comprehensive as possible.
Jean-Noël
|
|
User |
|
/submit |
|
Submitted as [email protected] To fetch this version into To fetch this version to local tag |
Documentation/git-add.adoc
Outdated
| @@ -37,16 +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 | |||
There was a problem hiding this comment.
On the Git mailing list, "D. Ben Knoble" wrote (reply to this):
On Wed, Aug 13, 2025 at 7:20 PM Julia Evans via GitGitGadget
<[email protected]> wrote:
>
> From: Julia Evans <[email protected]>
>
> - 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 <[email protected]>
> ---
> 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
git addcommand" instead ofgit addcc: Chris Torek [email protected]
cc: "D. Ben Knoble" [email protected]
cc: Jean-Noël AVILA [email protected]