git-add

将文件内容添加到索引

概要

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 commit 时，它只会提交已暂存的更改。例如，如果你已编辑 file.c 并想提交对该文件的更改，可以运行：

git add file.c
git commit

你也可以使用 git add -p 仅将文件的部分更改添加到索引。

此命令可以在提交之前多次执行。它只添加在运行 add 命令时指定文件的内容；如果你希望后续更改包含在下次提交中，则必须再次运行 git add 将新内容添加到索引。

git status 命令可用于获取哪些文件的更改已暂存用于下次提交的摘要。

git add 命令默认不会添加被忽略的文件。你可以使用 --force 选项添加被忽略的文件。如果你指定了被忽略文件的确切文件名，git add 将失败并显示被忽略文件的列表。否则它会静默忽略该文件。

有关将内容添加到提交的替代方法，请参阅 git-commit(1)。

选项

<pathspec>...

要添加内容的文件。可以使用文件通配符（例如 *.c）来添加所有匹配的文件。也可以指定前导目录名（例如 dir 以添加 dir/file1 和 dir/file2）来更新索引以匹配目录的当前整体状态（例如，指定 dir 将不仅记录在工作树中修改的文件 dir/file1、添加到工作树的文件 dir/file2，还会记录从工作树中删除的文件 dir/file3）。请注意，旧版本的 Git 会忽略已删除的文件；如果你想添加已修改或新文件但忽略已删除的文件，请使用 --no-all 选项。

有关 <pathspec> 语法的更多详细信息，请参阅 gitglossary(7) 中的 'pathspec' 条目。

-n, --dry-run

不实际添加文件，只显示它们是否存在和/或将被忽略。

-v, --verbose

详细模式。

-f, --force

允许添加 otherwise 被忽略 的文件。当设置 submodule.<name>.ignore=all 但你想暂存子模块的更新时，也会使用此选项。必须显式指定子模块的 path。

--sparse

允许更新稀疏检出锥体之外的索引条目。通常，git add 拒绝更新路径不在稀疏检出锥体内的索引条目，因为这些文件可能会在没有警告的情况下从工作树中删除。有关更多详细信息，请参阅 git-sparse-checkout(1)。

-i, --interactive

以交互方式将工作树中的修改内容添加到索引。可以提供可选的路径参数来限制操作到工作树的子集。有关详细信息，请参阅"交互模式"。

-p, --patch

以交互方式在索引和工作树之间选择补丁块并将其添加到索引。这使用户有机会在将修改内容添加到索引之前查看差异。 这实际上运行 add --interactive，但跳过初始命令菜单并直接跳到 patch 子命令。有关详细信息，请参阅"交互模式"。

-U<n>, --unified=<n>

生成具有 <n> 行上下文的差异。上下文行数默认为 diff.context，如果未设置配置变量则为 3。（由于历史原因，不带 <n> 的 -U 被静默接受为 -p 的同义词）。

--inter-hunk-context=<n>

显示差异块之间的上下文，最多显示指定的 <number> 行，从而合并彼此接近的块。默认为 diff.interHunkContext，如果未设置配置选项则为 0。

-e, --edit

在编辑器中打开与索引的差异并让用户编辑它。编辑器关闭后，调整块头并将补丁应用于索引。 此选项的目的是选择要应用的补丁行，甚至可以修改要暂存的行内容。这可能比使用交互式块选择器更快更灵活。但是，很容易混淆自己并创建无法应用于索引的补丁。请参阅下面的"编辑补丁"。

-u, --update

仅更新索引中已有与 <pathspec> 匹配的条目。这会删除和修改索引条目以匹配工作树，但不会添加新文件。 如果使用 -u 选项时未给出 <pathspec>，则整个工作树中的所有已跟踪文件都会更新（旧版本的 Git 将更新限制在当前目录及其子目录中）。

-A, --all, --no-ignore-removal

更新索引中工作树有文件匹配 <pathspec> 以及索引已有条目的位置。这会添加、修改和删除索引条目以匹配工作树。 如果使用 -A 选项时未给出 <pathspec>，则整个工作树中的所有文件都会更新（旧版本的 Git 将更新限制在当前目录及其子目录中）。

--no-all, --ignore-removal

通过添加索引未知的新文件和在工作树中修改的文件来更新索引，但忽略从工作树中删除的文件。当未使用 <pathspec> 时，此选项不执行任何操作。 此选项主要是为了帮助习惯旧版本 Git 的用户，其 git add <pathspec>... 是 git add --no-all <pathspec>... 的同义词，即忽略已删除的文件。

