日本語 ▾ トピック ▾ 最新バージョン ▾ 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 がローカルな変更があるかどうかを判断できない場合、'--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 に応じてソフトウェアのバージョンを記述するために使用されます。これは、人々が異なる 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