Git
English ▾ 主題 ▾ 最新版本 ▾ gitignore 最後更新於 2.42.0

名稱

gitignore - 指定刻意不追蹤的忽略檔案

概要

$XDG_CONFIG_HOME/git/ignore, $GIT_DIR/info/exclude, .gitignore

描述

gitignore 檔案指定 Git 應該忽略的刻意不追蹤的檔案。已經被 Git 追蹤的檔案不受影響；詳情請參閱下方的注意事項。

gitignore 檔案中的每一行指定一個模式。當決定是否忽略一個路徑時，Git 通常會檢查來自多個來源的 gitignore 模式，其優先順序如下，從高到低（在同一個優先順序級別內，最後符合的模式決定結果）

  • 從支援這些命令的命令列讀取的模式。

  • 從與路徑相同的目錄，或任何父目錄（直到工作樹的頂層）的 .gitignore 檔案讀取的模式，較高層級檔案中的模式會被較低層級檔案中的模式覆蓋，直到包含該檔案的目錄。這些模式會相對於 .gitignore 檔案的位置進行匹配。專案通常會在其儲存庫中包含此類 .gitignore 檔案，其中包含作為專案建置一部分產生的檔案的模式。

  • 從 $GIT_DIR/info/exclude 讀取的模式。

  • 從組態變數 core.excludesFile 指定的檔案讀取的模式。

要將模式放置在哪個檔案中取決於該模式的預期用途。

  • 應該進行版本控制並透過複製分發到其他儲存庫的模式（即所有開發人員都想要忽略的檔案）應該放在 .gitignore 檔案中。

  • 特定於某個儲存庫，但不需要與其他相關儲存庫共享的模式（例如，存在於儲存庫中但特定於某個使用者工作流程的輔助檔案）應該放在 $GIT_DIR/info/exclude 檔案中。

  • 使用者想要 Git 在所有情況下都忽略的模式（例如，使用者選擇的編輯器產生的備份或臨時檔案）通常會放入使用者 ~/.gitconfig 中的 core.excludesFile 指定的檔案中。其預設值為 $XDG_CONFIG_HOME/git/ignore。如果 $XDG_CONFIG_HOME 未設定或為空，則會改為使用 $HOME/.config/git/ignore。

底層 Git 工具，例如 *git ls-files* 和 *git read-tree*，會讀取由命令列選項指定的 gitignore 模式，或從由命令列選項指定的檔案讀取。較高層級的 Git 工具，例如 *git status* 和 *git add*，會使用上述來源指定的模式。

