簡體中文 ▾ 主題 ▾ 最新版本 ▾ gitignore 上次更新於 2.52.0

名稱

gitignore - 指定要忽略的未跟蹤檔案

概要

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

描述

一個 gitignore 檔案指定要忽略的未跟蹤檔案。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 標誌。

  • 反斜槓 ("\") 可用於轉義任何字元。例如，"\*" 匹配字面上的星號（而 "\a" 匹配 "a"，儘管那裡不需要轉義）。與 fnmatch(3) 一樣，模式末尾的反斜槓是無效模式，永遠不會匹配。

與完整路徑名匹配的模式中，兩個連續的星號（**）可能具有特殊含義：

  • 以斜槓開頭的 "**" 後跟斜槓表示在所有目錄中匹配。例如，"**/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 檔案中，以防止該檔案在後續提交中被重新引入。

Git 在訪問工作樹中的 .gitignore 檔案時不會遵循符號連結。這使得從索引或樹訪問檔案時的行為與從檔案系統訪問檔案時保持一致。

示例

  • 模式 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] 套件的一部分