Class: Git::Repository

Inherits:
Object
  • Object
show all
Extended by:
Factories
Includes:
Configuring, Branching, Committing, ContextHelpers, Diffing, Inspecting, Logging, Maintenance, Merging, ObjectOperations, RemoteOperations, Staging, Stashing, StatusOperations, WorktreeOperations
Defined in:
lib/git/repository.rb,
lib/git/repository/diffing.rb,
lib/git/repository/logging.rb,
lib/git/repository/merging.rb,
lib/git/repository/staging.rb,
lib/git/repository/stashing.rb,
lib/git/repository/branching.rb,
lib/git/repository/factories.rb,
lib/git/repository/committing.rb,
lib/git/repository/inspecting.rb,
lib/git/repository/maintenance.rb,
lib/git/repository/path_resolver.rb,
lib/git/repository/shared_private.rb,
lib/git/repository/context_helpers.rb,
lib/git/repository/object_operations.rb,
lib/git/repository/remote_operations.rb,
lib/git/repository/status_operations.rb,
lib/git/repository/worktree_operations.rb

Overview

The main public interface for interacting with a Git repository

Git::Repository is the orchestration layer for all git operations. It acts as the glue between the user-facing API and the underlying components, but contains minimal domain logic itself. For each operation it:

  1. Pre-processes arguments — transforms user-provided values into forms suitable for the command layer (e.g. path expansion, option normalization, Ruby-idiomatic defaults, deprecation handling, input validation).
  2. Calls commands — invokes one or more Git::Commands::* classes via the injected Git::ExecutionContext::Repository.
  3. Builds rich return values — passes raw command output through Git::Parsers::* classes and result-class factory methods to assemble the meaningful Ruby objects the caller expects.

Some operations are genuinely one-line delegators when no pre/post-processing is needed (e.g. add, reset), but many are short orchestration sequences that coordinate argument preparation, one or more command calls, and result assembly.

Facade methods are organized into focused modules under lib/git/repository/ (e.g. Staging) and included into this class.

Defined Under Namespace

Modules: Branching, Committing, ContextHelpers, Diffing, Factories, Inspecting, Logging, Maintenance, Merging, ObjectOperations, PathResolver, RemoteOperations, Staging, Stashing, StatusOperations, WorktreeOperations

Instance Attribute Summary collapse

Attributes included from Branching

#name, #state

Instance Method Summary collapse

Methods included from Factories

bare, clone, init, open

Methods included from WorktreeOperations

#worktree, #worktree_add, #worktree_prune, #worktree_remove, #worktrees, #worktrees_all

Methods included from StatusOperations

#empty?, #ls_files, #no_commits?, #status, #untracked_files

Methods included from Stashing

#stash_apply, #stash_clear, #stash_list, #stash_save, #stashes_all

Methods included from Staging

#add, #apply, #apply_mail, #clean, #ignored_files, #mv, #read_tree, #reset, #reset_hard, #rm

Methods included from RemoteOperations

#add_remote, #config_remote, #fetch, #ls_remote, #pull, #push, #remote, #remote_add, #remote_remove, #remote_set_branches, #remote_set_url, #remotes, #remove_remote, #set_remote_url

Methods included from ObjectOperations

#add_tag, #archive, #cat_file_commit, #cat_file_contents, #cat_file_size, #cat_file_tag, #cat_file_type, #delete_tag, #full_tree, #gblob, #gcommit, #grep, #gtree, #ls_tree, #name_rev, #object, #rev_parse, #tag, #tag_add, #tag_delete, #tag_sha, #tags, #tree_depth

Methods included from Merging

#conflicts, #each_conflict, #merge, #merge_base, #revert, #unmerged

Methods included from Maintenance

#gc, #repack

Methods included from Logging

#full_log_commits, #log

Methods included from Inspecting

#describe, #fsck, #show

Methods included from Diffing

#diff, #diff_files, #diff_full, #diff_index, #diff_numstat, #diff_path_status, #diff_stats

Methods included from Committing

#commit, #commit_all, #commit_tree, #write_and_commit_tree, #write_tree

Methods included from ContextHelpers

#chdir, #set_index, #set_working, #with_index, #with_temp_index, #with_temp_working, #with_working

Methods included from Branching

#branch, #branch?, #branch_contains, #branch_delete, #branch_new, #branches, #branches_all, #change_head_branch, #checkout, #checkout_file, #checkout_index, #current_branch, #current_branch_state, #is_branch?, #is_local_branch?, #is_remote_branch?, #local_branch?, #remote_branch?, #update_ref

Methods included from Configuring

#config_add, #config_get, #config_get_all, #config_get_colorbool, #config_get_regexp, #config_get_urlmatch, #config_list, #config_remove_section, #config_rename_section, #config_replace_all, #config_set, #config_unset, #config_unset_all

Constructor Details