模式格式

  • 空白行不會匹配任何檔案，因此可以用作分隔符號以提高可讀性。

  • 以 # 開頭的行會被視為註解。在第一個雜湊符號 ("#") 前面加上反斜線 ("\")，以表示以雜湊符號開頭的模式。

  • 尾隨空格會被忽略，除非它們用反斜線 ("\") 括起來。

  • 可選的前綴 "!" 會否定該模式；任何先前模式排除的匹配檔案都將再次包含。如果該檔案的父目錄被排除，則無法重新包含該檔案。Git 出於效能考量不會列出被排除的目錄，因此無論在哪裡定義，包含檔案的任何模式都不會生效。在第一個 "!" 前面加上反斜線 ("\")，以表示以字面 "!" 開頭的模式，例如，"\!important!.txt"。

  • 斜線 "/" 用作目錄分隔符號。分隔符號可以出現在 .gitignore 搜尋模式的開頭、中間或結尾。

  • 如果模式的開頭或中間（或兩者都有）存在分隔符號，則該模式會相對於特定 .gitignore 檔案的目錄層級。否則，該模式也可能在 .gitignore 層級以下的任何層級匹配。

  • 如果模式的結尾存在分隔符號，則該模式只會匹配目錄，否則該模式可以匹配檔案和目錄。

  • 例如，模式 doc/frotz/ 會匹配 doc/frotz 目錄，但不會匹配 a/doc/frotz 目錄；然而 frotz/ 會匹配 frotz 和 a/frotz（都是目錄）（所有路徑都是相對於 .gitignore 檔案）。

  • 星號 "*" 會匹配任何內容，除了斜線。字元 "?" 會匹配任何一個字元，除了 "/"。可以使用範圍表示法，例如 [a-zA-Z]，來匹配範圍中的其中一個字元。有關更詳細的描述，請參閱 fnmatch(3) 和 FNM_PATHNAME 旗標。

針對完整路徑名稱匹配的模式中的兩個連續星號 ("**") 可能具有特殊含義

  • 前導的 "**" 後面跟著斜線表示在所有目錄中匹配。例如，"**/foo" 會在任何地方匹配檔案或目錄 "foo"，與模式 "foo" 相同。"**/foo/bar" 會在任何直接位於目錄 "foo" 下的任何地方匹配檔案或目錄 "bar"。

  • 尾隨的 "/**" 會匹配內部的一切內容。例如，"abc/**" 會匹配目錄 "abc" 內的所有檔案，相對於 .gitignore 檔案的位置，深度無限。

  • 斜線後面跟著兩個連續星號，然後再跟著斜線，會匹配零個或多個目錄。例如，"a/**/b" 會匹配 "a/b"、"a/x/b"、"a/x/y/b" 等等。

  • 其他連續星號會被視為一般星號，並會根據先前的規則進行匹配。

組態

可選的組態變數 core.excludesFile 指示一個包含要排除的檔案名稱模式的檔案路徑，類似於 $GIT_DIR/info/exclude。排除檔案中的模式會與 $GIT_DIR/info/exclude 中的模式一起使用。

注意事項

gitignore 檔案的目的是確保某些未被 Git 追蹤的檔案保持不被追蹤的狀態。

若要停止追蹤目前正在追蹤的檔案，請使用 *git rm --cached* 從索引中移除該檔案。然後可以將檔案名稱新增至 .gitignore 檔案，以防止該檔案在後續的提交中再次引入。

當從工作樹中存取 .gitignore 檔案時，Git 不會追蹤符號連結。當從索引或樹狀結構而非從檔案系統存取檔案時，這樣可以保持行為一致。

範例

  • 模式 hello.* 會匹配名稱以 hello. 開頭的任何檔案或目錄。如果只想將其限制在目錄中，而不是子目錄中，則可以在模式前面加上斜線，即 /hello.*；現在該模式會匹配 hello.txt、hello.c，但不會匹配 a/hello.java。

  • 模式 foo/ 會匹配目錄 foo 及其底下的路徑，但不會匹配一般檔案或符號連結 foo（這與 Git 中路徑規格的一般運作方式一致）

  • 模式 doc/frotz 和 /doc/frotz 在任何 .gitignore 檔案中都具有相同的效果。換句話說，如果模式中已經存在中間斜線，則前導斜線並不相關。

  • 模式 foo/* 會匹配 foo/test.json（一般檔案）、foo/bar（目錄），但不會匹配 foo/bar/hello.c（一般檔案），因為模式中的星號不匹配包含斜線的 bar/hello.c。

    $ git status
    [...]
    # Untracked files:
    [...]
    #       Documentation/foo.html
    #       Documentation/gitignore.html
    #       file.o
    #       lib.a
    #       src/internal.o
    [...]
    $ cat .git/info/exclude
    # ignore objects and archives, anywhere in the tree.
    *.[oa]
    $ cat Documentation/.gitignore
    # ignore generated html files,
    *.html
    # except foo.html which is maintained by hand
    !foo.html
    $ git status
    [...]
    # Untracked files:
    [...]
    #       Documentation/foo.html
    [...]

另一個範例

    $ cat .gitignore
    vmlinux*
    $ ls arch/foo/kernel/vm*
    arch/foo/kernel/vmlinux.lds.S
    $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore

第二個 .gitignore 會防止 Git 忽略 arch/foo/kernel/vmlinux.lds.S。

範例，排除除特定目錄 foo/bar 之外的所有內容（請注意 /* - 如果沒有斜線，萬用字元也會排除 foo/bar 內的所有內容）

    $ cat .gitignore
    # exclude everything except directory foo/bar
    /*
    !/foo
    /foo/*
    !/foo/bar

參見

git-rm[1]、gitrepository-layout[5]、git-check-ignore[1]

GIT

屬於 git[1] 套件的一部分

scroll-to-top