Class: Git::Commands::Base Private

Inherits:

Object

• Object
• Git::Commands::Base

Defined in:

lib/git/commands/base.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.

Base class for git command implementations.

Provides default #initialize and #call methods so that simple commands only need to declare their arguments:

class Add < Git::Commands::Base arguments do literal 'add' flag_option :all flag_option :force end_of_options operand :paths, repeatable: true end

# Execute the git add command
# ...YARD docs...
def call(...) = super

end

Commands whose git process may exit with a non-zero status that is not an error can declare the acceptable range of exit codes:

class Delete < Git::Commands::Base arguments do literal 'branch' literal '--delete' operand :branch_names, repeatable: true, required: true end

allow_exit_status 0..1

# Execute the git branch --delete command
# ...YARD docs...
def call(...) = super

end

Commands with execution options (e.g., timeout) work with the default call — execution options are extracted and forwarded automatically.

Direct Known Subclasses

Add, Am::Abort, Am::Apply, Am::Continue, Am::Quit, Am::Retry, Am::ShowCurrentPatch, Am::Skip, Apply, Archive, Archive::ListFormats, Git::Commands::Branch::Copy, Git::Commands::Branch::Create, Git::Commands::Branch::Delete, Git::Commands::Branch::List, Git::Commands::Branch::Move, Git::Commands::Branch::SetUpstream, Git::Commands::Branch::ShowCurrent, Git::Commands::Branch::UnsetUpstream, CatFile::Batch, CatFile::Filtered, CatFile::Raw, Checkout::Branch, Checkout::Files, CheckoutIndex, Clean, Clone, Commit, CommitTree, ConfigOptionSyntax::Add, ConfigOptionSyntax::Get, ConfigOptionSyntax::GetAll, ConfigOptionSyntax::GetColor, ConfigOptionSyntax::GetColorBool, ConfigOptionSyntax::GetRegexp, ConfigOptionSyntax::GetUrlmatch, ConfigOptionSyntax::List, ConfigOptionSyntax::RemoveSection, ConfigOptionSyntax::RenameSection, ConfigOptionSyntax::ReplaceAll, ConfigOptionSyntax::Set, ConfigOptionSyntax::Unset, ConfigOptionSyntax::UnsetAll, Describe, Diff, DiffFiles, DiffIndex, Fetch, Fsck, Gc, Grep, Init, Log, LsFiles, LsRemote, LsTree, Maintenance::Register, Maintenance::Run, Maintenance::Start, Maintenance::Stop, Maintenance::Unregister, Merge::Abort, Merge::Continue, Merge::Quit, Merge::Start, MergeBase, Mv, NameRev, Pull, Push, ReadTree, Remote::Add, Remote::GetUrl, Remote::List, Remote::Prune, Remote::Remove, Remote::Rename, Remote::SetBranches, Remote::SetHead, Remote::SetUrl, Remote::SetUrlAdd, Remote::SetUrlDelete, Remote::Show, Remote::Update, Repack, Reset, RevParse, Revert::Abort, Revert::Continue, Revert::Quit, Revert::Skip, Revert::Start, Rm, Show, ShowRef::ExcludeExisting, ShowRef::Exists, ShowRef::List, ShowRef::Verify, Stash::Apply, Stash::Branch, Stash::Clear, Stash::Create, Stash::Drop, Stash::List, Stash::Pop, Stash::Push, Stash::Show, Stash::Store, Status, SymbolicRef::Delete, SymbolicRef::Read, SymbolicRef::Update, Tag::Create, Tag::Delete, Tag::List, Tag::Verify, UpdateRef::Batch, UpdateRef::Delete, UpdateRef::Update, Version, Worktree::List, Worktree::ManagementBase, WriteTree

Class Attribute Summary

• .allowed_exit_status_range ⇒ Range^? readonly private

  Range of exit status values accepted by this command.

• .args_definition ⇒ Git::Commands::Arguments^? readonly private

  The frozen argument definition for this command.

• .git_version_constraint ⇒ Git::VersionConstraint^? readonly private

  Version constraint for this command.

• .skip_version_validation? ⇒ Boolean readonly private

Class Method Summary

• .allow_exit_status(range) private

  Declare the acceptable range of exit status values for this command.

• .arguments { ... } private

  Define the command's arguments using the Arguments DSL.

• .requires_git_version(min = nil, before: nil) private

  Declare the git version requirements for this command.

• .skip_version_validation private

  Declare that this command should skip version validation.

Instance Method Summary

• #call(*args, **kwargs) ⇒ Git::CommandLine::Result private

  Execute the git command.

• #initialize(execution_context) ⇒ Base constructor private

  A new instance of Base.

Constructor Details

#initialize(execution_context) ⇒ Base

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.

Returns a new instance of Base.

Parameters:

• execution_context (Git::ExecutionContext) —

  context that provides ExecutionContext#command_capturing and ExecutionContext#command_streaming

# File 'lib/git/commands/base.rb', line 208

def initialize(execution_context)
  @execution_context = execution_context
end

Class Attribute Details

