簡體中文 ▾ 主題 ▾ 最新版本 ▾ gitcredentials 最後更新於 2.50.0

名稱

gitcredentials - 向 Git 提供使用者名稱和密碼

概要

git config credential.https://example.com.username myusername
git config credential.helper "$helper $options"

描述

Git 有時需要使用者憑證來執行操作；例如，它可能需要請求使用者名稱和密碼以透過 HTTP 訪問遠端倉庫。某些遠端倉庫接受個人訪問令牌或 OAuth 訪問令牌作為密碼。本手冊描述了 Git 請求這些憑證的機制，以及一些避免重複輸入這些憑證的功能。

請求憑證

在未定義任何憑證助手的情況下，Git 將嘗試以下策略向用戶請求使用者名稱和密碼：

  1. 如果設定了 GIT_ASKPASS 環境變數，則呼叫該變數指定的程式。命令列上會向該程式提供合適的提示，使用者的輸入將從其標準輸出中讀取。

  2. 否則，如果設定了 core.askPass 配置變數，則其值將按上述方式使用。

  3. 否則，如果設定了 SSH_ASKPASS 環境變數，則其值將按上述方式使用。

  4. 否則，將提示使用者在終端上輸入。

避免重複

重複輸入相同的憑證可能會很麻煩。Git 提供了兩種方法來減少這種困擾：

  1. 為給定的身份驗證上下文靜態配置使用者名稱。

  2. 憑證助手，用於快取或儲存密碼，或與系統密碼錢包或鑰匙串互動。

第一種方法很簡單，並且在你沒有可用於密碼的安全儲存時適用。通常透過將以下內容新增到你的配置中來配置它：

[credential "https://example.com"]
	username = me

另一方面，憑證助手是 Git 可以從中請求使用者名稱和密碼的外部程式；它們通常與作業系統或其他程式提供的安全儲存介面。此外，憑證生成助手可能透過某些 API 為特定伺服器生成憑證。

要使用助手，你必須首先選擇一個（有關列表，請參閱下文）。

你也可能安裝了第三方助手；在 git help -a 的輸出中搜索 credential-*，並查閱各個助手的文件。一旦你選擇了助手，你可以透過將其名稱放入 credential.helper 變數來告訴 Git 使用它。

  1. 尋找一個助手。

    $ git help -a | grep credential-
credential-foo

  2. 閱讀其描述。

    $ git help credential-foo

  3. 告訴 Git 使用它。

    $ git config --global credential.helper foo

可用助手

Git 目前包含以下助手：

cache

在記憶體中短期快取憑證。有關詳細資訊，請參閱 git-credential-cache[1]。

store

將憑證無限期儲存在磁碟上。有關詳細資訊，請參閱 git-credential-store[1]。

包含安全持久儲存的流行助手包括：

  • git-credential-libsecret (Linux)

  • git-credential-osxkeychain (macOS)

  • git-credential-wincred (Windows)

  • Git Credential Manager (跨平臺，包含在 Git for Windows 中)

社群在 https://git-scm.tw/doc/credential-helpers 維護著一份全面的 Git 憑證助手列表。

OAuth

輸入密碼或個人訪問令牌的另一種方法是使用 OAuth 憑證助手。初始身份驗證會開啟一個瀏覽器視窗到主機。後續身份驗證在後臺進行。許多流行的 Git 主機支援 OAuth。

支援 OAuth 的流行助手包括：

憑證上下文

Git 認為每個憑證都有一個由 URL 定義的上下文。此上下文用於查詢特定於上下文的配置，並傳遞給任何助手，助手可能將其用作安全儲存的索引。

例如，假設我們正在訪問 https://example.com/foo.git。當 Git 在配置檔案中檢視某個部分是否與此上下文匹配時，如果上下文是配置檔案中模式的更具體子集，則它們被認為是匹配的。例如，如果你的配置檔案中有以下內容：

[credential "https://example.com"]
	username = foo

那麼我們將匹配：協議相同，主機相同，並且“模式”URL 完全不關心路徑元件。但是，此上下文將不匹配：

[credential "https://kernel.org"]
	username = foo

因為主機名不同。它也不會匹配 foo.example.com；Git 完全比較主機名，不考慮兩個主機是否屬於同一域。同樣，http://example.com 的配置條目也不會匹配：Git 完全比較協議。但是，你可以在域名中使用萬用字元和其他模式匹配技術，就像 http.<URL>.* 選項一樣。

如果“模式”URL 確實包含路徑元件，那麼這也必須精確匹配：上下文 https://example.com/bar/baz.git 將匹配 https://example.com/bar/baz.git 的配置條目（除了匹配 https://example.com 的配置條目），但不會匹配 https://example.com/bar 的配置條目。

配置選項

憑證上下文的選項可以在 credential.*（適用於所有憑證）或 credential.<URL>.* 中配置，其中 <URL> 如上所述匹配上下文。

以下選項在任一位置都可用：

helper