-N, --intent-to-add

仅记录路径稍后将被添加的事实。路径的条目将被放置在索引中，但没有内容。这在许多用途中很有用，例如使用 git diff 显示此类文件的未暂存内容，以及使用 git commit -a 提交它们。

--refresh

不添加文件，只刷新它们在索引中的 stat() 信息。

--ignore-errors

如果某些文件因索引错误而无法添加，不要中止操作，而是继续添加其他文件。命令仍应以非零状态退出。配置变量 add.ignoreErrors 可以设置为 true 以使此成为默认行为。

--ignore-missing

此选项只能与 --dry-run 一起使用。通过使用此选项，用户可以检查给定文件是否会被忽略，无论它们是否已存在于工作树中。

--no-warn-embedded-repo

默认情况下，当在不使用 git submodule add 在 .gitmodules 中创建条目的情况下添加嵌入式存储库时，git add 会发出警告。此选项将抑制警告（例如，如果你正在手动对子模块执行操作）。

--renormalize

对所有已跟踪文件重新应用"clean"过程以强制将它们再次添加到索引。在更改 core.autocrlf 配置或 text 属性后，这对于更正以错误 CRLF/LF 行尾添加的文件很有用。此选项隐含 -u。单独的 CR 字符不受影响，因此虽然 CRLF 会清理为 LF，但 CRCRLF 序列只会部分清理为 CRLF。

--chmod=(+|-)x

覆盖添加文件的可执行位。可执行位仅在索引中更改，磁盘上的文件保持不变。

--pathspec-from-file=<file>

路径规格在 <file> 中传递，而不是命令行参数。如果 <file> 恰好是 -，则使用标准输入。路径规格元素由 LF 或 CR/LF 分隔。路径规格元素可以按配置变量 core.quotePath 中说明的方式引用（参见 git-config(1)）。另请参阅 --pathspec-file-nul 和全局 --literal-pathspecs。

--pathspec-file-nul

仅与 --pathspec-from-file 一起使用时有意义。路径规格元素用 NUL 字符分隔，所有其他字符按字面意思处理（包括换行符和引号）。

--

此选项可用于将命令行选项与文件列表分开（当文件名可能被误认为命令行选项时很有用）。

示例

• 添加 Documentation 目录及其子目录下所有 *.txt 文件的内容：

git add Documentation/\*.txt

注意，此示例中星号 * 从 shell 中被引用；这使命令可以包含 Documentation/ 目录子目录中的文件。

• 考虑添加所有 git-*.sh 脚本的内容：

git add git-*.sh

因为此示例让 shell 展开星号（即你明确列出文件），所以它不会考虑 subdir/git-foo.sh。

交互模式

当命令进入交互模式时，它会显示 status 子命令的输出，然后进入其交互命令循环。

命令循环显示可用子命令列表，并给出提示 "Whatnow> "。通常，当提示以单个 > 结尾时，你只能选择给定选项之一并按回车，如下所示：

    *** Commands ***
      1: status       2: update       3: revert       4: add untracked
      5: patch        6: diff         7: quit         8: help
    What now> 1

你也可以在上面说 s 或 sta 或 status，只要选择是唯一的。

主命令循环有 6 个子命令（加上 help 和 quit）。

status

显示 HEAD 和索引之间的更改（即如果你说 git commit 将提交什么），以及索引和工作树文件之间的更改（即在 git commit 之前你可以使用 git add 进一步暂存什么）。示例输出如下所示：

              staged     unstaged path
     1:       binary      nothing foo.png
     2:     +403/-35        +1/-1 add-interactive.c

它显示 foo.png 与 HEAD 有差异（但它是二进制文件，所以无法显示行数）并且索引副本和工作树版本之间没有差异（如果工作树版本也有差异，'binary' 将显示在 'nothing' 的位置）。另一个文件 add-interactive.c 如果你提交索引中的内容，将有 403 行添加和 35 行删除，但工作树文件有进一步的修改（一次添加和一次删除）。

update

显示状态信息并发出 "Update>>" 提示。当提示以双 >> 结尾时，你可以进行多个选择，用空格或逗号连接。你也可以指定范围。例如 "2-5 7,9" 从列表中选择 2,3,4,5,7,9。如果范围中的第二个数字被省略，则选择所有剩余的补丁。例如 "7-" 从列表中选择 7,8,9。你可以说 * 选择所有内容。

