git-describe(1)

SYNOPSIS

git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>…]
git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
git describe <blob>

DESCRIPTION

このコマンドは、コミットから到達可能な最新のタグを検索します。タグがコミットを指している場合は、タグのみが表示されます。それ以外の場合は、タグ名に、タグ付けされたオブジェクトの上に追加されたコミットの数と、最新のコミットの省略されたオブジェクト名の接尾辞が付きます。結果は「人間が読める」オブジェクト名であり、他のgitコマンドへのコミットを識別するためにも使用できます。

デフォルト(--all または --tags なし)では、 git describe は注釈付きタグのみを表示します。注釈付きタグの作成の詳細については、 git-tag(1) の -a および -s オプションを参照してください。

与えられたオブジェクトがブロブを参照している場合、それは <commit-ish>:<path> として表されます。これは、そブロブが <commit-ish> の <path> にあり、それ自体が、このブロブがHEADからの逆リビジョンウォークで発生する最初のコミットを表しているためです。

OPTIONS

<commit-ish>…: 説明するコミットっぽいオブジェクト名。省略した場合、デフォルトでHEADになります。
--dirty[=<mark>]
--broken[=<mark>]: 作業ツリーの状態を説明します。作業ツリーがHEADと一致する場合、出力は git describe HEAD と同じになります。作業ツリーにローカル変更がある場合、接尾辞 -dirty が追加されます。リポジトリが破損していて、Gitがローカルでの変更があるかどうかを判断できない場合(代わりに接尾辞 -broken を追加する --broken が指定されていない限り)、Gitはエラーになります。
--all: 注釈付きタグのみを使用する代わりに、 refs/ 名前空間にあるrefを使用してください。このオプションを使用すると、既知のブランチまたはリモート追跡ブランチまたは軽量タグを照合できます。
--tags: 注釈付きタグのみを使用する代わりに、 refs/tags 名前空間にあるタグを使用してください。このオプションを使用すると、軽量(注釈なし)タグのマッチングが可能になります。
--contains: そのコミットより前のタグを見つける代わりに、そのコミットの後に来るタグを見つけて、それを含めます。自動的に --tags の指定を含んでいます。
--abbrev=<n>: 省略されたオブジェクト名のデフォルトの16進数(これは、リポジトリ内のオブジェクトの数によって異なりますが、デフォルトは7桁です)を使用する代わりに、<n>桁、または一意のオブジェクト名を形成するために必要な数の桁を使用します。<n>が0の場合、長い形式は抑制され、最も近いタグのみが表示されます。
--candidates=<n>: 入力のコミットっぽいのを説明するための候補として最新の10個のタグのみを考慮するのではなく、最大<n>個の候補を考慮してください。 <n>を10より大きくすると、少し時間がかかりますが、より正確な結果が得られる場合があります。 <n>が0の場合、完全一致のみが出力されます。
--exact-match: 完全一致のみを出力します(タグは指定されたコミットを直接参照します)。これは --candidates=0 の同義語です。
--debug: 標準エラーに、検索戦略に関する情報を詳細に表示します。タグ名は引き続き標準出力で印刷されます。
--long: タグと一致する場合でも、常に長い形式(タグとコミット数と省略されたコミット名)を出力します。これは、問題のコミットがタグ付きバージョンである場合でも、 describe 出力にコミットオブジェクト名の一部を表示する場合に役立ちます。タグ名を発行するだけでなく、v1.2-0-gdeadbeeなどのコミットを記述します(オブジェクトdeadbeeを指すタグv1.2以降の0番目のコミット…)。
--match <pattern>: refs/tags/ プレフィックスを除いて、指定された glob(7) パターンに一致するタグのみを考慮してください。 --all と一緒に使用すると、パターンに一致するローカルブランチとリモート追跡参照も考慮されます。ただし、それぞれ refs/heads/ と refs/remotes/ プレフィックスは除外されます。他のタイプの参照は考慮されません。複数回指定すると、パターンのリストが蓄積され、いずれかのパターンに一致するタグが考慮されます。パターンのリストをクリアしてリセットするには、 --no-match を使用します。
--exclude <pattern>: refs/tags/ プレフィックスを除いて、指定された glob(7) パターンに一致するタグを考慮しないでください。 --all と一緒に使用すると、それぞれ refs/heads/ と refs/remotes/ プレフィックスを除いて、パターンに一致するローカルブランチとリモート追跡参照も考慮されません。他のタイプの参照は考慮されません。複数回指定すると、パターンのリストが蓄積され、いずれかのパターンに一致するタグが除外されます。 --match と組み合わせると、タグが少なくとも1つの --match パターンに一致し、 -exclude パターンのいずれにも一致しない場合にタグが考慮されます。パターンのリストをクリアしてリセットするには、 --no-exclude を使用します。
--always: ユニークさを保ちつつ省略されたコミットオブジェクトをフォールバックとして表示します。
--first-parent: マージコミットを確認したら、最初の親コミットのみを追跡します。これは、ターゲットコミットの履歴でマージされたブランチのタグを一致させたくない場合に役立ちます。

