Git
英语 ▾ 主题 ▾ 最新版本 ▾ git-add 最后更新于 2.46.0

名称

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>…​]

描述

此命令使用工作树中找到的当前内容更新索引,准备将内容暂存到下一个提交。它通常将现有路径的当前内容作为一个整体添加,但使用一些选项,它也可以用于添加内容,其中只应用了对工作树文件所做的部分更改,或者删除工作树中不再存在的路径。

“索引”保存工作树内容的快照,正是此快照被作为下一个提交的内容。因此,在对工作树进行任何更改后,并且在运行提交命令之前,必须使用 add 命令将任何新文件或修改后的文件添加到索引。

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

git status 命令可用于获取哪些文件已进行更改并已暂存到下一个提交的摘要。

默认情况下,git add 命令不会添加被忽略的文件。如果命令行中显式指定了任何被忽略的文件,git add 将失败并显示被忽略的文件列表。由 Git 执行的目录递归或文件名通配(在 shell 之前引用你的通配符)所达到的被忽略文件将被静默忽略。git add 命令可以使用 -f(强制)选项添加被忽略的文件。

有关将内容添加到提交的替代方法,请参阅 git-commit[1]

选项

<pathspec>…​

要添加内容的文件。可以使用文件通配符(例如 *.c)添加所有匹配的文件。还可以使用前导目录名称(例如 dir 添加 dir/file1dir/file2),将索引更新为与目录的整体当前状态相匹配(例如,指定 dir 将不仅记录工作树中修改的文件 dir/file1,还记录添加到工作树中的文件 dir/file2,以及从工作树中删除的文件 dir/file3)。请注意,Git 的旧版本过去会忽略已删除的文件;如果要添加修改后的文件或新文件,但要忽略已删除的文件,请使用 --no-all 选项。

有关 <pathspec> 语法的更多详细信息,请参阅 gitglossary[7] 中的 pathspec 条目。

-n
--dry-run

不要实际添加文件,只显示文件是否存在和/或是否会被忽略。

-v
--verbose

详细模式。

-f
--force

允许添加其他被忽略的文件。

--sparse

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

-i
--interactive

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

-p
--patch

交互式地选择索引和工作树之间的补丁块并将其添加到索引。这使用户有机会在将修改后的内容添加到索引之前查看差异。

这实际上运行 add --interactive,但绕过初始命令菜单并直接跳转到 patch 子命令。有关详细信息,请参阅“交互模式”。

-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 add 会在将嵌入式仓库添加到索引中时发出警告,而没有使用git submodule add.gitmodules中创建条目。此选项将抑制警告(例如,如果您正在手动对子模块执行操作)。

--renormalize

对所有跟踪文件重新应用“清理”过程,以强制再次将它们添加到索引中。这在更改core.autocrlf配置或text属性后很有用,以便更正以错误的 CRLF/LF 行结尾添加的文件。此选项意味着-u。孤立的 CR 字符保持不变,因此虽然 CRLF 清理为 LF,但 CRCRLF 序列只被部分清理为 CRLF。

--chmod=(+|-)x

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

--pathspec-from-file=<file>

Pathspec 传递到<file> 而不是命令行参数。如果<file> 恰好是- 则使用标准输入。Pathspec 元素以 LF 或 CR/LF 分隔。Pathspec 元素可以像配置变量core.quotePath 所解释的那样被引用(参见 git-config[1])。另请参见 --pathspec-file-nul 和全局 --literal-pathspecs

--pathspec-file-nul

只有在--pathspec-from-file 时才有意义。Pathspec 元素以 NUL 字符分隔,所有其他字符都被逐字取用(包括换行符和引号)。

--

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

示例

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

    $ git add Documentation/\*.txt

    请注意,在这个例子中,星号* 是从 shell 中引用的;这使命令可以包含Documentation/ 目录子目录中的文件。

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

    $ git add git-*.sh

    由于此示例允许 shell 扩展星号(即您正在显式列出文件),因此它不考虑subdir/git-foo.sh

