Git
英文 ▾ 主題 ▾ 最新版本 ▾ gitcli 最後更新於 2.45.0

名稱

gitcli - Git 命令列介面和慣例

概要

gitcli

說明

本手冊描述整個 Git CLI 使用的慣例。

許多命令會將修訂 (通常是「提交」，但有時是「tree-ish」，取決於上下文和命令) 和路徑作為其參數。以下是規則

  • 選項優先，然後是參數。子命令可能採用帶破折號的選項 (可能需要自己的參數，例如「--max-parents 2」) 和參數。您應該先提供帶破折號的選項，然後再提供參數。某些命令可能會在您已經給出非選項參數之後接受帶破折號的選項 (這可能會使命令不明確)，但您不應該依賴它 (因為我們最終可能會找到一種方法通過強制執行「選項然後參數」規則來解決這些不明確性)。

  • 修訂優先，然後是路徑。例如，在 git diff v1.0 v2.0 arch/x86 include/asm-x86 中，v1.0 和 v2.0 是修訂，而 arch/x86 和 include/asm-x86 是路徑。

  • 當參數可能被誤解為修訂或路徑時，可以通過在它們之間放置 -- 來消除歧義。例如，git diff -- HEAD 是指「我的工作樹中有一個名為 HEAD 的檔案。請顯示我已暫存到索引中的版本與我工作樹中該檔案的內容之間的變更」，而不是「顯示 HEAD 提交與整個工作樹之間的差異」。您可以說 git diff HEAD -- 來要求後者。

  • 在沒有消除歧義的 -- 的情況下，Git 會做出合理的猜測，但當出現歧義時會報錯並要求您消除歧義。例如，如果您的工作樹中有一個名為 HEAD 的檔案，git diff HEAD 是不明確的，您必須說 git diff HEAD -- 或 git diff -- HEAD 來消除歧義。

  • 因為 -- 在某些命令中消除了修訂和路徑的歧義，因此它不能用於這些命令來分隔選項和修訂。您可以使用 --end-of-options 來實現此目的 (它也適用於不區分修訂和路徑的命令，在這種情況下它只是 -- 的別名)。

    當編寫預期處理隨機使用者輸入的腳本時，通過在適當的位置放置消除歧義的 --，明確指出哪些參數是什麼是一個好習慣。

  • 許多命令允許在路徑中使用萬用字元，但您需要保護它們免受 shell 的 globbing。這兩個意思不同

    $ git restore *.c
$ git restore \*.c

    前者讓您的 shell 擴展 fileglob，並且您要求將工作樹中的點 C 檔案用索引中的版本覆蓋。後者將 *.c 傳遞給 Git，並且您要求將索引中符合該模式的路徑檢出到您的工作樹。在執行 git add hello.c; rm hello.c 之後，您將在前者中不會看到工作樹中的 hello.c，但在後者中您會看到。

  • 正如檔案系統中的 . (點) 指的是當前目錄一樣，在 Git 中使用 . 作為儲存庫名稱 (點儲存庫) 是相對路徑，指的是您當前的儲存庫。

以下是關於您在編寫 Git 腳本時應遵循的「標誌」的規則

  • 將簡短選項拆分為單獨的單字 (偏好 git foo -a -b 而不是 git foo -ab，後者甚至可能不起作用)。

  • 當命令列選項需要參數時，請使用黏著形式。換句話說，對於簡短選項，請寫 git foo -oArg 而不是 git foo -o Arg，對於長選項，請寫 git foo --long-opt=Arg 而不是 git foo --long-opt Arg。需要可選選項參數的選項必須以黏著形式寫入。

  • 當您向命令提供修訂參數時，請確保該參數不會與工作樹中的檔案名稱混淆。例如，不要寫 git log -1 HEAD，而要寫 git log -1 HEAD --；如果您碰巧在工作樹中有一個名為 HEAD 的檔案，則前者將不起作用。

  • 許多命令允許將長選項 --option 縮寫為僅其唯一前綴 (例如，如果沒有其他選項的名稱以 opt 開頭，您可能可以拼寫 --opt 來調用 --option 標誌)，但是您在編寫腳本時應該完整地拼寫出來；稍後版本的 Git 可能會引入一個名稱共享相同前綴的新選項，例如 --optimize，使得曾經唯一的短前綴不再唯一。

