SYNOPSIS

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

DESCRIPTION

Gitは、操作を実行するためにユーザーからの資格情報を必要とする場合があります。たとえば、HTTP経由でリモートリポジトリにアクセスするために、ユーザー名とパスワードを要求する必要がある場合があります。一部のリモートリポジトリでは、個人アクセス・トークン(personal access token)または OAuth アクセス・トークンをパスワードとして受け入れます。このマニュアルでは、Gitがこれらの資格情報を要求するために使用するメカニズムと、これらの資格情報を繰り返し入力しないようにするためのいくつかの機能について説明します。

REQUESTING CREDENTIALS

資格情報ヘルパーが定義されていない場合、Gitは以下の戦略でユーザーにユーザー名とパスワードを要求します:

  1. GIT_ASKPASS 環境変数が設定されている場合、その環境変数で指定したプログラムが呼び出されます。コマンドラインでプログラムによって適切なプロンプトが表示され、ユーザーの入力が標準出力から読み取られます。

  2. それ以外の場合、 core.askPass 構成変数が設定されていると、その値は上記と同様に使用されます。

  3. それ以外の場合、SSH_ASKPASS 環境変数が設定されていると、その値は上記と同様に使用されます。

  4. それ以外の場合、端末でユーザーの入力が促されます。

AVOIDING REPETITION

同じ資格情報を何度も入力するのは面倒な場合があります。 Gitには、この煩わしさを軽減する2つの方法があります:

  1. 指定の認証コンテキストのためのユーザー名の静的構成。

  2. パスワードをキャッシュまたは保存するため、またはシステムパスワードウォレットまたはキーチェーンと対話するための資格情報ヘルパー。

1つ目は、パスワードに使用できる安全なストレージがない場合に簡単で適切です。これは通常、以下を構成に追加することによって設定します:

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

一方、資格情報ヘルパーは、Gitがユーザー名とパスワードの両方を要求できる外部プログラムです。これらは通常、OSまたは他のプログラムによって提供される安全なストレージとインターフェイスします。あるいは、資格情報生成ヘルパーが、何らかの API を介して特定のサーバーの資格情報を生成する場合もあります。

ヘルパーを使用するには、最初に使用するヘルパーを選択する必要があります。Gitには現在、以下のヘルパーが含まれています:

cache

資格情報をメモリに短期間キャッシュします。 詳細については git-credential-cache(1) を参照してください。

store

資格情報をディスクに無期限に保存します。詳細については git-credential-store(1) を参照してください。

サードパーティのヘルパーがインストールされている場合もあります。 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

CREDENTIAL CONTEXTS

Gitは、各資格情報がURLによって定義されたコンテキストを持っていると見なします。このコンテキストは、コンテキスト固有の構成を検索するために使用され、すべてのヘルパーに渡されます。ヘルパーは、これを安全なストレージへのインデックスとして使用できます。

たとえば、 https://example.com/foo.git にアクセスしていると想像してください。Gitが構成ファイルを調べてセクションがこのコンテキストに一致するかどうかを確認するとき、コンテキストが構成ファイル内のパターンのより具体的なサブセットである場合、Gitは2つが一致すると見なします。たとえば、設定ファイルに以下がある場合:

[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 部分の照合に加えてパス部分も一致する) https://example.com/bar/baz.git の設定エントリとは一致しますが、 https://example.com/bar 構成エントリとは一致しません。

CONFIGURATION OPTIONS

コンテキストのオプションは、 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」に設定してください。

CUSTOM HELPERS

あなた独自のカスタムヘルパーを作成して、資格情報を保持している任意のシステムとインターフェイスすることができます。

資格情報ヘルパーは、資格情報を長期ストレージとの間でフェッチまたは保存するためにGitによって実行されるプログラムです(「長期」とは単一のGitプロセスよりも単純に長いという意味です。たとえば、資格情報はメモリ内に数分間、またはディスク上で無期限に保存される場合があります)。

各ヘルパーは、構成変数 credential.helper の単一の文字列で指定されます(その他 git-config(1) を参照)。文字列はGitによって、以下のルールを使用して実行されるコマンドに変換されます:

  1. ヘルパー文字列が "!" で始まる場合、それはシェルスニペットと見なされ、 "!" の後のすべてが コマンドになります。

  2. それ以外の場合、ヘルパー文字列が絶対パスで始まる場合は、文字列がそのままコマンドとして扱われます。

  3. それ以外の場合は、文字列 "git credential-" がヘルパー文字列の前に付加され、その結果がコマンドになります。

結果のコマンドには「operation」引数が追加され(詳細は下記参照)、結果はシェルによって実行されます。

仕様の例を以下に示します:

# 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'"

# 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

もしあれば、ヘルパーのストレージから一致する資格情報を削除します。

資格情報の詳細は、ヘルパーの標準入力ストリームで提供されます。正確な形式は、 git credential 配管コマンドの 入力/出力形式 と同じです(詳細な仕様については、 git-credential(1) の「INPUT/OUTPUT FORMAT」のセクションを参照してください)。

`get`操作の場合、ヘルパーは標準出力の属性のリストを同じ形式で作成する必要があります(一般的な属性については git-credential(1) を参照してください)。ヘルパーはサブセットを自由に作成できます。提供するのに役立つものがない場合は、値をまったく作成しません。提供された属性は、Gitの資格情報サブシステムによってすでに知られている属性を上書きします。認識されない属性は通知なく破棄されます。

すべての属性を上書きすることが可能ですが、正常に動作するヘルパーは、ユーザー名とパスワード以外の属性については上書きしないようにする必要があります。

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

同様に、ユーザー名とパスワードの両方が提供されると、ヘルパーに相談することはありません。

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

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

要求された操作(読み取り専用ストアや生成など)をサポートしていない場合は、要求を黙って無視する必要があります。

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

GIT

Part of the git(1) suite