#initialize(execution_context:) ⇒ Repository

Returns a new instance of Repository.

Parameters:

Raises:

  • (ArgumentError) —

    if execution_context is nil



97
98
99
100
101
 
# File 'lib/git/repository.rb', line 97

def initialize(execution_context:)
  raise ArgumentError, 'execution_context must not be nil' if execution_context.nil?

  @execution_context = execution_context
end

Instance Attribute Details

#execution_context ⇒ Git::ExecutionContext::Repository (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 execution context used to run git commands for this repository.

Returns:



90
91
92
 
# File 'lib/git/repository.rb', line 90

def execution_context
  @execution_context
end

Instance Method Details

#binary_path ⇒ String, :use_global_config

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 path to the git binary.

Returns:

  • (String, :use_global_config) —

    the path to the git binary



185
 
# File 'lib/git/repository.rb', line 185

def binary_path = execution_context.binary_path

#config(options = {}) ⇒ Hash{String => String} #config(name, options = {}) ⇒ String #config(name, value, options = {}) ⇒ Git::CommandLineResult

Read or write a git configuration entry

Dispatches to one of three modes depending on the arguments supplied:

  • List — config() returns all visible config entries as a Hash.
  • Get — config(name) returns the value for a single key as a String.
  • Set — config(name, value) writes a value and returns the raw command result.

Overloads:

  • #config(options = {}) ⇒ Hash{String => String}

    Returns all visible config entries, keyed by their full dotted key names (e.g. "user.name").

    Examples:

    List all config entries

    repo.config #=> { "user.name" => "Alice", "core.bare" => "false" }

    List all entries from a custom config file

    repo.config(file: '/path/to/.gitconfig')
