Git
English ▾ 主題 ▾ 最新版本 ▾ 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>…​]

描述

此命令使用工作目錄中找到的目前內容來更新索引,以準備將內容暫存以供下次提交。它通常會新增現有路徑的目前內容作為整體,但使用某些選項也可以用於新增僅套用對工作目錄檔案所做部分變更的內容,或移除工作目錄中不再存在的路徑。

「索引」保存工作目錄內容的快照,而此快照會被當作下次提交的內容。因此,在對工作目錄進行任何變更之後,以及在執行 commit 命令之前,您必須使用 add 命令將任何新的或已修改的檔案新增至索引。

此命令可以在提交之前執行多次。它只會新增執行 add 命令時所指定檔案的內容;如果您想要將後續變更納入下次提交,則必須再次執行 git add 以將新內容新增至索引。

可以使用 git status 命令來取得已暫存以供下次提交的變更檔案摘要。

預設情況下,git add 命令不會新增忽略的檔案。如果在命令列上明確指定了任何忽略的檔案,則 git add 將會失敗並顯示忽略的檔案清單。透過目錄遞迴或 Git 執行的檔案名稱 globbing(在 Shell 之前引用您的 glob)所達到的忽略檔案將會被靜默忽略。可以使用 -f(強制)選項來使用 git add 命令新增忽略的檔案。

請參閱 git-commit[1] 以取得將內容新增至提交的其他方式。

選項

<pathspec>…​

要從中新增內容的檔案。可以指定檔案 glob(例如 *.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 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* 子命令的輸出,然後進入其互動命令迴圈。

命令迴圈會顯示可用的子命令清單,並提供提示「What now> 」。一般來說,當提示以單個 *>* 結尾時,您只能選擇給定的選項之一並輸入 return,如下所示

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

您也可以在上面說 sstastatus,只要選擇是唯一的。

主要命令迴圈有 6 個子命令(加上 help 和 quit)。

status

這會顯示 HEAD 和索引之間的變更(也就是說,如果您輸入 git commit 會提交的內容),以及索引和工作樹檔案之間的變更(也就是說,您可以使用 git addgit 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

此介面與 *update* 和 *revert* 非常相似,可讓您將未追蹤的路徑新增至索引。

patch

這可讓您從類似 *status* 的選取範圍中選擇一個路徑。選擇路徑後,它會顯示索引和工作樹檔案之間的差異,並詢問您是否要暫存每個區塊的變更。您可以選擇下列選項之一,然後輸入 return

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.singleKey 設定為 true,以免必須在此處輸入 return。

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