SYNOPSIS

gitcli

DESCRIPTION

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

多くのコマンドは、引数としてリビジョン(revisions)(それはほとんどの場合「コミット」(commits)ですが、文脈とコマンドによっては「ツリーっぽい」(tree-ish)場合もあります)と、パス(paths)を取ります。ルールは以下のとおりです:

  • オプションは最初に指定し、 次に引数を指定します。 サブコマンドは、 ダッシュ付きのオプション(例えば --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 を使用できます(これら以外のパスのリビジョンを区別しないコマンドでも機能します。その場合、 --end-of-options は単に -- のエイリアスです)。

    ランダムなユーザー入力を処理することが期待されるスクリプトを作成するときは、適切な場所に曖昧さ回避の -- を配置することにより、どの引数がどれであるかを明示することをお勧めします。

  • 多くのコマンドではパスにワイルドカードを使用できますが、シェルによってワイルドカードが取得されないように保護する必要があります。以下の2つの意味は異なります: 

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

    前者を使用すると、シェルでfileglobを展開でき、作業ツリー内の C言語ソースファイル(dot-C)をインデックス内のバージョンで上書きするように要求されます。後者は *.c をGitに渡し、作業ツリーにチェックアウトするパターンに一致するインデックス内のパスを要求しています。git add hello.c; rm hello.c を実行後、前者では作業ツリーに hello.c は表示されませんが、後者では表示されます。

  • ファイルシステムの . (ピリオド)が現在のディレクトリを参照するのと同じように、Gitでリポジトリ名として . を使用すること(a dot-repository)は相対パスであり、あなたの現在のリポジトリを意味します。

Gitのスクリプトを作成するときに従う必要のある「フラグ」(flag)に関するルールは以下のとおりです:

  • 短いオプションは分割して単語に区切ります( git foo -ab よりも git foo -a -b を優先します。前者は機能しない事があります)。

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

  • Despite the above suggestion, when Arg is a path relative to the home directory of a user, e.g. ~/directory/file or ~u/d/f, you may want to use the separate form, e.g. git foo --file ~/mine, not git foo --file=~/mine. The shell will expand ~/ in the former to your home directory, but most shells keep the tilde in the latter. Some of our commands know how to tilde-expand the option value even when given in the stuck form, but not all of them do.

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

  • 多くのコマンドでは、長いオプション --option を一意であるかぎり短いプレフィックスのみに省略できます(たとえば、名前が opt で始まるオプションが他にない場合は、 --opt と入力して --option フラグを呼び出すことができます)。ただし、スクリプトを作成するときは、省略してはいけません。なぜならGitのより新しいバージョンで、名前が同じプレフィックスを共有する新しいオプションが導入される可能性があるからです。例えば --optimize が導入されると、以前は一意であった短いプレフィックス(--option , --opt)を一意では無くしてしまいます。

ENHANCED OPTION PARSER

Git 1.5.4シリーズ以降、多くのGitコマンド(この文書の執筆時点ではすべてではありませんが)は、拡張オプションパーサーを備えています。

以下は、この拡張オプションパーサーによって提供される機能のリストです。

Magic Options

拡張オプションパーサーがアクティブになっているコマンドはすべて、いくつかの魔法のコマンドラインオプション(magic command-line options)を理解します:

-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 があります。これはデフォルトで on です。 --no-track を使用して、その動作をオーバーライドできます。 --color と --no-color についても同じことが言えます。

Options trump configuration and environment

When there is a configuration variable or an environment variable that tweak the behaviour of an aspect of a Git command, and also a command line option that tweaks the same, the command line option overrides what the configuration and/or environment variable say.

For example, the user.name configuration variable is used to specify the human-readable name used by the git commit command to record the author and the committer name in a newly created commit. The GIT_AUTHOR_NAME environment variable, if set, takes precedence when deciding what author name to record. The --author=<author> command line option of the git commit command, when given, takes precedence over these two sources of information.

短いオプションのおまとめ

拡張オプションパーサーをサポートするコマンドを使用すると、短いオプションをおまとめできます。これは、たとえば、 git rm -rf や git clean -fdx を使用できることを意味します。

長いオプションの省略

拡張オプションパーサーをサポートするコマンドは、クソ詳しく長いオプションの一意なプレフィックスを受け入れますが、これは注意して使用してください。 たとえば、 git commit --amen は git commit --amend と入力したかのように動作しますが、これは、後のバージョンのGitが同じプレフィックスを共有する別のオプションを導入するまでのみ当てはまります。例えば git commit --amenity オプションが導入されたら一意で無くなります。

Separating argument from the option

コマンドラインで、オプションの必須パラメータを単に区切られた単語として記述することができます。これは、以下のすべての使い方が機能することを意味します:

$ 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

Magic filename options

Options that take a filename allow a prefix :(optional). For example:

git commit -F :(optional)COMMIT_EDITMSG
# if COMMIT_EDITMSG does not exist, the above is equivalent to
git commit

Like with configuration values, if the named file is missing Git behaves as if the option was not given at all. See "Values" in git-config(1).

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

作業ツリーおよび/またはインデックス内のファイルを処理できる多くのコマンドは、 --cached および/または --index オプションを使用できます。インデックスは元々キャッシュと呼ばれていたため、これら2つは同義語であると誤解されることがあります。ちゃいます。これらの2つのオプションは非常に異なることを意味します。

  • --cached オプションは、通常は作業ツリー内のファイルで機能するコマンドに、「インデックスのみで」機能するように要求するために使用されます。 たとえば、 git grep をコミットせずに使用して、どのコミットから文字列を検索するかを指定すると、通常は作業ツリー内のファイルで機能しますが、 --cached オプションを使用するとインデックス内の文字列を検索します。

  • --index オプションは、通常は作業ツリー内のファイルで機能するコマンドに、「インデックスにも」影響を与えるように要求するために使用されます。たとえば、 git stash apply は通常、stashエントリに記録された変更を作業ツリーにマージしますが、 --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

Part of the git(1) suite