增強選項解析器

從 Git 1.5.4 系列及更高版本開始，許多 Git 命令 (儘管在編寫本文時並非全部) 都帶有增強選項解析器。

以下是此選項解析器提供的功能的列表。

魔術選項

啟用增強選項解析器的命令都理解幾個魔術命令列選項

-h

提供命令的格式化輸出用法。

$ git describe -h
usage: git describe [<options>] <commit-ish>*
   or: git describe [<options>] --dirty

    --contains            find the tag that comes after the commit
    --debug               debug search strategy on stderr
    --all                 use any ref
    --tags                use any tag, even unannotated
    --long                always use long format
    --abbrev[=<n>]        use <n> digits to display SHA-1s

請注意，某些子命令 (例如 git grep) 在命令列上除了 -h 之外還有其他內容時，行為可能會有所不同，但是命令列上沒有其他任何內容的 git subcmd -h 旨在始終如一地提供用法。

--help-all

某些 Git 命令採用僅用於底層或已棄用的選項，並且這些選項會從預設用法中隱藏。此選項提供選項的完整列表。

否定選項

具有長選項名稱的選項可以通過在前面加上 --no- 來否定。例如，git branch 具有預設為開啟的選項 --track。您可以使用 --no-track 來覆蓋該行為。--color 和 --no-color 也是如此。

聚合短選項

支援增強選項解析器的命令允許您聚合短選項。這表示您可以例如使用 git rm -rf 或 git clean -fdx。

縮寫長選項

支援增強選項解析器的命令接受長選項的唯一前綴，就好像它被完整拼寫出來一樣，但是請謹慎使用。例如，git commit --amen 的行為就像您鍵入了 git commit --amend 一樣，但只有在更高版本的 Git 引入另一個共享相同前綴的選項 (例如 git commit --amenity 選項) 時才成立。

將參數與選項分離

您可以將選項的強制選項參數作為命令列上的單獨單字寫入。這表示以下所有用法都有效

$ git foo --long-opt=Arg
$ git foo --long-opt Arg
$ git foo -oArg
$ git foo -o Arg

但是，對於具有可選值的開關，不允許這樣做，必須使用黏著形式

$ git describe --abbrev HEAD     # correct
$ git describe --abbrev=10 HEAD  # correct
$ git describe --abbrev 10 HEAD  # NOT WHAT YOU MEANT

關於經常混淆的選項的說明

許多可以在工作樹和/或索引中的檔案上工作的命令可以採用 --cached 和/或 --index 選項。有時人們錯誤地認為，由於索引最初被稱為快取，因此這兩者是同義詞。它們不是 — 這兩個選項的意思非常不同。

  • --cached 選項用於要求通常在工作樹中的檔案上工作的命令僅在索引中工作。例如，git grep 在沒有使用提交來指定從哪個提交中尋找字串時，通常在工作樹中的檔案上工作，但使用 --cached 選項，它會在索引中尋找字串。

  • --index 選項用於要求通常在工作樹中的檔案上工作的命令也影響索引。例如，git stash apply 通常將快取條目中記錄的變更合併到工作樹，但使用 --index 選項，它也會將變更合併到索引中。

git apply 命令可以與 --cached 和 --index 一起使用 (但不能同時使用)。通常，該命令僅影響工作樹中的檔案，但是使用 --index，它會修補檔案及其索引條目，而使用 --cached，它僅修改索引條目。

另請參閱 https://lore.kernel.org/git/7v64clg5u9.fsf@assigned-by-dhcp.cox.net/ 和 https://lore.kernel.org/git/7vy7ej9g38.fsf@gitster.siamese.dyndns.org/ 以獲取更多資訊。

其他一些也能對工作目錄和/或索引中的檔案進行操作的指令，可以使用 --staged 和/或 --worktree 選項。

  • --staged 與 --cached 完全相同，都是用來要求指令僅對索引進行操作，而不對工作目錄進行操作。

  • --worktree 則相反，用來要求指令僅對工作目錄進行操作，而不對索引進行操作。

  • 這兩個選項可以同時指定，要求指令同時對索引和工作目錄進行操作。

GIT

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

scroll-to-top