Git
英語 ▾ トピック ▾ 最新バージョン ▾ git-describe は 2.42.0 で最後に更新されました

名前

git-describe - 利用可能な参照に基づいて、オブジェクトに人間が読める名前を付ける

概要

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

説明

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

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

指定されたオブジェクトがblobを参照する場合、<commit-ish>:<path>として記述されます。これにより、blobは<commit-ish>の<path>で見つけることができ、それ自体がHEADからの逆方向リビジョンウォークでこのblobが最初に発生するコミットを記述します。

オプション

<commit-ish>…​

記述するコミットのようなオブジェクト名。省略した場合はHEADがデフォルトになります。

--dirty[=<mark>]
--broken[=<mark>]

作業ツリーの状態を記述します。作業ツリーがHEADと一致する場合、出力は「git describe HEAD」と同じです。作業ツリーにローカルな変更がある場合、「-dirty」が追加されます。リポジトリが破損していて、Gitがローカルな変更の有無を判断できない場合、' --broken 'が指定されていない限り、Gitはエラーを発生させ、「-broken」のサフィックスを追加します。

--all

注釈付きタグのみを使用する代わりに、refs/名前空間にあるすべての参照を使用します。このオプションにより、既知のブランチ、リモート追跡ブランチ、または軽量タグのいずれにも一致させることができます。

--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

マージコミットを見ると、最初の親コミットのみをフォローします。これは、ターゲットコミットの履歴でマージされたブランチのタグに一致させたくない場合に役立ちます。

例

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を使用する可能性のある環境で役立ちます。

タグ名で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に設定すると、コマンドを使用して、サフィックスなしで最も近いタグ名を見つけることができます。

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

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

検索戦略

指定されたコミットishごとに、git describeはまず、そのコミットを正確にタグ付けしているタグを探します。アノテーション付きタグは常に軽量タグよりも優先され、新しい日付のタグは常に古い日付のタグよりも優先されます。完全一致が見つかった場合、その名前が出力され、検索は停止します。

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

ウォーク中に複数のタグが見つかった場合、入力されたコミットishとの差が最も少ないコミットを持つタグが選択され、出力されます。ここで、差が最も少ないコミットとは、git log tag..inputによって表示されるコミットの数ができるだけ少ないことを意味します。

バグ

ツリーオブジェクトと、コミットを指していないタグオブジェクトは記述できません。BLOBを記述する場合、BLOBを指している軽量タグは無視されますが、軽量タグの方が好ましいにもかかわらず、BLOBは依然として<コミットish>:<パス>として記述されます。

Git

git[1]スイートの一部

scroll-to-top