Git Describe

Prerequisites

A version control system, also known as a VCS, is one of the most crucial tools every developer should have. Git is one of the most widely used version control systems among developers worldwide.

Git is open-source software, which means it may be adjusted to meet particular needs and is free to use. Additionally, it has a lot of great features that attempt to speed up the project process while also facilitating collaboration between teams and individual developers.

Git is simple to use and understand, but it's also a skill that's in high demand.

You must have:

• Git installed 
• Access to a Git repository hosted by another service or a GitHub account 

Introduction

The git describe command finds the most recent reachable tag from a commit. The tag is only shown when the tag refers to the commit.  If not, it appends the tag name with the number of commits that have come after the tagged object followed by the abbreviated object name of the most latest commit. This will result in a "human-readable" object name that can also be used in other git commands to identify a commit.

Installation

The git-describe command is accessible using npm: npm install git-describe

Tests are not covered in the npm package; to run them, clone the git repository (Node.js 4+ is necessary).

If you do not need the functionality of the server, you do not need to install semver as of version 4.0.0.

Keep in mind that for this module to work, the git executable needs to be on the system's executable path.

Usage

The module exposes the following two functions:

• gitDescribe(directory, options, cb) -> Promise
• gitDescribeSync(directory, options) -> Object

The main difference between the two is that gitDescribe offers an asynchronous API (which may be used with either the callback parameter or the returned promise), whereas gitDescribeSync is synchronous (waits for the git executable to return and throws an Error when the command fails).

Both functions accept an options object and a directory string (which defaults to the working directory). You can omit one or both arguments.

Example:

Output

Options

• --dirty[=<mark>] --broken[=<mark>]

The option describes the current state of the working tree. It is the same output as git describe HEAD when the working tree matches HEAD.   If the working tree has been locally modified, the suffix -dirty is added. If a repository is corrupt and Git is unable to tell whether there has been a local modification, Git will throw an error unless the option --broken is specified, which adds the suffix -broken in its place.

The flag --broken is created, which is similar to --dirty but checks for dirtiness using a real child process. Instead of adding -dirty, we'll add -broken if the child dies unexpectedly.

• --all Use any ref that may be found in the refs/ namespace rather than just the annotated tags. Using this option, you can match any remote-tracking branch, lightweight tag, or known branch.

• --tags Use any tag that can be found in the refs/tags namespace rather than just the annotated tags. This option makes it possible to match a lightweight (non-annotated) tag.

• --contains Instead of looking for the tag that precedes the commit, look for the tag that follows it and so contains it. Implies automatically —tags.

• --abbrev=<n> Use digits, or as many digits as necessary, to create a unique object name rather than the truncated object name's default hexadecimal digit count (which will change depending on the number of objects in the repository, with a default of 7).

• --candidates=<n> Consider up to <n> tags as candidates instead of limiting it to the 10 most recent ones.  Increasing the number over 10 will take a little longer, but will likely yield a more precise outcome.

• --exact-match Produce only exact matches (tags refer directly to commits). This is another way of saying —candidates=0.

• --debug Indicate in detail the search strategies used to estimate the standard error. Standard out will still print the tag name.

• --long Even when it matches a tag, always display the lengthy format (the tag, the amount of commits, and the abbreviated commit name). This is helpful even if the commit in question is a tagged version and you want to view specific portions of the commit object name in the describe output.

Search Strategy

The git describe command will first search for a tag that specifically tags each commit-ish that is given. The preference will always be given to annotated tags over lightweight tags, and the preference will also be given to tags with newer dates over tags with older dates. When an exact match is found, its name will be displayed and the search will stop.

In the rare case that git describe does not find an exact match, it will explore the commit history to identify a tagged ancestor commit. The result will provide the ancestor's tag and an abbreviation version of the input commit-ish’s SHA-1. The git describe command walk will only take into account each commit's first parent if the option —first-parent was used.

During the walk, if more than one tag was found, the one with the fewest commits that differ from the input commit-ish will be selected and output. The amount of commits that the git log tag..input would display in this case is specified as the fewest number of commits different from the input commit-ish.

Example: How To Find The Current Tag With Git Describe?

You can use the git describe command to find the current tag:

How to Find the Latest Tag of a Specific Commit?

Enter the commit's hash as follows to find the most recent tag for that particular commit:

How to Get the Last Tag Matching a Regex?

Use the git tag command as follows to locate the most recent tag matching a regex:

All of the tags that match that pattern will be returned by this command.

Fixing Errors

How to fix this?

You don't have any tags in your repository, according to this error.

Solving this error: Make sure your local repository has tags. To pull the tags, try using the git pull command. Make sure the remote has tags if the repository has been cloned. The repository you are in is a shallow clone if the remote has tags. To fetch the tags, type git fetch --prune --unshallow.

Bugs

It is not possible to define tree objects or tag objects that do not point at commits. The lightweight tags linking at blobs are ignored when describing blobs, however, the blob is still characterized as <committ-ish>:<path> despite the lightweight tag being favorable.