X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-describe.txt;h=ac23e28f2759222bb67fcf2445c229e918d96211;hb=7fd53fce1c574f6a4940eedf36383a4e9ed7ae6a;hp=2700f35bdb6ec7aae9520eca0d21bcf5089bc750;hpb=ab1b3af7925682e0375667b892e2f7e985effba5;p=git.git diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 2700f35bd..ac23e28f2 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -8,14 +8,14 @@ git-describe - Show the most recent tag that is reachable from a commit SYNOPSIS -------- -'git-describe' [--all] [--tags] [--abbrev=] ... +'git-describe' [--all] [--tags] [--contains] [--abbrev=] ... DESCRIPTION ----------- The command finds the most recent tag that is reachable from a commit, and if the commit itself is pointed at by the tag, shows -the tag. Otherwise, it suffixes the tag name with abbreviated -object name of the commit. +the tag. Otherwise, it suffixes the tag name with the number of +additional commits and the abbreviated object name of the commit. OPTIONS @@ -31,10 +31,25 @@ OPTIONS Instead of using only the annotated tags, use any tag found in `.git/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. + --abbrev=:: Instead of using the default 8 hexadecimal digits as the abbreviated object name, use digits. +--candidates=:: + Instead of considering only the 10 most recent tags as + candidates to describe the input committish consider + up to candidates. Increasing above 10 will take + slightly longer but may produce a more accurate result. + +--debug:: + Verbosely display information about the searching strategy + being employed to standard error. The tag name will still + be printed to standard out. EXAMPLES -------- @@ -42,12 +57,18 @@ EXAMPLES With something like git.git current tree, I get: [torvalds@g5 git]$ git-describe parent - v1.0.4-g2414721b + 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, it has added the -git hash of the thing to the end: "-g" + 8-char shorthand for -the commit `2414721b194453f058079d897d13c4e377f92dc6`. +but since it has a handful 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. + +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`). Doing a "git-describe" on a tag-name will just show the tag name: @@ -58,16 +79,43 @@ With --all, the command can use branch heads as references, so the output shows the reference path as well: [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2 - tags/v1.0.0-g975b + tags/v1.0.0-21-g975b [torvalds@g5 git]$ git describe --all HEAD^ - heads/lt/describe-g975b + heads/lt/describe-7-g975b + +With --abbrev set to 0, the command can be used to find the +closest tagname without any suffix: + + [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2 + tags/v1.0.0 + +SEARCH STRATEGY +--------------- + +For each committish 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. + +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 committish's SHA1. + +If multiple tags were found during the walk then the tag which +has the fewest commits different from the input committish 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. Author ------ Written by Linus Torvalds , but somewhat -butchered by Junio C Hamano +butchered by Junio C Hamano . Later significantly +updated by Shawn Pearce . Documentation -------------- @@ -76,4 +124,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list