簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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 檔案中，以阻止該檔案在後續提交中被重新引入。

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

scroll-to-top