然后你选择的内容会用 * 突出显示，如下所示：

           staged     unstaged path
  1:       binary      nothing foo.png
* 2:     +403/-35        +1/-1 add-interactive.c

要删除选择，请在输入前加上 -，如下所示：

Update>> -2

做出选择后，用空行回答以将所选路径的工作树文件内容暂存到索引中。

revert

它的 UI 与 'update' 非常相似，所选路径的暂存信息将恢复为 HEAD 版本。恢复新路径会使其变为未跟踪。

add untracked

它的 UI 与 'update' 和 'revert' 非常相似，允许你将未跟踪的路径添加到索引。

patch

这让你从类似 'status' 的选择中选择一个路径。选择路径后，它会显示索引和工作树文件之间的差异，并询问你是否要暂存每个块的更改。你可以选择以下选项之一并按回车：

       y - 暂存此块
       n - 不暂存此块
       q - 退出；不暂存此块或任何剩余的块
       a - 暂存此块和文件中所有后续的块
       d - 不暂存此块或文件中任何后续的块
       g - 选择要转到的块
       / - 搜索与给定正则表达式匹配的块
       j - 转到下一个未决定的块，在底部回绕
       J - 转到下一个块，在底部回绕
       k - 转到上一个未决定的块，在顶部回绕
       K - 转到上一个块，在顶部回绕
       s - 将当前块拆分为更小的块
       e - 手动编辑当前块
       p - 打印当前块
       P - 使用分页器打印当前块
       ? - 打印帮助

在决定所有块的命运后，如果有任何被选择的块，索引将用选定的块更新。

你可以通过将配置变量 interactive.singleKey 设置为 true 来省去必须按回车的步骤。

diff

这让你查看将被提交的内容（即 HEAD 和索引之间）。

编辑补丁

调用 git add -e 或从交互式块选择器中选择 e 将在编辑器中打开补丁；编辑器退出后，结果将应用于索引。你可以自由地对补丁进行任意更改，但请注意某些更改可能会产生混淆的结果，甚至导致无法应用的补丁。如果你想完全中止操作（即不在索引中暂存任何新内容），只需删除补丁的所有行。下面的列表描述了你在补丁中可能看到的一些常见内容，以及哪些编辑操作对它们有意义。

添加的内容

添加的内容以 "+" 开头的行表示。你可以通过删除它们来阻止暂存任何添加行。

删除的内容

删除的内容以 "-" 开头的行表示。你可以通过将 "-" 转换为 " "（空格）来阻止暂存它们的删除。

修改的内容

修改的内容由 "-" 行（删除旧内容）后跟 "+" 行（添加替换内容）表示。你可以通过将 "-" 行转换为 " " 并删除 "+" 行来阻止暂存修改。请注意，仅修改这对中的一半可能会向索引引入令人困惑的更改。

还有更复杂的操作可以执行。但请注意，由于补丁仅应用于索引而不是工作树，工作树将看起来"撤消"了索引中的更改。例如，向索引中引入一个既不在 HEAD 中也不在工作树中的新行将暂存新行以进行提交，但该行在工作树中将显示为已恢复。

避免使用这些构造，或者在使用时格外小心。

删除未修改的内容

在索引和工作树之间没有差异的内容可能会显示在以 " "（空格）开头的上下文行中。你可以通过将空格转换为 "-" 来暂存上下文行以进行删除。生成的工作树文件将看起来重新添加了内容。

修改现有内容

还可以通过将上下文行暂存为删除（通过将 " " 转换为 "-"）并添加带有新内容的 "+" 行来修改上下文行。类似地，你可以修改现有添加或修改的 "+" 行。在所有情况下，新修改将在工作树中显示为已恢复。

新内容

你还可以添加补丁中不存在的新内容；只需添加新行，每行以 "+" 开头。添加将在工作树中显示为已恢复。

还有几个操作应该完全避免，因为它们会使补丁无法应用：

• 添加上下文（" "）或删除（"-"）行
• 删除上下文或删除行
• 修改上下文或删除行的内容

配置

本节中此行以下的内容是从 git-config(1) 文档中选择性包含的。内容与其中的内容相同：

add.ignoreErrors

add.ignore-errors（已弃用）

告诉 git add 在某些文件因索引错误而无法添加时继续添加文件。等同于 --ignore-errors 选项。add.ignore-errors 已弃用，因为它不遵循配置变量的常用命名约定。

另请参阅

git-status(1)git-rm(1)git-reset(1)git-mv(1)git-commit(1)git-update-index(1)

Git

git(1) 套件的一部分