grgit-describe

Name

grgit-describe - Describe a commit using the most recent tag reachable from it

Synopsis

grgit.describe()
grgit.describe(commit: <commit>, longDescr: <boolean>, tags: <boolean>, match: [<string>], always: <boolean>, abbrev <Integer>)
grgit.describe {
  commit = <commit>
  longDescr = <boolean>
  tags = <boolean>
  match = [<string>]
  always = <boolean>
  abbrev = <Integer>
}

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.

Describe only shows annotated tags. For more information about creating annotated tags see the annotate option to grgit-tag.

Options

commit

(Object, default null) Commit-ish object names to describe. Defaults to HEAD if omitted. For a more complete list of ways to spell commit names, see grgit-resolve (specifically the toCommit method).

always

(boolean, default false) When true, always describe a commit in some way and fall back to a uniquely abbreviated commit if no tags match.

longDescr

(boolean, default false) 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…​.).

tags

(boolean, default false) Instead of using only the annotated tags, use any tag found in refs/tags namespace. This option enables matching a lightweight (non-annotated) tag.

match

(List<String>, default []) Only consider tags matching the given glob(7) pattern, excluding the "refs/tags/" prefix. This can be used to avoid leaking private tags from the repository. If multiple patterns are given they will be accumulated, and tags matching any of the patterns will be considered.

abbrev

(Integer, default null) 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.

Examples

Describe the current HEAD.

grgit.describe() == '1.0.0'

Find the most recent tag that is reachable from a different commit.

grgit.describe(commit: 'other-branch') == '2.0.0-rc.1-7-g91fda36'

Always output the long format (the tag, the number of commits and the abbreviated commit name) even when it matches a tag.

grgit.describe(longDescr: true) == '2.0.0-rc.1-7-g91fda36'

Abbreviate object name to at least 2 digits, or as many digits as needed to form a unique object name.

grgit.describe(abbrev: 2) == '2.0.0-rc.1-7-g91fd'

See Also