日本語 ▾ トピック ▾ 最新バージョン ▾ gitcli は 2.50.0 で最終更新されました

名前

gitcli - Git コマンドラインインターフェースと規則

概要

gitcli

説明

このマニュアルでは、Git CLI 全体で使用されている規則について説明します。

多くのコマンドは、引数としてリビジョン (多くの場合「コミット」ですが、コンテキストとコマンドによっては「ツリーオブジェクト」の場合もあります) とパスを受け取ります。以下にルールを示します。

  • オプションが最初に来て、その後に引数が来ます。サブコマンドはダッシュ付きオプション (独自の引数を持つ場合があります。例: "--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 を使用できます (これは、パスのリビジョンを区別しないコマンドでも機能し、その場合は単に -- のエイリアスです)。

    ランダムなユーザー入力を処理することが期待されるスクリプトを作成する場合、適切な場所に -- を置いて、どの引数が何であるかを明示的にすることは良い習慣です。

  • 多くのコマンドはパスにワイルドカードを許可しますが、シェルによるグロブから保護する必要があります。これら2つは異なる意味を持ちます。

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

    前者はシェルがファイルグロブを展開し、作業ツリー内のドットCファイルがインデックスのバージョンで上書きされることを要求します。後者は *.c を Git に渡し、パターンに一致するインデックス内のパスが作業ツリーにチェックアウトされることを要求します。git add hello.c; rm hello.c を実行した後、前者では作業ツリーに hello.c は表示されませんが、後者では表示されます。

  • ファイルシステムの . (ピリオド) がカレントディレクトリを指すように、Git でリポジトリ名として . (ドットリポジトリ) を使用することは相対パスであり、現在のリポジトリを意味します。

Git をスクリプト化する際に従うべき「フラグ」に関するルールを以下に示します。

  • 短いオプションを個別の単語に分割する (git foo -ab よりも git foo -a -b を優先します。後者は機能しない場合があります)。

  • コマンドラインオプションが引数を取る場合、密着形式を使用します。言い換えれば、短いオプションには git foo -o Arg の代わりに git foo -oArg を、長いオプションには git foo --long-opt Arg の代わりに git foo --long-opt=Arg を記述します。オプションの引数を取るオプションは、密着形式で記述する必要があります。

  • 上記の提案にもかかわらず、Arg がユーザーのホームディレクトリに対する相対パスである場合 (例: ~/directory/file または ~u/d/f)、個別の形式 (例: git foo --file ~/mine) を使用することをお勧めします。git foo --file=~/mine のように書くべきではありません。前者の場合、シェルは ~/ をホームディレクトリに展開しますが、ほとんどのシェルは後者の場合チルダを残します。一部のコマンドは、密着形式で指定された場合でもオプション値をチルダ展開する方法を知っていますが、すべてではありません。

  • コマンドにリビジョンパラメータを渡す場合、そのパラメータが作業ツリー内のファイル名とあいまいにならないようにしてください。例: 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 コマンドは、配管用または非推奨のオプションを受け取りますが、そのようなオプションはデフォルトの使用法から隠されています。このオプションは、オプションの完全なリストを表示します。

オプションの否定

長いオプション名を持つオプションは、--no- をプレフィックスとして付けることで否定できます。例えば、git branch には、デフォルトで オン になっている --track オプションがあります。--no-track を使用してこの動作を上書きできます。--color と --no-color も同様です。

オプションは設定と環境を優先する

Git コマンドの動作の側面を調整する設定変数または環境変数があり、かつ同じものを調整するコマンドラインオプションがある場合、コマンドラインオプションは設定変数および/または環境変数の指定を上書きします。

例えば、user.name 設定変数は、git commit コマンドが新しく作成されたコミットに作者とコミッター名を記録するために使用する、人間が読める名前を指定するために使用されます。GIT_AUTHOR_NAME 環境変数が設定されている場合、記録する作者名を決定する際に優先されます。git commit コマンドの --author=<author> コマンドラインオプションが指定されている場合、これらの2つの情報源よりも優先されます。

短いオプションの集約

拡張オプションパーサーをサポートするコマンドは、短いオプションを集約できます。これにより、例えば 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 オプションを受け取ることができます。インデックスは元々キャッシュと呼ばれていたため、これら2つは同義語であると誤解する人がいます。これらは 同義語ではありません ―― これら2つのオプションは非常に異なる意味を持ちます。

  • --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 はその逆で、インデックスではなく作業ツリーのみで動作するようにコマンドに指示するために使用されます。

  • この2つのオプションは、インデックスと作業ツリーの両方で動作するようにコマンドに指示するために一緒に指定できます。

GIT

git[1]スイートの一部

scroll-to-top