#=> { "user.name" => "Alice", "core.bare" => "false" }

    Parameters:

    • options (Hash) (defaults to: {}) —

      options for the list operation

    Options Hash (options):

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

      path to a custom config file to read from instead of the default resolution chain

    Returns:

    • (Hash{String => String}) —

      all visible config entries, keyed by their full dotted key names (e.g. "user.name")

    Raises:

    • (ArgumentError) —

      if unsupported options are provided

  • #config(name, options = {}) ⇒ String

    Returns the value of the config entry.

    Examples:

    Read the committer name from config

    repo.config('user.name') #=> "Alice"

    Read a value from a custom config file

    repo.config('user.name', file: '/path/to/.gitconfig') #=> "Alice"

    Parameters:

    • name (String) —

      the dotted config key to look up (e.g. "user.name")

    • options (Hash) (defaults to: {}) —

      options for the get operation

    Options Hash (options):

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

      path to a custom config file to read from instead of the default resolution chain

    Returns:

    • (String) —

      the value of the config entry

    Raises:

    • (ArgumentError) —

      if unsupported options are provided

  • #config(name, value, options = {}) ⇒ Git::CommandLineResult

    Returns the raw result of git config <name> <value>.

    Examples:

    Set the committer name in local config

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

    Write a value to a custom config file

    repo.config('user.name', 'Alice', file: '/path/to/custom/config')

    Parameters:

    • name (String) —

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

    • value (#to_s) —

      the value to assign; must not be nil (a nil value is treated as "no value" and routes to the get overload). Must not be a Hash (a Hash is treated as the options argument; call value.to_s explicitly before passing if a stringified Hash is genuinely needed). Any other non-nil object is converted to a String via #to_s before being passed to git

    • options (Hash) (defaults to: {}) —

      options for the set operation

    Options Hash (options):

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

      path to a custom config file to write to instead of the repository's default .git/config

    Returns:

    Raises:

    • (ArgumentError) —

      if unsupported options are provided

Raises:



265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/git/repository.rb', line 265

def config(name = nil, value = nil, options = {})
  Git::Deprecation.warn(CONFIG_DEPRECATION_WARNING)
  name, value, options = deprecated_normalize_config_args(name, value, options)

  if !name.nil? && !value.nil?
    deprecated_config_set(name, value, **options)
  elsif name
    deprecated_config_get(name, **options)
  else
    deprecated_config_list(**options)
  end
end

#dir ⇒ Pathname?

Returns the root of the working tree, or nil for a bare repository

Examples:

Get the working directory path

repository.dir #=> #<Pathname:/path/to/repo>

Returns:

  • (Pathname, nil) —

    the working directory path, or nil when bare



110
111
112
113
 
# File 'lib/git/repository.rb', line 110

def dir
  working_dir = execution_context.git_work_dir
  working_dir && Pathname.new(working_dir)
end

#git_dir ⇒ 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.

Returns the git directory path.

Returns:

  • (String, nil) —

    the git directory path



160
 
# File 'lib/git/repository.rb', line 160

def git_dir = execution_context.git_dir

#git_index_file ⇒ 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.

Returns the index file path.

Returns:

  • (String, nil) —

    the index file path



170
 
# File 'lib/git/repository.rb', line 170

def git_index_file = execution_context.git_index_file

#git_ssh ⇒ 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.

Returns the SSH wrapper path.

Returns:

  • (String, nil) —

    the SSH wrapper path



180
 
# File 'lib/git/repository.rb', line 180

def git_ssh = execution_context.git_ssh

#git_version(timeout: nil) ⇒ Git::Version

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 installed git version.

Returns:



175
 
# File 'lib/git/repository.rb', line 175

def git_version(timeout: nil) = execution_context.git_version(timeout: timeout)

#git_work_dir ⇒ 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.

Returns the working directory path.

Returns:

  • (String, nil) —

    the working directory path



165
 
# File 'lib/git/repository.rb', line 165

def git_work_dir = execution_context.git_work_dir

#global_config ⇒ Hash{String => String} #global_config(name) ⇒ String #global_config(name, value) ⇒ Git::CommandLineResult

Read or write a global git configuration entry

Dispatches to one of three modes depending on the arguments supplied, targeting the git global config scope (git config --global):

  • List — global_config() returns all global config entries as a Hash.
  • Get — global_config(name) returns the value for a single key as a String.
  • Set — global_config(name, value) writes a value and returns the raw command result.

Overloads:

  • #global_config ⇒ Hash{String => String}

    Returns all global config entries, keyed by their full dotted key names (e.g. "user.name").

    Examples:

    List all global config entries

    repo.global_config #=> { "user.name" => "Alice", "core.autocrlf" => "false" }

    Returns:

    • (Hash{String => String}) —

      all global config entries, keyed by their full dotted key names (e.g. "user.name")

    Raises:

  • #global_config(name) ⇒ String

    Returns the value of the global config entry.

    Examples:

    Read the global committer name

    repo.global_config('user.name') #=> "Alice"

    Parameters:

    • name (String) —

      the dotted config key to look up (e.g. "user.name")

    Returns:

    • (String) —

      the value of the global config entry

    Raises:

  • #global_config(name, value) ⇒ Git::CommandLineResult

    Returns the raw result of git config --global <name> <value>.

    Examples:

    Set the global committer name

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

    Parameters:

    • name (String) —

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

    • value (#to_s) —

      the value to assign; any object is accepted and converted to a String via #to_s before being passed to git

    Returns:

    Raises:



324
325
326
327
328
329
330
331
332
333
 
# File 'lib/git/repository.rb', line 324

def global_config(name = nil, value = nil)
  Git::Deprecation.warn(GLOBAL_CONFIG_DEPRECATION_WARNING)
  if !name.nil? && !value.nil?
    deprecated_global_config_set(name, value)
  elsif !name.nil?
    deprecated_global_config_get(name)
  else
    deprecated_global_config_list
  end
end

#index ⇒ Pathname?

Returns the git index file

Examples:

Get the index file path

repository.index #=> #<Pathname:/path/to/repo/.git/index>

Returns:

  • (Pathname, nil) —

    the index file path



134
135
136
137
 
# File 'lib/git/repository.rb', line 134

def index
  index_file = execution_context.git_index_file
  index_file && Pathname.new(index_file)
end

#lib ⇒ self

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 self after emitting a deprecation warning.

Legacy callers that used git.lib.some_method can migrate to calling the facade method directly on the repository object. This shim will be removed in v6.0.0.

Returns:

  • (self) 


149
150
151
152
153
154
155
 
# File 'lib/git/repository.rb', line 149

def lib
  Git::Deprecation.warn(
    'Git::Repository#lib is deprecated and will be removed in v6.0.0. ' \
    'Use the repository object directly.'
  )
  self
end

#repo ⇒ Pathname?

Returns the repository (.git) directory

Examples:

Get the repository directory path

repository.repo #=> #<Pathname:/path/to/repo/.git>

Returns:

  • (Pathname, nil) —

    the repository directory path



122
123
124
125
 
# File 'lib/git/repository.rb', line 122

def repo
  repository = execution_context.git_dir
  repository && Pathname.new(repository)
end

#repo_size ⇒ Integer

Returns the size of the repository directory in bytes

Sums the sizes of every regular file under the repository (.git) directory in a single traversal. Symbolic links are not followed, so files that physically live outside the repository (reached through a symlinked directory) are never counted. Files that disappear mid-traversal are silently skipped.

Examples:

Get the repository size in bytes

repository.repo_size #=> 12345

Returns:

  • (Integer) —

    the total size in bytes of the repository directory



348
349
350
351
352
353
354
355
356
357
358
359
360
 
# File 'lib/git/repository.rb', line 348

def repo_size
  repository = repo
  return 0 unless repository&.directory?

  total = 0
  Find.find(repository.to_s) do |path|
    stat = File.lstat(path)
    total += stat.size if stat.file?
  rescue Errno::ENOENT
    next
  end
  total
end