describe Git Command Guide
The git describe command generates a human-readable name for a given commit based on the most recent tag that precedes the commit. It provides a version-like string that includes the tag name, number of commits since the tag, and abbreviated commit hash.
git describe Syntax:
Section titled “git describe Syntax:”git describe [options] [<commit-ish>]Options:
Section titled “Options:”| Option | Description |
|---|---|
| —all | Use any ref found in refs/namespace |
| —tags | Use any tag found |
| —contains | Find the tag that comes after the commit |
| —abbrev= | Use |
| —candidates= | Consider up to |
| —exact-match | Only output exact tag matches |
| —debug | Verbose debugging output |
| —long | Always use long format (tag-NN-gSHA-abbrev) |
| —match | Only consider tags matching given glob pattern |
| —exclude | Do not consider tags matching given glob pattern |
| —always | Show unique abbreviated commit object as fallback |
| —first-parent | Follow only the first parent commit upon seeing a merge commit |
| —broken | Allow looking at broken commits |
| —dirty[=] | Append if repository is dirty (default “dirty”) |
| —broken | Describe commits with broken files |
| —help | Display help |
Parameters:
Section titled “Parameters:”| Parameter | Description |
|---|---|
| Commit to describe (default HEAD) |
git describe Command Samples:
Section titled “git describe Command Samples:”Describe current commit
Section titled “Describe current commit”git describeShows tag-NN-gSHA description for current commit.
Describe specific commit
Section titled “Describe specific commit”git describe HEAD~3Describes commit 3 commits back from current HEAD.
Include all refs
Section titled “Include all refs”git describe --allConsider any ref in refs/namespace, not just tags.
Use tags only
Section titled “Use tags only”git describe --tagsUse any tag found in refs/tags/ namespace.
Long format always
Section titled “Long format always”git describe --longAlways use long format even for exact matches.
Custom abbreviation
Section titled “Custom abbreviation”git describe --abbrev=4Use 4 digits for SHA-1 abbreviation.
Match specific pattern
Section titled “Match specific pattern”git describe --match "v[0-9]*"Only consider tags matching v[0-9]* pattern.
Find containing tag
Section titled “Find containing tag”git describe --contains HEAD~3Find tag that contains the commit.
Show if repository is dirty
Section titled “Show if repository is dirty”git describe --dirty=-modifiedAppend “-modified” if working directory has modifications.
Exact match only
Section titled “Exact match only”git describe --exact-matchOnly output if commit is exactly a tag.
With first parent
Section titled “With first parent”git describe --first-parentFollow only first parent in merge commits.
How do I describe the current commit?
Section titled “How do I describe the current commit?”To describe the current commit, use:
git describeHow can I include all references in description?
Section titled “How can I include all references in description?”To include all references in description, run:
git describe --allHow do I use only tags for description?
Section titled “How do I use only tags for description?”To use only tags for description, execute:
git describe --tagsHow can I find which tag contains a commit?
Section titled “How can I find which tag contains a commit?”To find which tag contains a commit, use:
git describe --contains <commit>How do I see if the repository is dirty?
Section titled “How do I see if the repository is dirty?”To see if the repository is dirty, run:
git describe --dirtyApplications of the git describe command
Section titled “Applications of the git describe command”- Generating version numbers for software releases
- Creating human-readable commit identifiers
- Finding the most recent tagged version from any commit
- Providing context for commits in automated systems
- Debugging by quickly identifying commit positions
- Supporting build systems that need version metadata