Git
简体中文 ▾ Topics ▾ Latest version ▾ git-add last updated in 2.29.1

名称

git-add - 添加内容到索引

概述

git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
	  [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]]
	  [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
	  [--chmod=(+|-)x] [--pathspec-from-file=<文件> [--pathspec-file-nul]]
	  [--] [<指定路径>…​]

描述

该命令在工作树中找到的当前的内容以更新索引,为下一次提交准备暂存的内容。它通常会整体添加现有路径的当前内容,但是通过某些选项,它也可以用于仅添加对工作树文件所做的部分更改,或删除工作树中不存在的路径。

“索引”保存着工作树内容的快照,该快照作为下一次提交的内容。因此,在对工作树进行任何更改之后,以及在运行commit命令之前,必须使用`add`命令将所有新文件或修改过的文件添加到索引中。

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

git status 命令可用于获取摘要,说明哪些变化的文件已暂存,准备下一次提交。

git add 命令默认不会添加被忽略的文件。如果在命令行上明确指定了任何被忽略的文件,则`git add`会失败,并显示被忽略文件的列表。由目录递归或Git执行的文件名通配符(在shell之前引用的通配符)所涉及的忽略文件将被静默忽略。 git add 命令可用于通过 -f 选项(force)强制添加忽略的文件。

请参阅 git-commit[1] 了解将内容添加到提交的其他替代方法。

选项

<pathspec>…​

要从中添加内容的文件。Fileglobs(例如 *.c)可以用来添加所有匹配的文件。此外,还可以提供一个前导目录名(例如,指定 dir 以添加 dir/file1dir/file2)来更新索引,使其与整个目录的当前状态相匹配(例如,指定 dir 不仅会记录在工作树中修改的文件 dir/file1,还会记录在工作树中添加的文件 dir/file2,还有从工作树中删除的文件 dir/file3)。请注意,旧版本的 Git 会忽略已删除的文件;如果要添加已修改的文件或新文件,但忽略已删除的文件,请使用 --no all 选项。

有关 <指定路径> 格式的更多细节,请参考 gitglossary[7]

-n
--dry-run

实际上不添加文件,仅展示文件是否存在或是否忽略。

-v
--verbose

冗余模式。

-f
--force

允许添加已被忽略的文件。

-i
--interactive

以交互方式将工作树中的修改内容添加到索引。可以提供可选的路径参数,以将操作限制为工作树的子集。有关详细信息,请参见`‘交互模式’'。

-p
--patch

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

这可以有效地运行 add --interactive,但是会绕过初始命令菜单,而直接跳转到 patch 子命令。有关详细信息,请参见`‘交互模式’'。

-e
--edit

在编辑器中打开与索引的差异,使用户进行编辑。关闭编辑器后,调整块补丁头并将其应用于索引。

此选项的目的是选择并选择要应用的补丁的行,甚至修改要暂存的行的内容。与使用交互式补丁块选择器相比,其更快,更灵活。但是,很容易混淆自己并创建不应用于索引的补丁。请参阅下面的编辑补丁。

-u
--update

在索引已经有与 <指定路径> 匹配项的地方更新索引。这会删除和修改索引项以匹配工作树,但不添加新文件。

如果在使用 -u 选项时没有 <指定路径>,则整个工作树中的所有跟踪文件都将更新(旧版本 Git 会限制更新当前目录及其子目录)。

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

不仅在工作树中有与 <指定路径 >匹配的文件的地方更新索引,而且在索引中已经有一个项的地方更新索引。这将添加、修改和删除与工作树匹配的索引项。

如果在使用 -A 选项时没有 <指定路径>,则整个工作树中的所有文件都将更新(旧版本的 Git 会限制当前目录及其子目录的更新)。

--no-all
--ignore-removal

通过添加索引未知的新文件和在工作树中修改的文件以更新索引,但忽略已从工作树中删除的文件。当不使用 <指定路径> 时,此选项是必须的。

此选项主要用于帮助那些习惯于较旧版本 Git 的用户。旧版本中的 "Git add<指定路径>…​" 是 "Git add—​no all<指定路径>…​" 的同义词,即忽略已删除的文件。

-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

对所有跟踪的文件应用`clean`过程,将它们再次强制添加到索引中。这在更改`core.autocrlf`配置或`text`属性以更正添加了错误CRLF/LF行结尾的文件后非常有用。此选项隐含`-u`选项。

--chmod=(+|-)x

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

--pathspec-from-file=<file>

Pathspec在 <file> 中传递,而不是在命令行参数中传递。如果 <file> 正好是 -,则使用标准输入。Pathspec 元素由 LF 或 CR/LF 分隔。可以引用配置变量 core.quotePath 的 Pathspec 元素(请参见 linkgit: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 子命令的输出,然后进入其交互命令循环。

命令循环显示可用的子命令列表,并提示 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个子命令(包括帮助和退出)。

状态

这将显示每个路径下 HEAD 和索引之间的更改(即,如果输入 git commit,将提交什么),以及索引和工作树文件之间的更改(即,在输入 git commit 之前,执行 git add 可以进一步暂存什么)。示例输出如下:

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

它表明foo.png与HEAD有区别(但其是二进制的,因此无法显示行数),索引副本和工作树版本之间没有区别(如果工作树版本也不同,nothing`的位置上会显示`binary)。另一个文件git add---interactive.perl添加了403行,如果提交索引中的内容,则删除了35行,但工作树文件有额外修改(一次添加一次删除)。

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 git-add--interactive.perl

要删除选定内容,请在输入前加上`-`,如下所示:

Update>> -2

进行选择后,输入空行,以便为索引中选定的路径暂存工作树文件的内容。

还原

它有一个与 update 非常相似的交互过程,所选路径的暂存信息将还原为 HEAD 版本。还原新路径将使它们不被追踪。

添加未跟踪文件

它有一个与 updaterevert 非常相似的交互过程,允许您向索引添加未跟踪的路径。

补丁

这允许您从类似 "status" 命令的选择中选择一条路径。在选择路径之后,它将显示索引和工作树文件之间的差异,并询问您是否要暂存每个块的更改。您可以选择以下选项之一并输入回车:

y - 暂存此区块
n - 不暂存此区块
q - 退出;不暂存包括此块在内的剩余的区块
a - 暂存此块与此文件后面所有的区块
d - 不暂存此块与此文件后面所有的 区块
g - 选择并跳转至一个区块
/ - 搜索与给定正则表达示匹配的区块
j - 暂不决定,转至下一个未决定的区块
J - 暂不决定,转至下一个区块
k - 暂不决定,转至上一个未决定的区块
K - 暂不决定,转至上一个区块
s - 将当前的区块分割成多个较小的区块
e - 手动编辑当前的区块
? - 输出帮助

在决定了所有块的操作后,如果有选择的区块,则会使用其来更新索引。

通过将配置变量 interactive.singleKey 设置为 true,在此处可以不必键入回车。

diff

这使您可以查看要提交的内容(即,在HEAD和索引之间)。

编辑补丁

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

添加的内容

添加的内容以“ +”开头的行表示。您可以删除它们以防止暂存。

删除的内容

删除的内容以“-”开头的行表示。您可以通过将“-”转换为“ ”(空格)来防止将其删除。

修改的内容

修改后的内容由“-”行(删除旧内容)和“+”行(添加替换内容)表示。通过将“-”行转换为“ ”,并删除“+”行,可以防止临时进行修改。请注意,只修改其中一个可能会给索引带来混乱的更改。

还可以执行更复杂的操作。但是请注意,由于补丁仅应用于索引而不是工作树,因此工作树似乎会“撤消”索引中的更改。例如,在索引中添加一行,而该行不在 HEAD 或工作树。此时会暂存其以进行提交,但是该行似乎在会在工作树中进行还原。

避免使用这些构造,除非格外小心。

删除未改动的内容

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

修改现有的内容

也可以通过暂存上下文行(通过将“ ”转换为“-”)以进行删除来修改上下文行,并在其中添加新内容的“+”行。类似地,可以修改“+”行以进行现有内容的添加或修改。在所有情况下,新的修改都将在工作树中还原。

新的内容

您还可以添加补丁中不存在的新内容。只需添加新行,每行以“+”开头。添加的内容将还原到工作树中。

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

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

  • 删除上下文行或删除标记为删除的行

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

GIT

Part of the git[1] suite