日本語 ▾ トピック ▾ 最新バージョン ▾ 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 オプションを参照してください。

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

オプション

<commit-ish>…​

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

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

作業ツリーの状態を記述します。作業ツリーがHEADと一致する場合、出力は「git describe HEAD」と同じです。作業ツリーにローカル変更がある場合、「-dirty」が追加されます。リポジトリが破損しており、Gitがローカル変更があるかどうかを判断できない場合、Gitはエラーになります。ただし、「--broken」が指定されている場合は、代わりに「-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 <パターン>

指定されたglob(7)パターンに一致するタグのみを考慮し、「refs/tags/」プレフィックスは除外します。--allと一緒に使用した場合、パターンに一致するローカルブランチとリモートトラッキング参照も考慮されますが、それぞれ「refs/heads/」と「refs/remotes/」プレフィックスは除外されます。他の種類の参照は決して考慮されません。複数回指定された場合、パターンのリストが蓄積され、いずれかのパターンに一致するタグが考慮されます。パターンのリストをクリアしてリセットするには、--no-matchを使用します。

--exclude <パターン>

指定されたglob(7)パターンに一致するタグは考慮しません。「refs/tags/」プレフィックスは除外します。--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

つまり、「parent」ブランチの現在のHEADは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に設定すると、このコマンドはサフィックスなしで最も近いタグ名を見つけるために使用できます。

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

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

検索戦略

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

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

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

バグ

ツリーオブジェクトおよびコミットを指さないタグオブジェクトは記述できません。ブロブを記述する場合、ブロブを指す軽量タグは無視されますが、軽量タグが好ましいにもかかわらず、ブロブは引き続き<commit-ish>:<path>として記述されます。

Git

git[1]スイートの一部

scroll-to-top