.allowed_exit_status_range ⇒ Range^? (readonly)

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.

Returns range of exit status values accepted by this command.

Returns:

• (Range, nil) —

  range of exit status values accepted by this command

# File 'lib/git/commands/base.rb', line 69

def allowed_exit_status_range
  @allowed_exit_status_range
end

.args_definition ⇒ Git::Commands::Arguments^? (readonly)

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.

Returns the frozen argument definition for this command.

Returns:

• (Git::Commands::Arguments, nil) —

  the frozen argument definition for this command

# File 'lib/git/commands/base.rb', line 52

def args_definition
  @args_definition
end

.git_version_constraint ⇒ Git::VersionConstraint^? (readonly)

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.

Version constraint for this command

Returns +nil+ if the command is available in all supported git versions.

Returns:

• (Git::VersionConstraint, nil) —

  version constraint for this command

  Returns +nil+ if the command is available in all supported git versions.

# File 'lib/git/commands/base.rb', line 99

def git_version_constraint
  @git_version_constraint
end

.skip_version_validation? ⇒ Boolean (readonly)

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.

Returns:

• (Boolean)

# File 'lib/git/commands/base.rb', line 104

def skip_version_validation? = !!@skip_version_validation

Class Method Details

.allow_exit_status(range)

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.

This method returns an undefined value.

Declare the acceptable range of exit status values for this command.

Examples:

git-diff exits 1 when a diff is found (not an error)

allow_exit_status 0..1

git-fsck uses exit codes 0-7 as bit flags

allow_exit_status 0..7

Parameters:

• range (Range) —

  range of accepted exit status values

Raises:

• (ArgumentError) —

  if range is invalid

# File 'lib/git/commands/base.rb', line 85

def allow_exit_status(range)
  raise ArgumentError, 'allow_exit_status expects a Range' unless range.is_a?(Range)
  unless range.begin.is_a?(Integer) && range.end.is_a?(Integer)
    raise ArgumentError, 'allow_exit_status bounds must be Integers'
  end

  raise ArgumentError, 'allow_exit_status range must not be empty' if range.begin > range.end

  @allowed_exit_status_range = range
end

.arguments { ... }

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.

This method returns an undefined value.

Define the command's arguments using the Arguments DSL.

Yields:

• the block passed to Arguments.define

Raises:

• (ArgumentError) —

  if called more than once on the same class

# File 'lib/git/commands/base.rb', line 62

def arguments(&)
  raise ArgumentError, "arguments already defined for #{name}" if @args_definition

  @args_definition = Arguments.define(&).freeze
end

.requires_git_version(min = nil, before: nil)

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.

This method returns an undefined value.

Declare the git version requirements for this command.

Use this when the command (or the specific sub-action this class wraps) was introduced in a git version later than +Git::MINIMUM_GIT_VERSION+, or when the command was removed in a later version. When not declared, the command is assumed to be available in all supported git versions.

Examples:

git-am --retry requires git 2.46.0 or later

requires_git_version '2.46.0'

Feature with version range

requires_git_version '2.29.0', before: '2.50.0'

Feature available before git 2.50.0

requires_git_version before: '2.50.0'

Parameters:

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

  minimum version

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

  upper bound version (exclusive)

Raises:

• (ArgumentError) —

  if version format is invalid or called twice

# File 'lib/git/commands/base.rb', line 144

def requires_git_version(min = nil, before: nil)
  raise ArgumentError, 'requires_git_version already declared for this class' if @git_version_constraint

  @git_version_constraint = normalize_version_constraint(min, before)
end

.skip_version_validation

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.

This method returns an undefined value.

Declare that this command should skip version validation.

This is intended for internal use only — specifically for the git version command, which cannot validate versions without causing infinite recursion.

# File 'lib/git/commands/base.rb', line 116

def skip_version_validation
  @skip_version_validation = true
end

Instance Method Details

#call(*args, **kwargs) ⇒ Git::CommandLine::Result

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 the git command.

Bind arguments and execute the command.

Execution options (declared via execution_option in the Arguments DSL) are extracted from the bound arguments via Arguments::Bound#execution_options and forwarded as keyword arguments to the execution context via #execute_command.

When the :out execution option is present, stdout is streamed using @execution_context.command_streaming. Otherwise, stdout is captured using @execution_context.command_capturing.

Examples:

# In a command subclass:
# result = command.call('HEAD', timeout: 10)

Parameters:

• args (Array) —

  positional arguments forwarded to Arguments#bind

• kwargs (Hash) —

  keyword arguments forwarded to Arguments#bind

Returns:

• (Git::CommandLine::Result) —

  the result of calling git

Raises:

• (ArgumentError) —

  if no arguments definition is declared on the command class

• (Git::FailedError) —

  if git returns an exit code outside the allowed range

• (Git::VersionError) —

  if the installed git version doesn't meet requirements

# File 'lib/git/commands/base.rb', line 241

def call(*, **)
  bound = args_definition.bind(*, **)
  validate_version!(bound.execution_options)
  result = execute_command(bound)
  validate_exit_status!(result)
  result
end