describe

NAME名

git-describe - Give an object a human readable name based on an available refgit-describe - 利用可能な参照に基づいてオブジェクトに人間が読める名前を付ける

SYNOPSIS概要

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

DESCRIPTION説明

The command finds the most recent tag that is reachable from a commit. If the tag points to the commit, then only the tag is shown. Otherwise, it suffixes the tag name with the number of additional commits on top of the tagged object and the abbreviated object name of the most recent commit. The result is a "human-readable" object name which can also be used to identify the commit to other git commands.このコマンドは、コミットから到達可能な最新のタグを見つけます。タグがコミットを指している場合は、タグのみが表示されます。それ以外の場合は、タグ付きオブジェクトの上に追加のコミットの数と最新のコミットの省略されたオブジェクト名をタグ名の後に付けます。その結果、他のgitコマンドへのコミットを識別するためにも使用できる「人間が読める」オブジェクト名が得られます。

By default (without --all or --tags) git describe only shows annotated tags. For more information about creating annotated tags see the -a and -s options to git-tag[1].デフォルト（--allまたは--tagsなし）ではgit describe、注釈付きタグのみが表示されます。注釈付きタグの作成に関する詳細は、git-tag [1]の-aおよび-sオプションを参照してください。

If the given object refers to a blob, it will be described as <commit-ish>:<path>, such that the blob can be found at <path> in the <commit-ish>, which itself describes the first commit in which this blob occurs in a reverse revision walk from HEAD.所与のオブジェクトがブロブを参照する場合、それは<commit-ish>:<path>、ブロブがで発見され得るよう<path>に<commit-ish>、それ自体が、このブロブがＨＥＡＤからの逆の改訂ウォークで発生する最初のコミットを説明するように説明される。

OPTIONSオプション

