git describe command
git describeThe command is used to generate a readable string that describes the current commit based on Git's tag system.
git describeThe command is typically used to generate version numbers, helping to identify specific commits, and can be used when building, releasing, or tracking specific versions.
Basic Syntax
git describe [<options>] [<commit>]
<commit>: Specifies the commit to describe. Defaults to the current commit.<options>: Options for customizing the output format or behavior.
Common options and usage:
| Options | Description | UsageExample |
|---|---|---|
--tags | Use all tags (including lightweight tags) to generate the description. By default,git describeOnly consider annotated tags. | git describe --tags |
--abbrev=<n> | Set the minimum length of the commit hash to display to<n>characters. | git describe --abbrev=8 |
--long | Force long-form description, including the commit hash and the number of commits from the tag. | git describe --long |
--exact-match | Return the tag name only when the current commit exactly matches the tag. | git describe --exact-match |
--dirty | If the working directory has changes (uncommitted changes), add to the description-dirtysuffix. | git describe --dirty |
--match=<pattern> | Use only tags matching the specified pattern for description. | git describe --match "v1.*" |
--candidates=<n> | Limit the number of tags considered for description, default is 10. | git describe --candidates=5 |
--always | Display the commit hash even if no tag is found. | git describe --always |
Common usage
1. Describe the current commit
Generate a description string based on the most recent tag:
git describe
Example output:
v1.2-15-g2414721
The output here indicates that the current commit is 15 commits away from the nearest tag v1.2, and the current commit hash is 2414721.
2. Describe using all tags
Include all tags (lightweight and annotated tags) to generate the description:
git describe --tags
3. Display long-format description
Display long-form description, including hash and the number of commits from the tag:
git describe --long
4. Return the tag name only when the commit exactly matches the tag
If the current commit exactly matches a tag, only the tag name is returned:
git describe --exact-match
5. Add -dirty suffix
If the working directory has uncommitted changes, add the -dirty suffix to the description:
git describe --dirty
6. Only use tags matching the pattern
Use tags matching the specified pattern for description:
git describe --match "v1.*"
7. Display the commit hash even if no tag is found
Display the current commit hash even when there is no tag:
git describe --always
other extensions