Module: Git::Configuring

Included in:
Git, Repository
Defined in:
lib/git/configuring.rb

Overview

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 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.

Examples:

Include in a repository class

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

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!

Read Operations collapse

Write Operations collapse

Instance Method Details

#config_add(name, value, **options) ⇒ nil

Append a value to a multi-valued config key

Wraps git config --add.

Examples:

Append a URL to a multi-valued remote key

repo.config_add('remote.origin.url', 'git@github.com:user/repo.git')

Parameters:

  • name (String) —

    the full dotted config key

  • value (String) —

    the value to append

  • options (Hash) —

    scope options

Options Hash (**options):

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

    write to ~/.gitconfig

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

    write to the system config file

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

    write to .git/config

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

    write to the worktree config

  • :file (String, nil) — default: nil —

    path to a custom config file (alias: :f)

  • :blob (String, nil) — default: nil —

    write to a git blob object

  • :type (String, nil) — default: nil —

    coerce the value to the given type (e.g. "bool", "int")

Returns:

  • (nil)

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with a non-zero exit status



323
324
325
326
327
328
329
 
# File 'lib/git/configuring.rb', line 323

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

#config_get(name, value_regex = nil, **options) ⇒ Git::ConfigEntryInfo?

Retrieve a single config entry by key name

Wraps git config --get --show-scope --show-origin --null.

Examples:

Get a single config entry

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

Parameters:

  • name (String) —

    the full dotted config key (e.g. "user.name")

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

    optional regex to filter by value

  • options (Hash) —

    scope and filter options forwarded to the command

Options Hash (**options):

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

    read from ~/.gitconfig

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

    read from the system config file

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

    read from .git/config

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

    read from the worktree config

  • :file (String, nil) — default: nil —

    path to a custom config file (alias: :f)

  • :blob (String, nil) — default: nil —

    read from a git blob object

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

    follow include directives

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

    suppress include directives

  • :type (String, nil) — default: nil —

    enforce a type constraint on the value

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

    value to return when the key is missing

Returns:

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with an unexpected non-zero status



91
92
93
94
95
96
97
98
 
# 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

#config_get_all(name, value_regex = nil, **options) ⇒ Array<Git::ConfigEntryInfo>

Retrieve all values for a multi-valued config key

Wraps git config --get-all --show-scope --show-origin --null.

Examples:

Get all values for a multi-valued key

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

