Class: Git::Repository

Inherits:
Object
  • Object
show all
Includes:
Configuring, Branching, Committing, ContextHelpers, Diffing, Inspecting, Logging, Maintenance, Merging, ObjectOperations, RemoteOperations, Staging, Stashing, StatusOperations, WorktreeOperations, Module.new do # Emit a deprecation warning each time a method is defined in Git::Base so # that authors of monkeypatches are nudged toward Git::Repository. def self.method_added(method_name) Git::Deprecation.warn( 'Monkeypatching Git::Base is deprecated and will be removed in v6.0.0. ' \ "Define #{method_name} in Git::Repository instead." ) super end # Raise a clear error when legacy code calls Git::Base.new directly. def self.new(...) raise NoMethodError, 'Git::Base.new is not supported. Use Git.open, Git.clone, or Git.init instead.' end end
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

Instance Method Summary collapse

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



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

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:



104
105
106
 
# File 'lib/git/repository.rb', line 104

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



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

def binary_path = execution_context.binary_path

#config(name = nil, value = nil, options = {}) ⇒ Hash{String => String}, ...

Reads or writes 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.

Examples:

List all config entries

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

Read a config value

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

Set a config value

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

Parameters:

  • name (String, Hash, nil) (defaults to: nil) —

    the dotted config key, or an options hash for list mode when value and options are omitted

  • value (#to_s, Hash, nil) (defaults to: nil) —

    the value to set, or an options hash in the legacy config(name, options) call shape

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

    options forwarded to git config

Options Hash (options):

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

    path to a custom config file

Returns:

  • (Hash{String => String}, String, Git::CommandLine::Result) —

    all config entries, a single value, or the command result for set mode

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with a non-zero exit status



241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/git/repository.rb', line 241

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



124
125
126
127
 
# File 'lib/git/repository.rb', line 124

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



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

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



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

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



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

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

Parameters:

  • timeout (Numeric, nil) (defaults to: nil) —

    seconds to wait for git version; nil uses the default timeout for this execution context

Returns:



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

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



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

def git_work_dir = execution_context.git_work_dir

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

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::CommandLine::Result

    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:



300
301
302
303
304
305
306
307
308
309
 
# File 'lib/git/repository.rb', line 300

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



148
149
150
151
 
# File 'lib/git/repository.rb', line 148

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) 


163
164
165
166
167
168
169
 
# File 'lib/git/repository.rb', line 163

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



136
137
138
139
 
# File 'lib/git/repository.rb', line 136

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



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

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