Module: Git::Repository::Inspecting

Included in:
Git::Repository
Defined in:
lib/git/repository/inspecting.rb

Overview

Facade methods for read-only repository inspection operations

These methods report on the contents and integrity of the repository.

Included by Git::Repository.

Instance Method Summary collapse

Instance Method Details

#describe(committish = nil, opts = {}) ⇒ String

Give a human-readable name to a commit based on the most recent reachable tag

Runs git describe to find the nearest tag reachable from committish and formats a version string. 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 (e.g. v1.0.0-3-gabcdef1).

Examples:

Describe HEAD

repo.describe #=> "v1.0.0"

Describe a specific commit

repo.describe('abc123') #=> "v1.0.0-3-gabcdef1"

Describe using any tag (not just annotated tags)

repo.describe(nil, tags: true) #=> "v1.0.0-lightweight"

Require an exact tag match

repo.describe(nil, exact_match: true)

Use the legacy hyphenated key (still accepted)

repo.describe(nil, :'exact-match' => true)

Parameters:

  • committish (String, nil) (defaults to: nil) —

    the commit-ish to describe; defaults to HEAD when nil

  • opts (Hash) (defaults to: {}) —

    options forwarded to git describe

Options Hash (opts):

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

    use any ref in refs/, not just tags

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

    use lightweight tags as well as annotated ones

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

    describe the tag that contains the commit, rather than the nearest reachable one

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

    number of hex digits for the abbreviated object name; true uses git's default length

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

    append a dirty-state mark to the description; true appends -dirty, a String appends that string

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

    like :dirty but treats broken repository links as dirty

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

    number of candidate tags to consider; increasing above 10 may yield a more accurate result

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

    only succeed when the commit is pointed to by a tag directly (no suffix)

    The legacy hyphenated key :"exact-match" is also accepted and is automatically translated to :exact_match.

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

    verbosely display the search strategy

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

    always output the long format even when the commit matches a tag exactly

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

    only consider tags matching the given glob(7) pattern; pass an array for multiple patterns

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

    do not consider tags matching the given glob(7) pattern; pass an array for multiple patterns

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

    show the abbreviated commit SHA as fallback when the commit cannot be described

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

    follow only the first parent of merge commits when searching for the nearest tag

Returns:

  • (String) —

    the human-readable description of the commit, with trailing newlines preserved

Raises:

  • (Git::FailedError) —

    when git exits with a non-zero exit status

  • (ArgumentError) —

    when committish looks like a command-line flag (starts with -), or when opts contains any key not in the documented option list



98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/git/repository/inspecting.rb', line 98

def describe(committish = nil, opts = {})
  raise ArgumentError, "Invalid commit-ish object: '#{committish}'" if committish&.start_with?('-')

  opts = opts.dup
  if opts.key?(:'exact-match')
    opts[:exact_match] ||= opts[:'exact-match']
    opts.delete(:'exact-match')
  end
  SharedPrivate.assert_valid_opts!(DESCRIBE_ALLOWED_OPTS, **opts)
  commit_ishes = Array(committish).compact
  Git::Commands::Describe.new(@execution_context).call(*commit_ishes, **opts).stdout
end

#fsck(*objects, **options) ⇒ Git::FsckResult

Verify the connectivity and validity of the objects in the database

Runs git fsck and returns the categorized objects it flags. Progress output is always suppressed (--no-progress) so that stdout contains only the machine-parsable findings.

Returns the objects flagged by fsck, categorized by status.

Examples:

Check repository integrity

result = repo.fsck
result.dangling.each { |obj| puts "#{obj.type}: #{obj.oid}" }

Check if the repository is clean

repo.fsck.empty? #=> true

List root commits

repo.fsck(root: true).root.each { |obj| puts obj.oid }

Check specific objects

repo.fsck('abc1234', 'def5678')

Parameters:

  • objects (Array<String>) —

    specific objects to treat as heads for the unreachability trace

    When none are given, git fsck defaults to the index file, all refs, and all reflogs.

  • options (Hash) —

    options for the fsck command

Options Hash (**options):

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

    report tags

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

    report root nodes

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

    print objects that exist but are not reachable from any reference node

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

    consider objects recorded in the index as head nodes for reachability

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

    do not consider commits referenced only by reflogs to be reachable

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

    also check alternate object pools and packed archives, not just the local store

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

    skip alternate object pools and packed archives

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

    enable stricter checking

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

    be chatty

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

    write dangling objects into .git/lost-found

    This modifies the repository by creating files.

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

    print dangling objects

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

    suppress dangling object reporting

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

    check only connectivity; faster but does not validate blob content

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

    show the name of each reachable object alongside its identifier

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

    suppress object name display

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

    check reference database consistency

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

    skip reference checking

Returns:

Raises:

  • (ArgumentError) —

    when unsupported options are provided

  • (Git::FailedError) —

    when git exits outside the allowed range (exit code > 7)



245
246
247
248
249
 
# File 'lib/git/repository/inspecting.rb', line 245

def fsck(*objects, **)
  SharedPrivate.assert_valid_opts!(FSCK_ALLOWED_OPTS, **)
  result = Git::Commands::Fsck.new(@execution_context).call(*objects, **, no_progress: true)
  Git::Parsers::Fsck.parse(result.stdout)
end

#show(objectish = nil, path = nil) ⇒ String

Show a single git object (a commit, tag, tree, or blob)

Examples:

Show the HEAD commit

repo.show

Show a specific commit

repo.show('HEAD~1')

Show the contents of a file at a revision

repo.show('HEAD', 'README.md')

Parameters:

  • objectish (String, nil) (defaults to: nil) —

    the object to show; a ref, SHA, or objectish:path expression

    Defaults to HEAD when nil.

  • path (String, nil) (defaults to: nil) —

    the file whose contents to show at objectish, when given

    Combined with objectish as objectish:path. When objectish is nil and path is given, HEAD is used as the objectish, so show(nil, 'README.md') resolves to HEAD:README.md.

Returns:

  • (String) —

    git's stdout from the show, with trailing newlines preserved

Raises:



139
140
141
142
 
# File 'lib/git/repository/inspecting.rb', line 139

def show(objectish = nil, path = nil)
  object = path ? "#{objectish || 'HEAD'}:#{path}" : objectish
  Git::Commands::Show.new(@execution_context).call(*[object].compact).stdout
end