英語 ▾ トピック ▾ 最新バージョン ▾ gitcredentials は 2.49.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はこの煩わしさを軽減するために2つの方法を提供します。

  1. 特定の認証コンテキストに対するユーザー名の静的設定。

  2. パスワードをキャッシュまたは保存したり、システムのパスワードウォレットやキーチェーンと連携するためのクレデンシャルヘルパー。

最初の方法は、パスワードのための安全なストレージがない場合にシンプルで適切です。これは通常、以下の内容をconfigに追加することで設定されます。

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

一方、クレデンシャルヘルパーは、Gitがユーザー名とパスワードの両方を要求できる外部プログラムです。これらは通常、OSまたは他のプログラムによって提供される安全なストレージと連携します。あるいは、クレデンシャル生成ヘルパーが、特定のサーバーの認証情報を何らかの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に同梱)

コミュニティは、Gitクレデンシャルヘルパーの包括的なリストを https://git.dokyumento.jp/doc/credential-helpers で維持しています。

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は、2つのホストが同じドメインの一部であるかどうかを考慮せずに、ホスト名を正確に比較します。同様に、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- が前置されます。結果の文字列はシェルによって実行されます（したがって、例えばこれを foo --option=bar に設定すると、シェル経由で 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. ヘルパー文字列が「!」で始まる場合、それはシェルスニペットと見なされ、「!」の後のすべてがコマンドになります。

  2. そうでない場合、ヘルパー文字列が絶対パスで始まる場合、その文字列そのままがコマンドになります。

  3. そうでない場合、文字列「git credential-」がヘルパー文字列の前に付加され、その結果がコマンドになります。

結果のコマンドには「操作」引数が追加され（詳細は以下を参照）、その結果はシェルによって実行されます。

いくつかの指定例を以下に示します。

# 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 で有効にできるように支援する努力をすべきです。

ヘルパーが実行されると、コマンドラインに「操作」引数が1つ追加され、それは以下のいずれかです。

get

一致する認証情報が存在する場合、それを返します。

store

ヘルパーに適用可能な場合、認証情報を保存します。

erase

一致する認証情報があれば、ヘルパーのストレージから削除します。

認証情報の詳細はヘルパーの標準入力ストリームで提供されます。正確なフォーマットは、git credential プラミングコマンドの入出力フォーマットと同じです（詳細な仕様については git-credential[1] の INPUT/OUTPUT FORMAT セクションを参照してください）。

get 操作の場合、ヘルパーは標準出力に同じフォーマットで属性のリストを出力する必要があります（一般的な属性については git-credential[1] を参照）。ヘルパーは、提供すべき有用なものがない場合、サブセット、あるいは全く値を生成しないことも自由です。提供された属性は、Gitの認証情報サブシステムがすでに知っている属性を上書きします。認識されない属性は黙って破棄されます。

すべての属性を上書きすることは可能ですが、適切に動作するヘルパーは、ユーザー名とパスワード以外の属性についてはそうしないべきです。

ヘルパーが quit 属性を true または 1 の値で出力した場合、それ以上のヘルパーは参照されず、ユーザーへのプロンプトも表示されません（認証情報が提供されていない場合、操作は失敗します）。

同様に、ユーザー名とパスワードの両方が提供された場合、それ以上ヘルパーは参照されません。

store または erase 操作の場合、ヘルパーの出力は無視されます。

ヘルパーが要求された操作を実行できなかった場合、またはユーザーに潜在的な問題を通知する必要がある場合、標準エラー出力に書き込むことができます。

要求された操作をサポートしない場合（例：読み取り専用ストアまたはジェネレーター）、その要求を黙って無視する必要があります。

ヘルパーが他の操作を受け取った場合、その要求を黙って無視する必要があります。これにより、将来の操作が追加される余地が残されます（古いヘルパーは新しい要求を単に無視します）。

GIT

git[1] スイートの一部

scroll-to-top