SYNOPSIS

'git credential' (fill|approve|reject)

DESCRIPTION

Gitには、システム固有のヘルパーから資格情報(credentials)を保存および取得したり、ユーザーにユーザー名とパスワードの入力を求めたりするための内部インターフェイスがあります。 git-credentialコマンドは、Gitと同じ方法で資格情報を取得、保存、または要求する可能性のあるスクリプトにこのインターフェイスを公開します。 このスクリプト可能なインターフェイスの設計は、内部CAPIをモデル化しています。 概念の背景については、credential.hを参照してください。

git-credentialは、コマンドラインで「action」オプション(fill または approve または reject のいずれか)を取り、stdinで資格情報の説明(description)を読み取ります(INPUT/OUTPUT FORMAT を参照)

アクションが fill の場合、git-credentialは、構成ファイルを読み取るか、構成された資格情報ヘルパーに連絡するか、ユーザーにプロンプトを表示することにより、説明(description)に「username」および「password」属性を追加しようとします。次に、資格情報の説明(description)のユーザー名とパスワードの属性が、すでに提供されている属性とともにstdoutに出力されます。

アクションが approve(承認)の場合、git-credentialは、構成された資格情報ヘルパーに説明(description)を送信します。ヘルパーは、後で使用するために資格情報を保存する場合があります。

アクションが reject の場合、 git-credential は設定された資格情報ヘルパーに説明(description)を送信します。 これにより、 説明(description)に一致する保存済みの資格情報が消去される場合があります。

アクションが approve(承認)または reject(拒否)の場合、出力は生成されません。

TYPICAL USE OF GIT CREDENTIAL

git-credentialを使用するアプリケーションは、通常、以下の手順に従って git credential を使用します:

  1. コンテキストに基づいて資格情報の説明(description)を生成します。

    たとえば、 https://example.com/foo.git のパスワードが必要な場合は、以下の資格情報の説明(description)を生成できます(最後の空白行を忘れないでください。これは、アプリケーションがすべての情報の提供を終了したことを git credential に通知します):

    protocol=https
host=example.com
path=foo.git

  2. この説明(description)のユーザー名とパスワードを提供するようにgit-credentialに依頼してください。 これは、 git credential fill を実行し、ステップ(1)の説明(description)を標準入力に送ることで実行されます。完全な資格情報の説明(description)(資格情報自体、つまりログインとパスワードを含む)は、以下のように標準出力へ生成されます。 

    protocol=https
host=example.com
username=bob
password=secr3t

    ほとんどの場合、これは入力で指定された属性が出力で繰り返されることを意味しますが、Gitは資格情報の説明(description)を変更する場合もあります。たとえば、プロトコルがHTTP(s)であり、 credential.useHttpPath がfalseの場合、 path 属性を削除します。

    git credential が既にパスワードを知っていた場合、この手順では、ユーザーが password=secr3t を返す前に実際にこのパスワードを入力していなかった可能性があります(ユーザーが代わりにキーチェーンのロックを解除するためにパスワードを入力したか、キーチェーンがすでにロック解除している場合はユーザーの操作が行われなかった可能性があります)。

  3. 資格情報を使用し(たとえば、手順(2)のユーザー名とパスワードを使用してURLにアクセスします)、それが受け入れられるかどうかを確認します。

  4. パスワードの成功または失敗について報告します。資格情報によって操作が正常に完了することが許可された場合は、「approve」アクションでマークを付けて、「git credential」に次の呼び出しで再利用するように指示できます。操作中に資格情報が拒否された場合は、「reject」アクションを使用して、 git credential が次の呼び出しで新しいパスワードを要求するようにします。 いずれの場合も、 git credential には、ステップ(2)で取得した資格情報の説明(description)(ステップ(1)で提供されたものも含まれます)を指定する必要があります。

INPUT/OUTPUT FORMAT

git credential は、標準入力/標準出力で(使用するアクションに応じて)資格情報を読み取り および/また は書き込みます。この情報は、 git credential がログイン情報(ホスト、プロトコル、パスなど)を取得するキー、または取得する実際の資格データ(ユーザー名/パスワード)のいずれかに対応できます。

資格情報は、1行に1つの属性を持つ、名前付き属性のセットに分割されます。 各属性は、キーと値のペアで指定され、 = (等号)記号と、改行で続けます。

キーには、 = または改行またはNUL以外の任意のバイトを含めることができます。値には、改行またはNUL以外の任意のバイトを含めることができます。

C言語スタイルの配列括弧 [] で終わるキーを持つ属性は複数の値を持つことができます。 複数値属性の各インスタンスは、 順序付けられた値のリストを形成します。 繰り返される属性の順序によって値の順序が定義されます。 空の複数値属性(key[]=\n)は、 それ以前のエントリをすべてクリアし、 リストをリセットするように機能します。

いずれの場合も、すべてのバイトはそのまま扱われます(つまり、 クォートせず、 改行またはNULを含む値を送信することはできません)。 属性のリストは、 空白行またはファイルの終わりで終了します。

Gitは以下の属性を理解します:

protocol

資格情報が使用されるプロトコル(例: https)。

host

ネットワーク資格情報のリモートホスト名。これには、ポート番号が指定されている場合はそれも含まれます(例: example.com:8088)。

path

資格情報が使用されるパス。 たとえば、リモートhttpsリポジトリにアクセスする場合、これはサーバー上のリポジトリのパスになります。

username

私達が既に持っている(たとえば、URL、構成、ユーザー、または以前に実行したヘルパーから)場合、資格情報のユーザー名。

password

資格情報のパスワード(私達が保存を要求している場合)。

password_expiry_utc

OAuth アクセス・トークンなど、 生成されたパスワードには有効期限がある場合があります。ヘルパーから資格情報を読み取るとき、 git credential fill は期限切れのパスワードを無視します。 これは Unix 時間 UTC、 つまり 1970 年からの秒数で表されます。

oauth_refresh_token

OAuth リフレッシュ・トークンには、 OAuth アクセス・トークンであるパスワードに付随することがあります。 ヘルパーは、 この属性を password 属性と同様に機密(confidential)として扱う必要があります。 Git 自体は、 この属性に対して特別な振る舞いは行いません。

url

この特別な属性が git credential によって読み取られると、値はURLとして解析され、その構成要素が読み取られたかのように扱われます(たとえば、 url=https://example.com は protocol=https と host=example.com が提供されたかのように振る舞います)。これは、発信者がURL自体を解析することを回避するのに役立ちます。

注意:プロトコルの指定は必須であり、そして、URLでホスト名が指定されていない場合(たとえば "cert:///path/to/file")、資格情報には、値が空の文字列であるホスト名属性が含まれることに注意してください。

URLから欠落しているコンポーネント(たとえば、上記の例にユーザー名がないとか)は未設定のままになります。

wwwauth[]

1 つ以上の WWW-Authenticate 認証ヘッダーを含む HTTP レスポンスが Git によって受信されると、 これらは Git によって資格情報ヘルパーに渡されます。

各 WWW-Authenticate ヘッダー値は、 複数値属性 wwwauth[] として渡されます。 属性の順序は、HTTP レスポンスに表示される順序と同じです。 この属性は、 Gitから資格情報ヘルパーに追加情報を渡すための「一方通行」の属性です。

認識されない属性は通知なく破棄されます。

GIT

Part of the git(1) suite