<commit-ish>… <commit-ish>…: Commit-ish object names to describe. Defaults to HEAD if omitted.説明するコミット風オブジェクト名。省略すると、デフォルトのHEADになります。
--dirty[=<mark>] --dirty [= <mark>]
--broken[=<mark>] - 壊れた[= <mark>]: Describe the state of the working tree. When the working tree matches HEAD, the output is the same as "git describe HEAD". If the working tree has local modification "-dirty" is appended to it. If a repository is corrupt and Git cannot determine if there is local modification, Git will error out, unless ‘--broken’ is given, which appends the suffix "-broken" instead.作業ツリーの状態を説明してください。作業ツリーがHEADと一致すると、出力は "git describe HEAD"と同じになります。作業ツリーにローカル修正がある場合は、 " - 汚れた"が追加されます。リポジトリが破損していて、Gitがローカルの変更があるかどうかを判断できない場合、Gitは、 ' - broken'が与えられていない限りエラーになります。
--all - すべて: Instead of using only the annotated tags, use any ref found in refs/ namespace. This option enables matching any known branch, remote-tracking branch, or lightweight tag.注釈付きタグのみを使用するのではなく、refs/名前空間にある任意の参照を使用してください。このオプションは、既知のブランチ、リモートトラッキングブランチ、または軽量タグのマッチングを可能にします。
--tags - タグ: Instead of using only the annotated tags, use any tag found in refs/tags namespace. This option enables matching a lightweight (non-annotated) tag.注釈付きタグのみを使用するのではなく、refs/tags名前空間で見つかった任意のタグを使用してください。このオプションは、軽量（注釈なし）タグのマッチングを可能にします。
--contains - 含む: Instead of finding the tag that predates the commit, find the tag that comes after the commit, and thus contains it. Automatically implies --tags.コミットの前のタグを見つける代わりに、コミットの後に来るタグを見つけ、それを含んでください。自動的に--tagsを意味します。
--abbrev=<n> --abbrev = <n>: Instead of using the default 7 hexadecimal digits as the abbreviated object name, use <n> digits, or as many digits as needed to form a unique object name. An <n> of 0 will suppress long format, only showing the closest tag.省略時のオブジェクト名としてデフォルトの7桁の16進数を使用する代わりに、<n>桁、または固有のオブジェクト名を形成するのに必要なだけの桁数を使用してください。0の<n>はロングフォーマットを抑制し、最も近いタグのみを表示します。
--candidates=<n> --candidates = <n>: Instead of considering only the 10 most recent tags as candidates to describe the input commit-ish consider up to <n> candidates. Increasing <n> above 10 will take slightly longer but may produce a more accurate result. An <n> of 0 will cause only exact matches to be output.入力コミットを記述するための候補として最新の10個のタグだけを検討する代わりに、<n>個までの候補を検討します。<n>を10より大きくすると少し時間がかかりますが、より正確な結果が得られる可能性があります。<n>が0の場合、完全一致のみが出力されます。
--exact-match - 完全に一致: Only output exact matches (a tag directly references the supplied commit). This is a synonym for --candidates=0.完全一致のみを出力します（タグは指定されたコミットを直接参照します）。これは--candidates = 0の同義語です。
--debug - デバッグ: Verbosely display information about the searching strategy being employed to standard error. The tag name will still be printed to standard out.標準エラーに対して採用されている検索方法に関する情報を詳細に表示します。タグ名は標準出力に出力されます。
--long - 長いです: Always output the long format (the tag, the number of commits and the abbreviated commit name) even when it matches a tag. This is useful when you want to see parts of the commit object name in "describe" output, even when the commit in question happens to be a tagged version. Instead of just emitting the tag name, it will describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2 that points at object deadbee….).タグと一致する場合でも、常に長い形式（タグ、コミット数、および省略されたコミット名）を出力します。問題のコミットがタグ付きバージョンである場合でも、 "describe"の出力にコミットオブジェクト名の一部を表示したい場合に便利です。単にタグ名を発行するのではなく、そのようなコミットをv1.2-0-gdeadbeeと記述します（タグv1.2から0番目のコミットはオブジェクトdeadbeeを指しています…）。
--match <pattern> --match <パターン>: Only consider tags matching the given glob(7) pattern, excluding the "refs/tags/" prefix. If used with --all, it also considers local branches and remote-tracking references matching the pattern, excluding respectively "refs/heads/" and "refs/remotes/" prefix; references of other types are never considered. If given multiple times, a list of patterns will be accumulated, and tags matching any of the patterns will be considered. Use --no-match to clear and reset the list of patterns.glob(7)"refs / tags /"プレフィックスを除いて、与えられたパターンにマッチするタグのみを考慮してください。とともに使用した場合は--all、 "refs / heads /"と "refs / remotes /"の接頭辞をそれぞれ除いて、パターンに一致するローカルブランチとリモートトラッキングの参照も考慮されます。他の型の参照は考慮されません。複数回指定した場合は、パターンのリストが蓄積され、いずれかのパターンに一致するタグが考慮されます。--no-matchパターンのリストをクリアしてリセットするために使用します。
--exclude <pattern> --exclude <パターン>: Do not consider tags matching the given glob(7) pattern, excluding the "refs/tags/" prefix. If used with --all, it also does not consider local branches and remote-tracking references matching the pattern, excluding respectively "refs/heads/" and "refs/remotes/" prefix; references of other types are never considered. If given multiple times, a list of patterns will be accumulated and tags matching any of the patterns will be excluded. When combined with --match a tag will be considered when it matches at least one --match pattern and does not match any of the --exclude patterns. Use --no-exclude to clear and reset the list of patterns.glob(7)"refs / tags /"プレフィックスを除いて、与えられたパターンにマッチするタグを考慮しないでください。とともに使用した場合--all、ローカルブランチとリモートトラッキング参照がパターンに一致することも考慮されません（それぞれ "refs / heads /"と "refs / remotes /"プレフィックスを除く）。他の型の参照は考慮されません。複数回指定した場合、パターンのリストが累積され、いずれかのパターンに一致するタグが除外されます。--matchと組み合わせると、タグは少なくとも1つの--matchパターンと一致し、 - excludeパターンのいずれとも一致しないときに考慮されます。--no-excludeパターンのリストをクリアしてリセットするために使用します。
--always - 常に: Show uniquely abbreviated commit object as fallback.一意に省略されたコミットオブジェクトを代替として表示します。
--first-parent - 最初の親: Follow only the first parent commit upon seeing a merge commit. This is useful when you wish to not match tags on branches merged in the history of the target commit.マージコミットを見て最初の親コミットのみをたどります。これは、ターゲットコミットの履歴にマージされたブランチのタグを一致させたくない場合に便利です。

EXAMPLES例

With something like git.git current tree, I get:git.git現在のツリーのようなもので、私は得ます：

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

