Skip to content

doc: git-add: clarify DESCRIPTION section #1952

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

doc: git-add: clarify DESCRIPTION section #1952

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9389911
doc: git-add: clarify intro & add an example
jvns Aug 19, 2025
67fb4eb
doc: git-add: simplify discussion of ignored files
jvns Aug 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 16 additions & 18 deletions Documentation/git-add.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Copy link

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):

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

Copy link

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):

"Julia Evans via GitGitGadget" <[email protected]> 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.

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.
Expand Down
Loading