Home Explore Blog CI



git

1st chunk of `Documentation/git-describe.adoc`
16ae4e9c8b1e74991cd859ae591059e0603b40f7ef80cc2a0000000100000fa5
git-describe(1)
===============

NAME
----
git-describe - Give an object a human readable name based on an available ref

SYNOPSIS
--------
[verse]
'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.

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 linkgit:git-tag[1].

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.

OPTIONS
-------
<commit-ish>...::
	Commit-ish object names to describe.  Defaults to HEAD if omitted.

--dirty[=<mark>]::
--broken[=<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.

--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.

--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.

--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=<n>::
	Instead of using the default number of hexadecimal digits (which
	will vary according to the number of objects in the repository with
	a default of 7) of 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.

--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.

--exact-match::
	Only output exact matches (a tag directly references the
	supplied commit).  This is a synonym for --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....).

--match <pattern>::
	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

Title: Git Describe Command
Summary
The git-describe command generates a human-readable name for a Git object based on the most recent tag reachable from a commit, and can also describe the state of the working tree and provide additional information about the commit.