i.e. the current head of my "parent" branch is based on v1.0.4, but since it has a few commits on top of that, describe has added the number of additional commits ("14") and an abbreviated object name for the commit itself ("2414721") at the end.つまり、私の "親"ブランチの現在のヘッドはv1.0.4に基づいていますが、それに加えていくつかのコミットがあるので、describeは追加のコミットの数（ "14"）とコミットの省略名を追加しました最後にそれ自体（ "2414721"）を追加します。

The number of additional commits is the number of commits which would be displayed by "git log v1.0.4..parent". The hash suffix is "-g" + 7-char abbreviation for the tip commit of parent (which was 2414721b194453f058079d897d13c4e377f92dc6). The "g" prefix stands for "git" and is used to allow describing the version of a software depending on the SCM the software is managed with. This is useful in an environment where people may use different SCMs.追加コミット数は、 "git log v1.0.4..parent"によって表示されるコミット数です。ハッシュサフィックスは、親のチップコミットのための "-g" + 7文字の省略形です2414721b194453f058079d897d13c4e377f92dc6。接頭辞「g」は「git」を表し、ソフトウェアの管理に使用されるSCMに応じてソフトウェアのバージョンを記述するために使用されます。これは、さまざまなSCMを使用する可能性がある環境で役立ちます。

Doing a git describe on a tag-name will just show the tag name:こう説明するのgitをタグ名には、単にタグ名を表示します。

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

With --all, the command can use branch heads as references, so the output shows the reference path as well:--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

With --abbrev set to 0, the command can be used to find the closest tagname without any suffix:--abbrevを0に設定すると、このコマンドを使用してサフィックスなしで最も近いtagnameを見つけることができます。

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

Note that the suffix you get if you type these commands today may be longer than what Linus saw above when he ran these commands, as your Git repository may have new commits whose object names begin with 975b that did not exist back then, and "-g975b" suffix alone may not be sufficient to disambiguate these commits.あなたのGitリポジトリが当時は存在しなかった975bで始まる新しいコミットを持っているかもしれないので、今日これらのコマンドをタイプしたときに得られる接尾辞はLinusがこれらのコマンドを実行したときに上に見たものより長いかもしれませんg975b "接尾辞だけでは、これらのコミットを明確にするのに十分ではないかもしれません。

SEARCH STRATEGY検索戦略

For each commit-ish supplied, git describe will first look for a tag which tags exactly that commit. Annotated tags will always be preferred over lightweight tags, and tags with newer dates will always be preferred over tags with older dates. If an exact match is found, its name will be output and searching will stop.提供されているそれぞれのcommit-ishに対して、git describeは最初にそのコミットを正確にタグ付けするタグを探します。注釈付きタグは常に軽量タグよりも優先され、新しい日付を持つタグは常に古い日付を持つタグよりも優先されます。完全に一致するものが見つかると、その名前が出力され、検索は中止されます。

If an exact match was not found, git describe will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor’s tag will be output along with an abbreviation of the input commit-ish’s SHA-1. If --first-parent was specified then the walk will only consider the first parent of each commit.完全に一致するものが見つからなかった場合、git describeはコミット履歴をたどってタグ付けされた先祖コミットを探します。先祖のタグは、入力commit-ishのSHA-1の省略形とともに出力されます。場合は--first-parent、指定された後、徒歩でのみ各コミットの最初の親を検討します。

If multiple tags were found during the walk then the tag which has the fewest commits different from the input commit-ish will be selected and output. Here fewest commits different is defined as the number of commits which would be shown by git log tag..input will be the smallest number of commits possible.歩行中に複数のタグが見つかった場合、入力コミットとは異なるコミットが最も少ないタグが選択されて出力されます。ここでは、コミットコミットメントの差異が最も少ないと定義されてgit log tag..inputいるコミットメントの数が、最小のコミット数となるように定義されています。

BUGSバグ

Tree objects as well as tag objects not pointing at commits, cannot be described. When describing blobs, the lightweight tags pointing at blobs are ignored, but the blob is still described as <committ-ish>:<path> despite the lightweight tag being favorable.ツリーオブジェクトとコミットを指していないタグオブジェクトは記述できません。ブロブを記述するとき、ブロブを指し示す軽量タグは無視されますが、軽量タグが好ましいにもかかわらず、ブロブは依然として<committ-ish>：<path>として記述されます。