Parameters:

  • name (String) —

    the full dotted config key

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

    optional regex to filter by value

  • options (Hash) —

    scope and filter options (see #config_get)

Returns:

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with an unexpected non-zero status



124
125
126
127
128
129
130
131
 
# File 'lib/git/configuring.rb', line 124

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

#config_get_colorbool(name, stdout_is_tty = nil, **options) ⇒ String

Query whether color output is enabled for a given config slot

Wraps git config --get-colorbool.

Examples:

Check color status for color.ui

repo.config_get_colorbool('color.ui')  # => "true"

Parameters:

  • name (String) —

    the config key to check (e.g. "color.ui")

  • stdout_is_tty (Boolean, nil) (defaults to: nil) —

    whether stdout is a TTY

  • options (Hash) —

    scope and filter options

Options Hash (**options):

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

    read from ~/.gitconfig

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

    read from the system config file

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

    read from .git/config

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

    read from the worktree config

  • :file (String, nil) — default: nil —

    path to a custom config file (alias: :f)

  • :blob (String, nil) — default: nil —

    read from a git blob object

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

    follow include directives (--includes)

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

    suppress include directives (--no-includes)

Returns:

  • (String) —

    "true" or "false"

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with an unexpected non-zero status



174
175
176
177
178
179
 
# File 'lib/git/configuring.rb', line 174

def config_get_colorbool(name, stdout_is_tty = nil, **)
  Private.assert_valid_opts!(CONFIG_GET_COLORBOOL_ALLOWED_OPTS, **)
  assert_valid_scope!(**)
  cmd = Git::Commands::ConfigOptionSyntax::GetColorBool.new(execution_context)
  cmd.call(name, stdout_is_tty, **).stdout.chomp
end

#config_get_regexp(name_regex, value_regex = nil, **options) ⇒ Array<Git::ConfigEntryInfo>

Retrieve all config entries whose key matches a regular expression

Wraps git config --get-regexp --show-scope --show-origin --null.

Examples:

Get all remote-related config entries

entries = repo.config_get_regexp('remote\\.')
entries.map(&:key)  # => ["remote.origin.url", ...]

Parameters:

  • name_regex (String) —

    regex matched against config key names

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

    optional regex to filter by value

  • options (Hash) —

    scope and filter options (see #config_get)

Returns:

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with an unexpected non-zero status



205
206
207
208
209
210
211
212
 
# File 'lib/git/configuring.rb', line 205

def config_get_regexp(name_regex, value_regex = nil, **options)
  Private.assert_valid_opts!(CONFIG_GET_REGEXP_ALLOWED_OPTS, **options)
  assert_valid_scope!(**options)
  options = options.merge(show_scope: true, show_origin: true, null: true)
  cmd = Git::Commands::ConfigOptionSyntax::GetRegexp.new(execution_context)
  output = cmd.call(name_regex, value_regex, **options).stdout
  Git::Parsers::ConfigEntry.parse_list(output)
end

#config_get_urlmatch(name, url, **options) ⇒ Array<Git::ConfigEntryInfo>

Retrieve config entries whose URL pattern matches a given URL

Wraps git config --get-urlmatch --show-scope --null.

Note: --show-origin is not supported by git for --get-urlmatch, so the Git::ConfigEntryInfo entries returned by this method always have origin: nil.

Examples:

Get config entries for a specific URL

entries = repo.config_get_urlmatch('http', 'https://github.com/user/repo')
entries.map(&:key)

Parameters:

  • name (String) —

    the config section or key prefix to look up

  • url (String) —

    the URL to match against

  • options (Hash) —

    scope and filter options (see #config_get)

Returns:

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with an unexpected non-zero status



242
243
244
245
246
247
248
249
 
# File 'lib/git/configuring.rb', line 242

def config_get_urlmatch(name, url, **options)
  Private.assert_valid_opts!(CONFIG_GET_URLMATCH_ALLOWED_OPTS, **options)
  assert_valid_scope!(**options)
  options = options.merge(show_scope: true, null: true)
  cmd = Git::Commands::ConfigOptionSyntax::GetUrlmatch.new(execution_context)
  output = cmd.call(name, url, **options).stdout
  Git::Parsers::ConfigEntry.parse_urlmatch(output)
end

#config_list(**options) ⇒ Array<Git::ConfigEntryInfo>

List all visible config entries

Wraps git config --list --show-scope --show-origin --null.

Examples:

List all config entries

entries = repo.config_list
entries.first.scope  # => "local"

Parameters:

  • options (Hash) —

    scope and filter options (see #config_get)

Returns:

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with an unexpected non-zero status



271
272
273
274
275
276
277
278
 
# File 'lib/git/configuring.rb', line 271

def config_list(**options)
  Private.assert_valid_opts!(CONFIG_LIST_ALLOWED_OPTS, **options)
  assert_valid_scope!(**options)
  options = options.merge(show_scope: true, show_origin: true, null: true)
  cmd = Git::Commands::ConfigOptionSyntax::List.new(execution_context)
  output = cmd.call(**options).stdout
  Git::Parsers::ConfigEntry.parse_list(output)
end

#config_remove_section(name, **options) ⇒ nil

Remove an entire config section

Wraps git config --remove-section.

Examples:

Remove the origin remote section

repo.config_remove_section('remote.origin')

Parameters:

  • name (String) —

    the section name to remove (e.g. "remote.origin")

  • options (Hash) —

    scope options

Options Hash (**options):

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

    remove from ~/.gitconfig

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

    remove from the system config file

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

    remove from .git/config

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

    remove from the worktree config

  • :file (String, nil) — default: nil —

    path to a custom config file (alias: :f)

  • :blob (String, nil) — default: nil —

    remove from a git blob object

Returns:

  • (nil)

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with a non-zero exit status



366
367
368
369
370
371
372
 
# File 'lib/git/configuring.rb', line 366

def config_remove_section(name, **)
  Private.assert_valid_opts!(CONFIG_REMOVE_SECTION_ALLOWED_OPTS, **)
  assert_valid_scope!(**)
  cmd = Git::Commands::ConfigOptionSyntax::RemoveSection.new(execution_context)
  cmd.call(name, **)
  nil
end

#config_rename_section(old_name, new_name, **options) ⇒ nil

Rename a config section

Wraps git config --rename-section.

Examples:

Rename a remote section

repo.config_rename_section('remote.old', 'remote.new')

Parameters:

  • old_name (String) —

    the current section name

  • new_name (String) —

    the new section name

  • options (Hash) —

    scope options

Options Hash (**options):

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

    rename in ~/.gitconfig

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

    rename in the system config file

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

    rename in .git/config

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

    rename in the worktree config

  • :file (String, nil) — default: nil —

    path to a custom config file (alias: :f)

  • :blob (String, nil) — default: nil —

    rename in a git blob object

Returns:

  • (nil)

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with a non-zero exit status



411
412
413
414
415
416
417
 
# File 'lib/git/configuring.rb', line 411

def config_rename_section(old_name, new_name, **)
  Private.assert_valid_opts!(CONFIG_RENAME_SECTION_ALLOWED_OPTS, **)
  assert_valid_scope!(**)
  cmd = Git::Commands::ConfigOptionSyntax::RenameSection.new(execution_context)
  cmd.call(old_name, new_name, **)
  nil
end

#config_replace_all(name, value, value_regex = nil, **options) ⇒ nil

Replace all values matching a key (and optional value regex)

Wraps git config --replace-all.

Examples:

Replace all values for a key

repo.config_replace_all('remote.origin.url', 'https://github.com/user/repo')

Parameters:

  • name (String) —

    the full dotted config key

  • value (String) —

    the new value

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

    optional regex; only matching values are replaced

  • options (Hash) —

    scope options

Options Hash (**options):

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

    write to ~/.gitconfig

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

    write to the system config file

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

    write to .git/config

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

    write to the worktree config

  • :file (String, nil) — default: nil —

    path to a custom config file (alias: :f)

  • :blob (String, nil) — default: nil —

    write to a git blob object

  • :type (String, nil) — default: nil —

    coerce the value to the given type (e.g. "bool", "int")

Returns:

  • (nil)

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with a non-zero exit status



460
461
462
463
464
465
466
 
# File 'lib/git/configuring.rb', line 460

def config_replace_all(name, value, value_regex = nil, **)
  Private.assert_valid_opts!(CONFIG_REPLACE_ALL_ALLOWED_OPTS, **)
  assert_valid_scope!(**)
  cmd = Git::Commands::ConfigOptionSyntax::ReplaceAll.new(execution_context)
  cmd.call(name, value, value_regex, **)
  nil
end

#config_set(name, value, **options) ⇒ nil

Set a config entry to a new value

Wraps the implicit set mode of git config.

Examples:

Set the user name in local config

repo.config_set('user.name', 'Alice')

Parameters:

  • name (String) —

    the full dotted config key

  • value (String) —

    the value to set

  • options (Hash) —

    scope options

Options Hash (**options):

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

    write to ~/.gitconfig

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

    write to the system config file

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

    write to .git/config

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

    write to the worktree config

  • :file (String, nil) — default: nil —

    path to a custom config file (alias: :f)

  • :blob (String, nil) — default: nil —

    write to a git blob object

  • :type (String, nil) — default: nil —

    coerce the value to the given type (e.g. "bool", "int")

Returns:

  • (nil)

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with a non-zero exit status



507
508
509
510
511
512
513
 
# File 'lib/git/configuring.rb', line 507

def config_set(name, value, **)
  Private.assert_valid_opts!(CONFIG_SET_ALLOWED_OPTS, **)
  assert_valid_scope!(**)
  cmd = Git::Commands::ConfigOptionSyntax::Set.new(execution_context)
  cmd.call(name, value, **)
  nil
end

#config_unset(name, value_regex = nil, **options) ⇒ nil

Remove a config entry

Wraps git config --unset.

Examples:

Remove a config entry

repo.config_unset('user.name')

Parameters:

  • name (String) —

    the full dotted config key

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

    optional regex; only the matching value is removed

  • options (Hash) —

    scope options

Options Hash (**options):

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

    remove from ~/.gitconfig

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

    remove from the system config file

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

    remove from .git/config

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

    remove from the worktree config

  • :file (String, nil) — default: nil —

    path to a custom config file (alias: :f)

  • :blob (String, nil) — default: nil —

    remove from a git blob object

Returns:

  • (nil)

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with a non-zero exit status



552
553
554
555
556
557
558
 
# File 'lib/git/configuring.rb', line 552

def config_unset(name, value_regex = nil, **)
  Private.assert_valid_opts!(CONFIG_UNSET_ALLOWED_OPTS, **)
  assert_valid_scope!(**)
  cmd = Git::Commands::ConfigOptionSyntax::Unset.new(execution_context)
  cmd.call(name, value_regex, **)
  nil
end

#config_unset_all(name, value_regex = nil, **options) ⇒ nil

Remove all config entries for a key

Wraps git config --unset-all.

Examples:

Remove all values for a multi-valued key

repo.config_unset_all('remote.origin.url')

Parameters:

  • name (String) —

    the full dotted config key

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

    optional regex; only matching values are removed

  • options (Hash) —

    scope options

Options Hash (**options):

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

    remove from ~/.gitconfig

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

    remove from the system config file

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

    remove from .git/config

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

    remove from the worktree config

  • :file (String, nil) — default: nil —

    path to a custom config file (alias: :f)

  • :blob (String, nil) — default: nil —

    remove from a git blob object

Returns:

  • (nil)

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with a non-zero exit status



597
598
599
600
601
602
603
 
# File 'lib/git/configuring.rb', line 597

def config_unset_all(name, value_regex = nil, **)
  Private.assert_valid_opts!(CONFIG_UNSET_ALL_ALLOWED_OPTS, **)
  assert_valid_scope!(**)
  cmd = Git::Commands::ConfigOptionSyntax::UnsetAll.new(execution_context)
  cmd.call(name, value_regex, **)
  nil
end