"Fossies" - the Fresh Open Source Software Archive

Member "git-describe.txt" (15 Dec 2018, 8013 Bytes) of package /linux/misc/git-htmldocs-2.20.1.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "git-describe.txt": 2.19.1_vs_2.19.2.

    1 git-describe(1)
    2 ===============
    3 
    4 NAME
    5 ----
    6 git-describe - Give an object a human readable name based on an available ref
    7 
    8 SYNOPSIS
    9 --------
   10 [verse]
   11 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
   12 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
   13 'git describe' <blob>
   14 
   15 DESCRIPTION
   16 -----------
   17 The command finds the most recent tag that is reachable from a
   18 commit.  If the tag points to the commit, then only the tag is
   19 shown.  Otherwise, it suffixes the tag name with the number of
   20 additional commits on top of the tagged object and the
   21 abbreviated object name of the most recent commit. The result
   22 is a "human-readable" object name which can also be used to
   23 identify the commit to other git commands.
   24 
   25 By default (without --all or --tags) `git describe` only shows
   26 annotated tags.  For more information about creating annotated tags
   27 see the -a and -s options to linkgit:git-tag[1].
   28 
   29 If the given object refers to a blob, it will be described
   30 as `<commit-ish>:<path>`, such that the blob can be found
   31 at `<path>` in the `<commit-ish>`, which itself describes the
   32 first commit in which this blob occurs in a reverse revision walk
   33 from HEAD.
   34 
   35 OPTIONS
   36 -------
   37 <commit-ish>...::
   38 	Commit-ish object names to describe.  Defaults to HEAD if omitted.
   39 
   40 --dirty[=<mark>]::
   41 --broken[=<mark>]::
   42 	Describe the state of the working tree.  When the working
   43 	tree matches HEAD, the output is the same as "git describe
   44 	HEAD".  If the working tree has local modification "-dirty"
   45 	is appended to it.  If a repository is corrupt and Git
   46 	cannot determine if there is local modification, Git will
   47 	error out, unless `--broken' is given, which appends
   48 	the suffix "-broken" instead.
   49 
   50 --all::
   51 	Instead of using only the annotated tags, use any ref
   52 	found in `refs/` namespace.  This option enables matching
   53 	any known branch, remote-tracking branch, or lightweight tag.
   54 
   55 --tags::
   56 	Instead of using only the annotated tags, use any tag
   57 	found in `refs/tags` namespace.  This option enables matching
   58 	a lightweight (non-annotated) tag.
   59 
   60 --contains::
   61 	Instead of finding the tag that predates the commit, find
   62 	the tag that comes after the commit, and thus contains it.
   63 	Automatically implies --tags.
   64 
   65 --abbrev=<n>::
   66 	Instead of using the default 7 hexadecimal digits as the
   67 	abbreviated object name, use <n> digits, or as many digits
   68 	as needed to form a unique object name.  An <n> of 0
   69 	will suppress long format, only showing the closest tag.
   70 
   71 --candidates=<n>::
   72 	Instead of considering only the 10 most recent tags as
   73 	candidates to describe the input commit-ish consider
   74 	up to <n> candidates.  Increasing <n> above 10 will take
   75 	slightly longer but may produce a more accurate result.
   76 	An <n> of 0 will cause only exact matches to be output.
   77 
   78 --exact-match::
   79 	Only output exact matches (a tag directly references the
   80 	supplied commit).  This is a synonym for --candidates=0.
   81 
   82 --debug::
   83 	Verbosely display information about the searching strategy
   84 	being employed to standard error.  The tag name will still
   85 	be printed to standard out.
   86 
   87 --long::
   88 	Always output the long format (the tag, the number of commits
   89 	and the abbreviated commit name) even when it matches a tag.
   90 	This is useful when you want to see parts of the commit object name
   91 	in "describe" output, even when the commit in question happens to be
   92 	a tagged version.  Instead of just emitting the tag name, it will
   93 	describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2
   94 	that points at object deadbee....).
   95 
   96 --match <pattern>::
   97 	Only consider tags matching the given `glob(7)` pattern,
   98 	excluding the "refs/tags/" prefix. If used with `--all`, it also
   99 	considers local branches and remote-tracking references matching the
  100 	pattern, excluding respectively "refs/heads/" and "refs/remotes/"
  101 	prefix; references of other types are never considered. If given
  102 	multiple times, a list of patterns will be accumulated, and tags
  103 	matching any of the patterns will be considered.  Use `--no-match` to
  104 	clear and reset the list of patterns.
  105 
  106 --exclude <pattern>::
  107 	Do not consider tags matching the given `glob(7)` pattern, excluding
  108 	the "refs/tags/" prefix. If used with `--all`, it also does not consider
  109 	local branches and remote-tracking references matching the pattern,
  110 	excluding respectively "refs/heads/" and "refs/remotes/" prefix;
  111 	references of other types are never considered. If given multiple times,
  112 	a list of patterns will be accumulated and tags matching any of the
  113 	patterns will be excluded. When combined with --match a tag will be
  114 	considered when it matches at least one --match pattern and does not
  115 	match any of the --exclude patterns. Use `--no-exclude` to clear and
  116 	reset the list of patterns.
  117 
  118 --always::
  119 	Show uniquely abbreviated commit object as fallback.
  120 
  121 --first-parent::
  122 	Follow only the first parent commit upon seeing a merge commit.
  123 	This is useful when you wish to not match tags on branches merged
  124 	in the history of the target commit.
  125 
  126 EXAMPLES
  127 --------
  128 
  129 With something like git.git current tree, I get:
  130 
  131 	[torvalds@g5 git]$ git describe parent
  132 	v1.0.4-14-g2414721
  133 
  134 i.e. the current head of my "parent" branch is based on v1.0.4,
  135 but since it has a few commits on top of that,
  136 describe has added the number of additional commits ("14") and
  137 an abbreviated object name for the commit itself ("2414721")
  138 at the end.
  139 
  140 The number of additional commits is the number
  141 of commits which would be displayed by "git log v1.0.4..parent".
  142 The hash suffix is "-g" + 7-char abbreviation for the tip commit
  143 of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`).
  144 The "g" prefix stands for "git" and is used to allow describing the version of
  145 a software depending on the SCM the software is managed with. This is useful
  146 in an environment where people may use different SCMs.
  147 
  148 Doing a 'git describe' on a tag-name will just show the tag name:
  149 
  150 	[torvalds@g5 git]$ git describe v1.0.4
  151 	v1.0.4
  152 
  153 With --all, the command can use branch heads as references, so
  154 the output shows the reference path as well:
  155 
  156 	[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
  157 	tags/v1.0.0-21-g975b
  158 
  159 	[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
  160 	heads/lt/describe-7-g975b
  161 
  162 With --abbrev set to 0, the command can be used to find the
  163 closest tagname without any suffix:
  164 
  165 	[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
  166 	tags/v1.0.0
  167 
  168 Note that the suffix you get if you type these commands today may be
  169 longer than what Linus saw above when he ran these commands, as your
  170 Git repository may have new commits whose object names begin with
  171 975b that did not exist back then, and "-g975b" suffix alone may not
  172 be sufficient to disambiguate these commits.
  173 
  174 
  175 SEARCH STRATEGY
  176 ---------------
  177 
  178 For each commit-ish supplied, 'git describe' will first look for
  179 a tag which tags exactly that commit.  Annotated tags will always
  180 be preferred over lightweight tags, and tags with newer dates will
  181 always be preferred over tags with older dates.  If an exact match
  182 is found, its name will be output and searching will stop.
  183 
  184 If an exact match was not found, 'git describe' will walk back
  185 through the commit history to locate an ancestor commit which
  186 has been tagged.  The ancestor's tag will be output along with an
  187 abbreviation of the input commit-ish's SHA-1. If `--first-parent` was
  188 specified then the walk will only consider the first parent of each
  189 commit.
  190 
  191 If multiple tags were found during the walk then the tag which
  192 has the fewest commits different from the input commit-ish will be
  193 selected and output.  Here fewest commits different is defined as
  194 the number of commits which would be shown by `git log tag..input`
  195 will be the smallest number of commits possible.
  196 
  197 BUGS
  198 ----
  199 
  200 Tree objects as well as tag objects not pointing at commits, cannot be described.
  201 When describing blobs, the lightweight tags pointing at blobs are ignored,
  202 but the blob is still described as <committ-ish>:<path> despite the lightweight
  203 tag being favorable.
  204 
  205 GIT
  206 ---
  207 Part of the linkgit:git[1] suite