Module: Git::Configuring Private

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

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

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

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.

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



395
396
397
398
399
400
401
# 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

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

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.

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>

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.

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

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

Returns:

Raises:

  • (ArgumentError)

    if unsupported options are provided

  • (Git::FailedError)

    if git exits with an unexpected non-zero status



142
143
144
145
146
147
148
149
# 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

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

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.

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



192
193
194
195
196
197
# File 'lib/git/configuring.rb', line 192

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>

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.

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

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

Returns:

Raises:

  • (ArgumentError)

    if unsupported options are provided

  • (Git::FailedError)

    if git exits with an unexpected non-zero status



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

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>

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.

Note:

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

Retrieve config entries whose URL pattern matches a given URL

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

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

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

Returns:

Raises:

  • (ArgumentError)

    if unsupported options are provided

  • (Git::FailedError)

    if git exits with an unexpected non-zero status



296
297
298
299
300
301
302
303
# File 'lib/git/configuring.rb', line 296

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>

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.

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

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

Returns:

Raises:

  • (ArgumentError)

    if unsupported options are provided

  • (Git::FailedError)

    if git exits with an unexpected non-zero status



343
344
345
346
347
348
349
350
# File 'lib/git/configuring.rb', line 343

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

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.

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



438
439
440
441
442
443
444
# File 'lib/git/configuring.rb', line 438

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

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.

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



483
484
485
486
487
488
489
# File 'lib/git/configuring.rb', line 483

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

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.

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



532
533
534
535
536
537
538
# File 'lib/git/configuring.rb', line 532

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

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.

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



579
580
581
582
583
584
585
# File 'lib/git/configuring.rb', line 579

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

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.

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



624
625
626
627
628
629
630
# File 'lib/git/configuring.rb', line 624

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

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.

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



669
670
671
672
673
674
675
# File 'lib/git/configuring.rb', line 669

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