class Git::Commands::ShowRef::List

Standard ref listing command via ‘git show-ref`

Lists refs stored in the local repository together with their associated commit IDs. When no filters are given, all refs are listed. Filters can narrow output to heads, tags, or refs matching a given pattern.

An exit status of 1 is not an error — it indicates that no matching refs were found. Exit status 0 means at least one match was found.

For strict per-ref verification, use {Git::Commands::ShowRef::Verify}. For stdin-based filtering, use {Git::Commands::ShowRef::ExcludeExisting}. For a simple boolean existence check (git >= 2.43), use {Git::Commands::ShowRef::Exists}.

@example List all refs

cmd = Git::Commands::ShowRef::List.new(execution_context)
result = cmd.call
result.stdout  # => "abc1234 refs/heads/main\n..."

@example List only tags

cmd = Git::Commands::ShowRef::List.new(execution_context)
result = cmd.call(tags: true)

@example List with abbreviated SHA hashes

cmd = Git::Commands::ShowRef::List.new(execution_context)
result = cmd.call(hash: 7)

@example Match a pattern

cmd = Git::Commands::ShowRef::List.new(execution_context)
result = cmd.call('v1.0', 'v2.0', tags: true)

@note ‘arguments` block audited against git-scm.com/docs/git-show-ref/2.53.0

@see Git::Commands::ShowRef

@see git-scm.com/docs/git-show-ref

@api private

Public Instance Methods

call (*, **)

Source

# File lib/git/commands/show_ref/list.rb, line 143
def call(*, **)
  super
end

@overload call(*pattern, **options)

Execute `git show-ref` to list matching refs

@param pattern [Array<String>] zero or more patterns to filter refs

  When empty, all refs are listed.

@param options [Hash] command options

@option options [Boolean, nil] :head (nil) show the HEAD ref even when filtered

@option options [Boolean, nil] :dereference (nil) dereference annotated tags,
  emitting an extra line per tag whose SHA points to the tagged object

  Alias: `:d`

@option options [Boolean, Integer, nil] :hash (nil) show only the SHA part of each ref

  Pass `true` for full-length SHAs or an integer for the abbreviation length
  (e.g. `hash: 7`).

  Alias: `:s`

@option options [Boolean, Integer, nil] :abbrev (nil) abbreviate object names

  Pass `true` for the default length or an integer for a specific length.

@option options [Boolean, nil] :branches (nil) limit output to local branches (refs/heads/)

  Prefer `:branches` over `:heads` on git >= 2.46; `:heads` emits the deprecated
  `--heads` flag.

@option options [Boolean, nil] :heads (nil) limit output to refs under refs/heads/

  Deprecated at the git level in git 2.46. Use `:branches` instead.

@option options [Boolean, nil] :tags (nil) limit output to refs under refs/tags/

@option options [Numeric] :timeout (nil) abort the command after this many seconds

@return [Git::CommandLine::Result] the result of calling `git show-ref`

@raise [ArgumentError] if unsupported options are provided

@raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)

@api public

Calls superclass method Git::Commands::Base::call