簡體中文 ▾ 主題 ▾ 最新版本 ▾ gitcli 最後更新於 2.50.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 萬用字元展開。以下兩種情況含義不同：

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

    前者讓您的 shell 展開檔案萬用字元，您是要求工作區中的 .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。接受可選選項引數的選項必須以緊湊形式編寫。

  • 儘管有上述建議，當 Arg 是相對於使用者主目錄的路徑時，例如 ~/directory/file 或 ~u/d/f，您可能希望使用分離形式，例如 git foo --file ~/mine，而不是 git foo --file=~/mine。Shell 會將前者中的 ~/ 展開為您的主目錄，但大多數 shell 會保留後者中的波浪號。我們的一些命令知道即使以緊湊形式給出選項值也能進行波浪號展開，但並非所有命令都如此。

  • 當您向命令提供修訂版本引數時，請確保該引數與工作區中檔案的名稱不產生歧義。例如，不要寫 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 命令接受僅用於底層（plumbing）或已棄用的選項，這些選項在預設用法中是隱藏的。此選項提供完整的選項列表。

否定選項

帶有長選項名的選項可以透過新增字首 --no- 來否定。例如，git branch 有一個預設開啟的 --track 選項。您可以使用 --no-track 來覆蓋該行為。同樣適用於 --color 和 --no-color。

選項優先於配置和環境變數

當存在配置變數或環境變數用於調整 Git 命令某個方面的行為，並且也有一個命令列選項用於調整相同方面時，命令列選項會覆蓋配置和/或環境變數的設定。

例如，user.name 配置變數用於指定 git commit 命令在新建提交中記錄作者和提交者名稱時使用的可讀名稱。GIT_AUTHOR_NAME 環境變數（如果設定）在決定記錄哪個作者名稱時具有優先權。git commit 命令的 --author=<author> 命令列選項（如果提供）優先於這兩種資訊來源。

聚合短選項

支援增強選項解析器的命令允許您聚合短選項。這意味著您可以例如使用 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