Class: Git::Commands::Describe Private

Inherits:

Base

• Object
• Base
• Git::Commands::Describe

Defined in:

lib/git/commands/describe.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Note:

arguments block audited against https://git-scm.com/docs/git-describe/2.53.0

Implements the git describe command

Gives a human-readable name to a commit based on the most recent reachable tag. When the tag points directly at the commit, only the tag name is shown. Otherwise, the tag name is suffixed with the number of additional commits and the abbreviated commit SHA.

Examples:

Typical usage

describe = Git::Commands::Describe.new(execution_context)
describe.call
describe.call('abc123')
describe.call(tags: true)
describe.call(dirty: true)
describe.call(dirty: '-dirty')

See Also:

• git-describe
• Git::Commands

Instance Method Summary

• #call(*commit_ish, **options) ⇒ Git::CommandLine::Result private

  Execute the git describe command.

Methods inherited from Base

allow_exit_status, arguments, #initialize, requires_git_version, skip_version_validation

Constructor Details

This class inherits a constructor from Git::Commands::Base

Instance Method Details

#call(*commit_ish, **options) ⇒ Git::CommandLine::Result

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Execute the git describe command

Parameters:

• commit_ish (Array<String>) —

  zero or more commit-ish objects to describe

  When none are given, describes HEAD.

• options (Hash) —

  command options

Options Hash (**options):

• :all (Boolean, nil) — default: nil —

  use any ref found in the refs/ namespace, not just tags

• :tags (Boolean, nil) — default: nil —

  use any tag found in the refs/tags namespace, instead of only annotated tags

• :contains (Boolean, nil) — default: nil —

  find the tag that comes after the commit and thus contains it, rather than the most recent tag reachable from it

• :abbrev (Boolean, String, nil) — default: nil —

  use this many digits for the abbreviated commit object name

  When true, emits bare --abbrev (which uses git's default length). Pass a string to emit --abbrev=<n>.

• :dirty (Boolean, String, nil) — default: nil —

  describe the working tree

  When true, appends -dirty; when a String, appends that string as the dirty mark. Maps to --dirty[=<mark>].

• :broken (Boolean, String, nil) — default: nil —

  describe the working tree, treating broken links as dirty

  When true, appends -broken; when a String, appends that string as the broken mark. Maps to --broken[=<mark>].

• :candidates (Integer, String) — default: nil —

  consider up to this many candidates

  Increasing above the default of 10 will take a slightly longer time but may produce a more accurate result. Maps to --candidates=<n>.

• :exact_match (Boolean, nil) — default: nil —

  only output exact matches (a tag directly references the supplied commit object)

• :debug (Boolean, nil) — default: nil —

  verbosely display information about the searching strategy being employed

• :long (Boolean, nil) — default: nil —

  always output the long format (the tag, the number of commits, and the abbreviated object name) even when it matches a tag exactly

• :match (String, Array<String>) — default: nil —

  only consider tags matching the given glob(7) pattern

  Pass an array to match against multiple patterns. Maps to --match <pattern>.

• :exclude (String, Array<String>) — default: nil —

  do not consider tags matching the given glob(7) pattern

  Pass an array to exclude multiple patterns. Maps to --exclude <pattern>.

• :always (Boolean, nil) — default: nil —

  show uniquely abbreviated commit object as fallback when the commit cannot be described

• :first_parent (Boolean, nil) — default: nil —

  follow only the first parent of a merge commit

Returns:

• (Git::CommandLine::Result) —

  the result of calling git describe

Raises:

• (ArgumentError) —

  if unsupported options are provided

• (Git::FailedError) —

  if git exits with a non-zero exit status

# File 'lib/git/commands/describe.rb', line 151

def call(*, **)
  super
end