交互模式

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

命令循环显示了可用的子命令列表,并提供了一个提示“What now>”。一般来说,当提示以单个> 结尾时,您只能选择一个给定的选项并输入回车,像这样

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

只要选择是唯一的,您也可以在上面说sstastatus

主命令循环有 6 个子命令(加上帮助和退出)。

status

这显示了 HEAD 和索引之间的变化(即,如果您说git commit,将会提交的内容),以及索引和工作树文件之间的变化(即,在使用git add 进行git commit 之前,您可以进一步阶段的内容)每个路径。示例输出如下

              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

这与update 非常类似,所选路径的暂存信息将恢复为 HEAD 版本。恢复新路径会使它们成为未跟踪路径。

add untracked

这与updaterevert 非常类似,允许您将未跟踪的路径添加到索引中。

patch

这允许您从status 样式选择中选择一个路径。选择路径后,它会显示索引和工作树文件之间的 diff,并询问您是否要暂存每个块的变化。您可以选择以下选项之一并输入回车

y - stage this hunk
n - do not stage this hunk
q - quit; do not stage this hunk or any of the remaining ones
a - stage this hunk and all later hunks in the file
d - do not stage this hunk or any of the later hunks in the file
g - select a hunk to go to
/ - search for a hunk matching the given regex
j - leave this hunk undecided, see next undecided hunk
J - leave this hunk undecided, see next hunk
k - leave this hunk undecided, see previous undecided hunk
K - leave this hunk undecided, see previous hunk
s - split the current hunk into smaller hunks
e - manually edit the current hunk
p - print the current hunk
? - print help

决定了所有块的命运后,如果选择了任何块,索引将使用选定的块进行更新。

您可以通过设置配置变量interactive.singleKeytrue 来避免在这里输入回车。

diff

这允许您查看将要提交的内容(即 HEAD 和索引之间的内容)。

编辑补丁

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

添加内容

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

删除内容

删除的内容由以“-”开头的行表示。您可以通过将“-”转换为“ ”(空格)来阻止暂存它们的删除。

修改内容

修改的内容由“-”行(删除旧内容)后跟“+”行(添加替换内容)表示。您可以通过将“-”行转换为“ ”,并删除“+”行来阻止暂存修改。注意,只修改其中一半很可能会在索引中引入令人困惑的变化。

还可以执行更复杂的操作。但请注意,由于补丁仅应用于索引,而不是工作树,因此工作树将显示为“撤消”索引中的更改。例如,在索引中引入一个既不在 HEAD 也不在工作树中的新行,将暂存新行以进行提交,但该行将显示为在工作树中被撤消。

避免使用这些结构,或者非常谨慎地使用它们。

删除未修改的内容

索引和工作树之间没有差异的内容可能显示在上下文行上,以“ ”(空格)开头。您可以通过将空格转换为“-”来暂存上下文行以进行删除。由此产生的工作树文件将显示为重新添加内容。

修改现有内容

还可以通过暂存它们以进行删除(通过将“ ”转换为“-”)并添加以“+”开头的具有新内容的行来修改上下文行。类似地,可以修改现有添加或修改的“+”行。在所有情况下,新的修改将显示为在工作树中被撤消。

新内容

您还可以添加补丁中不存在的新内容;只需添加新行,每行都以“+”开头。该添加将显示为在工作树中被撤消。

还有一些操作应该完全避免,因为它们会导致无法应用补丁

  • 添加上下文(“ ”)或删除(“-”)行

  • 删除上下文或删除行

  • 修改上下文或删除行的内容

配置

本节中此行以下的所有内容都是从 git-config[1] 文档中选择性包含的。内容与在那里找到的内容相同

add.ignoreErrors
add.ignore-errors (已弃用)

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

GIT

git[1] 套件的一部分

scroll-to-top