Git
日本語 ▾ トピック ▾ 最新バージョン ▾ gitcli は 2.45.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 --long-opt=Arg を git foo -o Arg や git foo --long-opt Arg の代わりに記述します。オプションのオプション引数を取るオプションは、スタック形式で記述する必要があります。

  • コマンドにリビジョンパラメーターを指定する場合は、パラメーターが作業ツリー内のファイルの名前とあいまいにならないようにしてください。例えば、git log -1 HEAD ではなく git log -1 HEAD -- と記述してください。作業ツリーに HEAD という名前のファイルがある場合、前者は機能しません。

  • 多くのコマンドでは、長いオプション --option を一意のプレフィックスにのみ省略できます（例えば、名前が opt で始まる他のオプションがない場合、--option フラグを呼び出すために --opt と記述できる場合があります）が、スクリプトを記述するときは完全にスペルアウトする必要があります。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 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