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

名前

gitcli - Git コマンドラインインターフェースと慣例

概要

gitcli

説明

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

多くのコマンドは、引数としてリビジョン（ほとんどの場合「コミット」、ただしコンテキストやコマンドによっては「tree-ish」）とパスを受け取ります。以下にそのルールを示します。

  • オプションは最初に、その後に引数が来ます。サブコマンドはダッシュ付きオプション（例: "--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を推奨。後者は機能しない場合があります）。

  • コマンドラインオプションが引数を取る場合、stuck形式を使用します。つまり、短いオプションの場合はgit foo -o Argではなくgit foo -oArgと書き、長いオプションの場合はgit foo --long-opt Argではなくgit foo --long-opt=Argと書きます。オプションの引数を取るオプションは、stuck形式で記述する必要があります。

  • 上記の提案にもかかわらず、Argがユーザーのホームディレクトリに対する相対パス（例：~/directory/fileや~u/d/f）である場合、git foo --file=~/mineではなく、git foo --file ~/mineのように分離した形式を使用したい場合があります。前者の~/はシェルによってホームディレクトリに展開されますが、ほとんどのシェルは後者ではチルダを保持します。一部のコマンドは、stuck形式で与えられた場合でもオプション値のチルダ展開方法を知っていますが、すべてのコマンドがそうではありません。

  • コマンドにリビジョンパラメータを与える場合、そのパラメータが作業ツリー内のファイル名と曖昧にならないようにしてください。例えば、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

ただし、これはオプション値を持つスイッチでは**許可されていません**。その場合はstuck形式を使用する必要があります。

$ git describe --abbrev HEAD     # correct
$ git describe --abbrev=10 HEAD  # correct
$ git describe --abbrev 10 HEAD  # NOT WHAT YOU MEANT

よく混同されるオプションに関する注意点

作業ツリー内および/またはインデックス内のファイルを操作できる多くのコマンドは、--cachedおよび/または--indexオプションを受け入れます。インデックスが元々キャッシュと呼ばれていたため、これらが同義語であると誤解する人がいますが、これらは**異なり**ます。これら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は反対で、インデックスではなく作業ツリーのみを操作するようコマンドに要求します。

  • 両方のオプションを一緒に指定することで、インデックスと作業ツリーの両方を操作するようコマンドに要求できます。

Git

git[1]スイートの一部

scroll-to-top