module Git::Configuring

Mixin that adds structured ‘git config` read and write operations

Include or extend this module to gain the full suite of ‘config_*` methods. The including/extending class must implement two private methods:

{#execution_context} — returns a ‘Git::ExecutionContext` used to run commands
{#assert_valid_scope!} — raises ‘ArgumentError` if a requested scope is not valid in this context (e.g., `:local` is not valid without a repository)

Read methods that return {Git::ConfigEntryInfo} objects merge ‘show_scope: true, show_origin: true, null: true` into the options so that every returned entry carries its full provenance. Two exceptions apply: {#config_get_urlmatch} merges only `show_scope: true, null: true` because git does not support `–show-origin` with `–get-urlmatch` (those entries always have `origin: nil`); {#config_get_colorbool} returns a plain `String` and does not use these output-format options at all.

@example Include in a repository class

class MyRepo
  include Git::Configuring
  private
  def execution_context = @ctx
  def assert_valid_scope!(**) = nil  # all scopes allowed
end

@example Extend the Git module for global/system config

extend Git::Configuring
def self.execution_context = Git::ExecutionContext::Global.new
private_class_method :execution_context
def self.assert_valid_scope!(**opts)
  # reject :local, :worktree, :blob when called without a repository
end
private_class_method :assert_valid_scope!

@api private

Constants

CONFIG_ADD_ALLOWED_OPTS: @api private
CONFIG_GET_ALLOWED_OPTS: @api private
CONFIG_GET_ALL_ALLOWED_OPTS: @api private
CONFIG_GET_COLORBOOL_ALLOWED_OPTS: @api private
CONFIG_GET_REGEXP_ALLOWED_OPTS: @api private
CONFIG_GET_URLMATCH_ALLOWED_OPTS: @api private
CONFIG_LIST_ALLOWED_OPTS: @api private
CONFIG_REMOVE_SECTION_ALLOWED_OPTS: @api private
CONFIG_RENAME_SECTION_ALLOWED_OPTS: @api private
CONFIG_REPLACE_ALL_ALLOWED_OPTS: @api private
CONFIG_SET_ALLOWED_OPTS: @api private
CONFIG_UNSET_ALLOWED_OPTS: @api private
CONFIG_UNSET_ALL_ALLOWED_OPTS: @api private

Public Instance Methods

config_add (name, value, **)

Source

# File lib/git/configuring.rb, line 395
def config_add(name, value, **)
  Private.assert_valid_opts!(CONFIG_ADD_ALLOWED_OPTS, **)
  assert_valid_scope!(**)
  cmd = Git::Commands::ConfigOptionSyntax::Add.new(execution_context)
  cmd.call(name, value, **)
  nil
end

@overload config_add(name, value, **options)

Append a value to a multi-valued config key

Wraps `git config --add`.

@example Append a URL to a multi-valued remote key
  repo.config_add('remote.origin.url', 'git@github.com:user/repo.git')

@param name [String] the full dotted config key

@param value [String] the value to append

@param options [Hash] scope options

@option options [Boolean, nil] :global (nil) write to `~/.gitconfig`

@option options [Boolean, nil] :system (nil) write to the system config file

@option options [Boolean, nil] :local (nil) write to `.git/config`

@option options [Boolean, nil] :worktree (nil) write to the worktree config

@option options [String, nil] :file (nil) path to a custom config file (alias: `:f`)

@option options [String, nil] :blob (nil) write to a git blob object

@option options [String, nil] :type (nil) coerce the value to the given type (e.g. `"bool"`, `"int"`)

@return [nil]

@raise [ArgumentError] if unsupported options are provided

@raise [Git::FailedError] if git exits with a non-zero exit status

config_get (name, value_regex = nil, **options)

Source

# File lib/git/configuring.rb, line 91
def config_get(name, value_regex = nil, **options)
  Private.assert_valid_opts!(CONFIG_GET_ALLOWED_OPTS, **options)
  assert_valid_scope!(**options)
  options = options.merge(show_scope: true, show_origin: true, null: true)
  cmd = Git::Commands::ConfigOptionSyntax::Get.new(execution_context)
  output = cmd.call(name, value_regex, **options).stdout
  Git::Parsers::ConfigEntry.parse_get(name, output)
end

Retrieve a single config entry by key name

Wraps ‘git config –get –show-scope –show-origin –null`.

@example Get a single config entry

entry = repo.config_get('user.name')
entry&.value  # => "Alice"

@param name [String] the full dotted config key (e.g. ‘“user.name”`)

@param value_regex [String, nil] optional regex to filter by value

@param options [Hash] scope and filter options forwarded to the command

@option options [Boolean, nil] :global (nil) read from ‘~/.gitconfig`

@option options [Boolean, nil] :system (nil) read from the system config file

@option options [Boolean, nil] :local (nil) read from ‘.git/config`

@option options [Boolean, nil] :worktree (nil) read from the worktree config

@option options [String, nil] :file (nil) path to a custom config file (alias: ‘:f`)

@option options [String, nil] :blob (nil) read from a git blob object

@option options [Boolean, nil] :includes (nil) follow include directives

@option options [Boolean, nil] :no_includes (nil) suppress include directives

@option options [String, nil] :type (nil) enforce a type constraint on the value

@option options [String, nil] :default (nil) value to return when the key is missing

@return [Git::ConfigEntryInfo, nil] the matching entry, or ‘nil` when not found

@raise [ArgumentError] if unsupported options are provided

@raise [Git::FailedError] if git exits with an unexpected non-zero status

config_get_all (name, value_regex = nil, **options)

Source

# File lib/git/configuring.rb, line 142
def config_get_all(name, value_regex = nil, **options)
  Private.assert_valid_opts!(CONFIG_GET_ALL_ALLOWED_OPTS, **options)
  assert_valid_scope!(**options)
  options = options.merge(show_scope: true, show_origin: true, null: true)
  cmd = Git::Commands::ConfigOptionSyntax::GetAll.new(execution_context)
  output = cmd.call(name, value_regex, **options).stdout
  Git::Parsers::ConfigEntry.parse_get_all(name, output)
end

Retrieve all values for a multi-valued config key

Wraps ‘git config –get-all –show-scope –show-origin –null`.

@example Get all values for a multi-valued key

entries = repo.config_get_all('remote.origin.url')
entries.map(&:value)  # => ["https://...", "git@..."]

@param name [String] the full dotted config key

@param value_regex [String, nil] optional regex to filter by value

@param options [Hash] scope and filter options