EXAMPLES

git.gitのツリーのようなナニカなら、以下のようなものを得るでしょう:

[torvalds@g5 git]$ git describe parent
v1.0.4-14-g2414721

つまり、私の「親」ブランチの現在のヘッドはv1.0.4に基づいていますが、その上にいくつかのコミットがあるため、describeは、追加のコミットの数(14)と、コミット自体の省略されたオブジェクト名(2414721)を最後に追加しました。

追加のコミットの数は、 git log v1.0.4..parent によって表示されるコミットの数です。ハッシュ接尾辞は -g + 親の先端コミットの明確な略語です(これは 2414721b194453f058079d897d13c4e377f92dc6 でした)。省略形の長さは、リポジトリ内のオブジェクトのおおよその数と、誕生日のパラドックスに関する少しの計算を使用して、リポジトリが大きくなるにつれてスケーリングされ、デフォルトでは最小7になります。 g プレフィックスは git を表し、ソフトウェアが管理されているSCMに応じてソフトウェアのバージョンを記述できるようにするために使用されます。これは、人々がさまざまなSCMを使用する可能性がある環境で役立ちます。

タグ名に対して git describe を実行すると、タグ名が表示されるだけです:

[torvalds@g5 git]$ git describe v1.0.4
v1.0.4

--all を使用すると、コマンドはブランチヘッドを参照として使用できるため、出力には参照パスも表示されます:

[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
tags/v1.0.0-21-g975b

[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
heads/lt/describe-7-g975b

`--abbrev`を0に設定すると、このコマンドを使用して、接尾辞(suffix)なしで最も近いタグ名を見つけることができます:

[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
tags/v1.0.0

注意: 今、これらのコマンドを入力した場合に取得するサフィックスは、かつてLinusがこれらのコマンドを実行したときに上記で見たものよりも長くなる可能性があることに注意してください。Gitリポジトリには、オブジェクト名が975bで始まり、当時は存在しなかった新しいコミットが含まれている可能性があります。 -g975b サフィックスだけでは、これらのコミットを明確にするのに十分でない場合があります。

SEARCH STRATEGY

提供されたコミットっぽいのごとに、 git describe は最初にそのコミットを正確にタグ付けするタグを探します。注釈付きタグは常に軽量タグよりも優先され、新しい日付のタグは常に古い日付のタグよりも優先されます。完全に一致するものが見つかると、その名前が出力され、検索が停止します。

完全に一致するものが見つからなかった場合、 git describe はコミット履歴をさかのぼって、タグ付けされた祖先コミットを見つけます。祖先のタグは、入力したコミットっぽい何かのSHA-1の省略形とともに出力されます。 --first-parent が指定された場合、ウォークは各コミットの最初の親のみを考慮します。

ウォーク中に複数のタグが見つかった場合は、入力コミットっぽい何かとは異なるコミットが最も少ないタグが選択されて出力されます。ここで異なるコミットの数は、 git log tag..input で示されるコミットの数として定義され、可能な限り最小のコミット数になります。

BUGS

ツリーオブジェクト、およびコミットを指していないタグオブジェクトは表わせません。ブロブを表す場合、ブロブを指す軽量タグは無視されますが、軽量タグが有利であるにもかかわらず、ブロブは依然として <committ-ish>:<path> として表されます。

GIT

Part of the git(1) suite

git-describe(1) Manual Page