module Agate::Describe

Overview

Describes a commit in terms of the closest tag or reference. Equivalent to git describe.

# Describe HEAD
Describe.commit(repo, "HEAD")             # => "v1.0.0-3-gabcdef0"
Describe.commit(repo, "HEAD", tags: true) # => "v1.0.0-3-gabcdef0"
Describe.commit(repo, "HEAD", all: true)  # => "heads/main-3-gabcdef0"

# Describe with options
Describe.commit(repo, "HEAD", long: true) # => "v1.0.0-0-gabcdef0"
Describe.commit(repo, "HEAD", abbrev: 12) # => "v1.0.0-3-gabcdef0abcde"

# Describe working directory (includes dirty suffix)
Describe.workdir(repo, dirty_suffix: "-dirty") # => "v1.0.0-3-gabcdef0-dirty"

Defined in:

agate/describe.cr

Class Method Summary

.commit(repo : Repository, committish : String | Object, strategy : DescribeStrategy = DescribeStrategy::Default, tags : Bool = false, all : Bool = false, pattern : String | Nil = nil, max_candidates : UInt32 = 10, first_parent : Bool = false, fallback_to_oid : Bool = false, abbrev : UInt32 = 7, long : Bool = false) : String
Describes a committish (commit, tag, or revision spec string).
.commit?(repo : Repository, committish : String | Object, **opts) : String | Nil
Describes a committish, returning nil if no matching tag is found.
.workdir(repo : Repository, strategy : DescribeStrategy = DescribeStrategy::Default, tags : Bool = false, all : Bool = false, pattern : String | Nil = nil, max_candidates : UInt32 = 10, first_parent : Bool = false, fallback_to_oid : Bool = false, abbrev : UInt32 = 7, long : Bool = false, dirty_suffix : String | Nil = nil) : String
Describes the working directory relative to the closest tag.
.workdir?(repo : Repository, **opts) : String | Nil
Describes the working directory relative to the closest tag.

Class Method Detail

def self.commit(repo : Repository, committish : String | Object, strategy : DescribeStrategy = DescribeStrategy::Default, tags : Bool = false, all : Bool = false, pattern : String | Nil = nil, max_candidates : UInt32 = 10, first_parent : Bool = false, fallback_to_oid : Bool = false, abbrev : UInt32 = 7, long : Bool = false) : String #

Describes a committish (commit, tag, or revision spec string). Returns a string like "v1.0.0-3-gabcdef0".

Options:

strategy: which refs to consider (default: annotated tags only)
tags: shorthand for strategy: DescribeStrategy::Tags
all: shorthand for strategy: DescribeStrategy::All
pattern: glob pattern to match tag names (e.g., "v*")
max_candidates: maximum number of candidate tags (default: 10)
first_parent: only follow first parent (default: false)
fallback_to_oid: show OID if no tag found (default: false)
abbrev: abbreviated OID length (default: 7)
long: always use long format (default: false)

[View source]

def self.commit?(repo : Repository, committish : String | Object, **opts) : String | Nil #

Describes a committish, returning nil if no matching tag is found.

[View source]

def self.workdir(repo : Repository, strategy : DescribeStrategy = DescribeStrategy::Default, tags : Bool = false, all : Bool = false, pattern : String | Nil = nil, max_candidates : UInt32 = 10, first_parent : Bool = false, fallback_to_oid : Bool = false, abbrev : UInt32 = 7, long : Bool = false, dirty_suffix : String | Nil = nil) : String #

Describes the working directory relative to the closest tag. Like git describe --dirty.

Options are the same as .commit, plus:

dirty_suffix: suffix to append if the workdir is dirty (e.g., "-dirty")

[View source]

def self.workdir?(repo : Repository, **opts) : String | Nil #

Describes the working directory relative to the closest tag. Like git describe --dirty.

Options are the same as .commit, plus:

dirty_suffix: suffix to append if the workdir is dirty (e.g., "-dirty")

[View source]