Class: Git::Commands::Describe Private

Inherits:
Base
  • Object
show all
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:

Instance Method Summary collapse

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::CommandLineResult

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:

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 67