From 93899116f931955edbed110c5f4286495677ec2d Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Tue, 19 Aug 2025 15:30:12 -0400 Subject: [PATCH 1/2] doc: git-add: clarify intro & add an example - 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 --- 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 b7a735824d6ce0..19f99b0e7f6f09 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 From 67fb4eb4963a087ea0b150625a1458c7fca21e45 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Sat, 9 Aug 2025 09:12:46 -0400 Subject: [PATCH 2/2] doc: git-add: simplify discussion of ignored files - 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 --- 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 19f99b0e7f6f09..bf793d28949339 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.