外部憑證助手的名稱以及任何相關選項。如果助手名稱不是絕對路徑，則會預置字串 git credential-。生成的字串由 shell 執行（因此，例如，將其設定為 foo --option=bar 將透過 shell 執行 git credential-foo --option=bar）。有關其使用示例，請參閱特定助手的文件。

如果 credential.helper 配置變數有多個例項，則每個助手將依次嘗試，並可能提供使用者名稱、密碼或不提供任何內容。一旦 Git 獲得了使用者名稱和未過期的密碼，將不再嘗試其他助手。

如果 credential.helper 配置為空字串，則這會將助手列表重置為空（因此，你可以透過配置空字串助手，然後是所需的助手集，來覆蓋由低優先順序配置檔案設定的助手）。

username

預設使用者名稱，如果 URL 中未提供。

useHttpPath

預設情況下，Git 不認為 http URL 的“路徑”元件值得透過外部助手進行匹配。這意味著為 https://example.com/foo.git 儲存的憑證也將用於 https://example.com/bar.git。如果你確實想區分這些情況，請將此選項設定為 true。

自定義助手

你可以編寫自己的自定義助手，以與你儲存憑證的任何系統進行介面。

憑證助手是 Git 執行的程式，用於從長期儲存中獲取或儲存憑證（其中“長期”只是比單個 Git 程序更長；例如，憑證可以儲存在記憶體中幾分鐘，或無限期地儲存在磁碟上）。

每個助手都由配置變數 credential.helper（以及其他，參見 git-config[1]）中的單個字串指定。Git 根據以下規則將該字串轉換為要執行的命令：

  1. 如果助手字串以“!”開頭，則它被視為 shell 片段，並且“!”之後的所有內容都成為命令。

  2. 否則，如果助手字串以絕對路徑開頭，則原樣助手字串成為命令。

  3. 否則，將字串“git credential-”預置到助手字串，結果成為命令。

然後，生成的命令會附加一個“操作”引數（有關詳細資訊，請參閱下文），並由 shell 執行結果。

以下是一些示例規範：

# run "git credential-foo"
[credential]
	helper = foo

# same as above, but pass an argument to the helper
[credential]
	helper = "foo --bar=baz"

# the arguments are parsed by the shell, so use shell
# quoting if necessary
[credential]
	helper = "foo --bar='whitespace arg'"

# store helper (discouraged) with custom location for the db file;
# use `--file ~/.git-secret.txt`, rather than `--file=~/.git-secret.txt`,
# to allow the shell to expand tilde to the home directory.
[credential]
	helper = "store --file ~/.git-secret.txt"

# you can also use an absolute path, which will not use the git wrapper
[credential]
	helper = "/path/to/my/helper --with-arguments"

# or you can specify your own shell snippet
[credential "https://example.com"]
	username = your_user
	helper = "!f() { test \"$1\" = get && echo \"password=$(cat $HOME/.secret)\"; }; f"

一般來說，上述規則（3）對使用者來說最簡單。憑證助手的作者應努力透過將其程式命名為“git-credential-$NAME”，並在安裝期間將其放入 $PATH 或 $GIT_EXEC_PATH 來幫助其使用者，這將允許使用者使用 git config credential.helper $NAME 啟用它。

當助手執行時，其命令列將附加一個“操作”引數，該引數是以下之一：

get

返回匹配的憑證（如果存在）。

store

儲存憑證，如果適用於助手。

erase

從助手的儲存中刪除匹配的憑證（如果存在）。

憑證的詳細資訊將透過助手的 stdin 流提供。確切的格式與 git credential 底層命令的輸入/輸出格式相同（有關詳細規範，請參閱 git-credential[1] 中的 INPUT/OUTPUT FORMAT 部分）。

對於 get 操作，助手應以相同的格式在 stdout 上生成屬性列表（有關常見屬性，請參閱 git-credential[1]）。助手可以自由地生成子集，甚至在沒有有用的值時完全不生成任何值。任何提供的屬性都將覆蓋 Git 憑證子系統已知的屬性。無法識別的屬性將被靜默丟棄。

雖然可以覆蓋所有屬性，但表現良好的助手應避免對使用者名稱和密碼以外的任何屬性執行此操作。

如果助手輸出一個值為 true 或 1 的 quit 屬性，則不會再諮詢其他助手，也不會提示使用者（如果未提供憑證，則操作將失敗）。

同樣，一旦提供了使用者名稱和密碼，將不再諮詢其他助手。

對於 store 或 erase 操作，助手的輸出將被忽略。

如果助手未能執行請求的操作或需要通知使用者潛在問題，它可能會寫入 stderr。

如果它不支援請求的操作（例如，只讀儲存或生成器），它應該靜默忽略該請求。

如果助手收到任何其他操作，它應該靜默忽略該請求。這為將來新增新操作留下了空間（較舊的助手將只忽略新請求）。

GIT

Git[1] 套件的一部分

scroll-to-top