Class: Git::Commands::ShowRef::ExcludeExisting Private

Inherits:
Base
  • Object
show all
Defined in:
lib/git/commands/show_ref/exclude_existing.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-show-ref/2.53.0

Stdin filter mode for git show-ref --exclude-existing

Reads ref names from the positional arguments, passes them to git's stdin, and outputs only those refs that do NOT already exist in the local repository. Useful for determining which remote refs would be new if fetched.

Pass exclude_existing: 'refs/heads/' to limit filtering to refs matching the given prefix pattern. By default (no pattern), all refs are evaluated.

For standard ref listing, use List. For strict per-ref verification, use Verify. For a boolean existence check (git >= 2.43), use Exists.

Examples:

Filter refs that do not exist locally

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

Limit filtering to a prefix pattern

cmd = Git::Commands::ShowRef::ExcludeExisting.new(execution_context)
result = cmd.call('refs/heads/main', exclude_existing: 'refs/heads/')
# refs/heads/main already exists locally, so git echoes nothing
result.stdout  # => ""

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(*ref, exclude_existing: true, **options) ⇒ Git::CommandLineResult

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 git show-ref --exclude-existing to filter ref names against the local repository

Each ref is passed to git's stdin. Git writes back only the refs that do not already exist locally.

Parameters:

  • ref (Array<String>) —

    ref names to test

  • exclude_existing (true, String) (defaults to: true) —

    filter mode selector

    Pass true (default) to test all refs, or a non-empty pattern string to restrict testing to refs whose names start with the pattern (e.g. 'refs/heads/'). Passing false or nil raises ArgumentError.

  • options (Hash) —

    command options

Options Hash (**options):

  • :timeout (Numeric) — default: nil —

    abort the command after this many seconds

Returns:

Raises:



82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/git/commands/show_ref/exclude_existing.rb', line 82

def call(*, exclude_existing: true, **)
  unless exclude_existing == true || (exclude_existing.is_a?(String) && !exclude_existing.empty?)
    raise ArgumentError,
          ":exclude_existing must be true or a non-empty String, got #{exclude_existing.inspect}"
  end

  bound = args_definition.bind(*, exclude_existing: exclude_existing, **)
  validate_version!
  stdin = Array(bound.ref).map { |r| "#{r}\n" }.join
  with_stdin(stdin) { |reader| run_filter(bound, reader) }
end