class Git::Repository

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:

**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).
**Calls commands** — invokes one or more ‘Git::Commands::*` classes via the injected `Git::ExecutionContext::Repository`.
**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. {Git::Repository::Staging}) and included into this class.

@api public

Attributes

execution_context [R]

@return [Git::ExecutionContext::Repository] the execution context used to run

git commands for this repository

@api private

Public Class Methods

new (execution_context:)

Source

# File lib/git/repository.rb, line 77
def initialize(execution_context:)
  raise ArgumentError, 'execution_context must not be nil' if execution_context.nil?

  @execution_context = execution_context
end

@param execution_context [Git::ExecutionContext::Repository] the context used

to run git commands for this repository; must not be nil

@raise [ArgumentError] if ‘execution_context` is nil

Public Instance Methods

assert_valid_scope! (**)

Source

# File lib/git/repository.rb, line 205
def assert_valid_scope!(**)
  nil
end

All git config scopes are valid in a repository context

@return [void]

binary_path (= execution_context.binary_path)

Source

# File lib/git/repository.rb, line 152
  def binary_path = execution_context.binary_path

  # 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.
  #
  # @example Get the repository size in bytes
  #   repository.repo_size #=> 12345
  #
  # @return [Integer] the total size in bytes of the repository directory
  #
  # @raise [Git::Error] if the repository directory cannot be traversed, for
  #   example when a subdirectory cannot be searched
  #
  def repo_size
    repository = repo
    return 0 unless repository&.directory?

    Git::SystemCallGuard.call('Failed to compute the repository size') do
      repo_size_of_directory(repository.to_s)
    end
  end

  private

  # Sums the size of every regular file under `dir`
  #
  # Symbolic links are not followed. Entries that disappear between the
  # traversal and the `lstat` call are skipped.
  #
  # @param dir [String] the directory to traverse
  #
  # @return [Integer] the total size in bytes of the files under `dir`
  #
  def repo_size_of_directory(dir)
    total = 0
    Find.find(dir) do |path|
      stat = File.lstat(path)
      total += stat.size if stat.file?
    rescue Errno::ENOENT
      next
    end
    total
  end

  # All git config scopes are valid in a repository context
  #
  # @return [void]
  #
  def assert_valid_scope!(**)
    nil
  end
end

@return [String, :use_global_config] the path to the git binary

@api private

dir ()

Source

# File lib/git/repository.rb, line 90
def dir
  working_dir = execution_context.git_work_dir
  working_dir && Pathname.new(working_dir)
end

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

@example Get the working directory path

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

@return [Pathname, nil] the working directory path, or ‘nil` when bare

git_dir (= execution_context.git_dir)

Source

# File lib/git/repository.rb, line 122
def git_dir = execution_context.git_dir

# @return [String, nil] the working directory path
#
# @api private
def git_work_dir = execution_context.git_work_dir

# @return [String, nil] the index file path
#
# @api private
def git_index_file = execution_context.git_index_file

# Returns the installed git version
#
# @param timeout [Numeric, nil] seconds to wait for `git version`; `nil`
#   uses the default timeout for this execution context
#
# @return [Git::Version] the installed git version
#
# @api private
def git_version(timeout: nil) = execution_context.git_version(timeout: timeout)

# @return [String, nil] the SSH wrapper path
#
# @api private
def git_ssh = execution_context.git_ssh

# @return [String, :use_global_config] the path to the git binary
#
# @api private
def binary_path = execution_context.binary_path

# 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.
#
# @example Get the repository size in bytes
#   repository.repo_size #=> 12345
#
# @return [Integer] the total size in bytes of the repository directory
#
# @raise [Git::Error] if the repository directory cannot be traversed, for
#   example when a subdirectory cannot be searched
#
def repo_size
  repository = repo
  return 0 unless repository&.directory?

  Git::SystemCallGuard.call('Failed to compute the repository size') do
    repo_size_of_directory(repository.to_s)
  end
end

private

# Sums the size of every regular file under `dir`
#
# Symbolic links are not followed. Entries that disappear between the
# traversal and the `lstat` call are skipped.
#
# @param dir [String] the directory to traverse
#
# @return [Integer] the total size in bytes of the files under `dir`
#
def repo_size_of_directory(dir)
  total = 0
  Find.find(dir) do |path|
    stat = File.lstat(path)
    total += stat.size if stat.file?
  rescue Errno::ENOENT
    next
  end
  total
end

# All git config scopes are valid in a repository context
#
# @return [void]
#
def assert_valid_scope!(**)
  nil

@return [String, nil] the git directory path

@api private

git_index_file (= execution_context.git_index_file)

Source

# File lib/git/repository.rb, line 132
def git_index_file = execution_context.git_index_file

# Returns the installed git version
#
# @param timeout [Numeric, nil] seconds to wait for `git version`; `nil`
#   uses the default timeout for this execution context
#
# @return [Git::Version] the installed git version
#
# @api private
def git_version(timeout: nil) = execution_context.git_version(timeout: timeout)

# @return [String, nil] the SSH wrapper path
#
# @api private
def git_ssh = execution_context.git_ssh

# @return [String, :use_global_config] the path to the git binary
#
# @api private
def binary_path = execution_context.binary_path

# 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.
#
# @example Get the repository size in bytes
#   repository.repo_size #=> 12345
#
# @return [Integer] the total size in bytes of the repository directory
#
# @raise [Git::Error] if the repository directory cannot be traversed, for
#   example when a subdirectory cannot be searched
#
def repo_size
  repository = repo
  return 0 unless repository&.directory?

  Git::SystemCallGuard.call('Failed to compute the repository size') do
    repo_size_of_directory(repository.to_s)
  end
end

private

# Sums the size of every regular file under `dir`
#
# Symbolic links are not followed. Entries that disappear between the
# traversal and the `lstat` call are skipped.
#
# @param dir [String] the directory to traverse
#
# @return [Integer] the total size in bytes of the files under `dir`
#
def repo_size_of_directory(dir)
  total = 0
  Find.find(dir) do |path|
    stat = File.lstat(path)
    total += stat.size if stat.file?
  rescue Errno::ENOENT
    next
  end
  total
end

# All git config scopes are valid in a repository context
#
# @return [void]
#
def assert_valid_scope!(**)
  nil
end

@return [String, nil] the index file path

@api private

git_ssh (= execution_context.git_ssh)

Source

# File lib/git/repository.rb, line 147
    def git_ssh = execution_context.git_ssh

    # @return [String, :use_global_config] the path to the git binary
    #
    # @api private
    def binary_path = execution_context.binary_path

    # 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.
    #
    # @example Get the repository size in bytes
    #   repository.repo_size #=> 12345
    #
    # @return [Integer] the total size in bytes of the repository directory
    #
    # @raise [Git::Error] if the repository directory cannot be traversed, for
    #   example when a subdirectory cannot be searched
    #
    def repo_size
      repository = repo
      return 0 unless repository&.directory?

      Git::SystemCallGuard.call('Failed to compute the repository size') do
        repo_size_of_directory(repository.to_s)
      end
    end

    private

    # Sums the size of every regular file under `dir`
    #
    # Symbolic links are not followed. Entries that disappear between the
    # traversal and the `lstat` call are skipped.
    #
    # @param dir [String] the directory to traverse
    #
    # @return [Integer] the total size in bytes of the files under `dir`
    #
    def repo_size_of_directory(dir)
      total = 0
      Find.find(dir) do |path|
        stat = File.lstat(path)
        total += stat.size if stat.file?
      rescue Errno::ENOENT
        next
      end
      total
    end

    # All git config scopes are valid in a repository context
    #
    # @return [void]
    #
    def assert_valid_scope!(**)
      nil
    end
  end
end

@return [String, nil] the SSH wrapper path

@api private

git_version (timeout: nil)

Source

# File lib/git/repository.rb, line 142
  def git_version(timeout: nil) = execution_context.git_version(timeout: timeout)

  # @return [String, nil] the SSH wrapper path
  #
  # @api private
  def git_ssh = execution_context.git_ssh

  # @return [String, :use_global_config] the path to the git binary
  #
  # @api private
  def binary_path = execution_context.binary_path

  # 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.
  #
  # @example Get the repository size in bytes
  #   repository.repo_size #=> 12345
  #
  # @return [Integer] the total size in bytes of the repository directory
  #
  # @raise [Git::Error] if the repository directory cannot be traversed, for
  #   example when a subdirectory cannot be searched
  #
  def repo_size
    repository = repo
    return 0 unless repository&.directory?

    Git::SystemCallGuard.call('Failed to compute the repository size') do
      repo_size_of_directory(repository.to_s)
    end
  end

  private

  # Sums the size of every regular file under `dir`
  #
  # Symbolic links are not followed. Entries that disappear between the
  # traversal and the `lstat` call are skipped.
  #
  # @param dir [String] the directory to traverse
  #
  # @return [Integer] the total size in bytes of the files under `dir`
  #
  def repo_size_of_directory(dir)
    total = 0
    Find.find(dir) do |path|
      stat = File.lstat(path)
      total += stat.size if stat.file?
    rescue Errno::ENOENT
      next
    end
    total
  end

  # All git config scopes are valid in a repository context
  #
  # @return [void]
  #
  def assert_valid_scope!(**)
    nil
  end
end

Returns the installed git version

@param timeout [Numeric, nil] seconds to wait for ‘git version`; `nil`

uses the default timeout for this execution context

@return [Git::Version] the installed git version

@api private

git_work_dir (= execution_context.git_work_dir)

Source

# File lib/git/repository.rb, line 127
def git_work_dir = execution_context.git_work_dir

# @return [String, nil] the index file path
#
# @api private
def git_index_file = execution_context.git_index_file

# Returns the installed git version
#
# @param timeout [Numeric, nil] seconds to wait for `git version`; `nil`
#   uses the default timeout for this execution context
#
# @return [Git::Version] the installed git version
#
# @api private
def git_version(timeout: nil) = execution_context.git_version(timeout: timeout)

# @return [String, nil] the SSH wrapper path
#
# @api private
def git_ssh = execution_context.git_ssh

# @return [String, :use_global_config] the path to the git binary
#
# @api private
def binary_path = execution_context.binary_path

# 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.
#
# @example Get the repository size in bytes
#   repository.repo_size #=> 12345
#
# @return [Integer] the total size in bytes of the repository directory
#
# @raise [Git::Error] if the repository directory cannot be traversed, for
#   example when a subdirectory cannot be searched
#
def repo_size
  repository = repo
  return 0 unless repository&.directory?

  Git::SystemCallGuard.call('Failed to compute the repository size') do
    repo_size_of_directory(repository.to_s)
  end
end

private

# Sums the size of every regular file under `dir`
#
# Symbolic links are not followed. Entries that disappear between the
# traversal and the `lstat` call are skipped.
#
# @param dir [String] the directory to traverse
#
# @return [Integer] the total size in bytes of the files under `dir`
#
def repo_size_of_directory(dir)
  total = 0
  Find.find(dir) do |path|
    stat = File.lstat(path)
    total += stat.size if stat.file?
  rescue Errno::ENOENT
    next
  end
  total
end

# All git config scopes are valid in a repository context
#
# @return [void]
#
def assert_valid_scope!(**)
  nil

@return [String, nil] the working directory path

@api private

index ()

Source

# File lib/git/repository.rb, line 114
def index
  index_file = execution_context.git_index_file
  index_file && Pathname.new(index_file)
end

Returns the git index file

@example Get the index file path

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

@return [Pathname, nil] the index file path

repo ()

Source

# File lib/git/repository.rb, line 102
def repo
  repository = execution_context.git_dir
  repository && Pathname.new(repository)
end

Returns the repository (‘.git`) directory

@example Get the repository directory path

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

@return [Pathname, nil] the repository directory path

repo_size ()

Source

# File lib/git/repository.rb, line 170
def repo_size
  repository = repo
  return 0 unless repository&.directory?

  Git::SystemCallGuard.call('Failed to compute the repository size') do
    repo_size_of_directory(repository.to_s)
  end
end

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.

@example Get the repository size in bytes

repository.repo_size #=> 12345

@return [Integer] the total size in bytes of the repository directory

@raise [Git::Error] if the repository directory cannot be traversed, for

example when a subdirectory cannot be searched

repo_size_of_directory (dir)

Source

# File lib/git/repository.rb, line 190
def repo_size_of_directory(dir)
  total = 0
  Find.find(dir) do |path|
    stat = File.lstat(path)
    total += stat.size if stat.file?
  rescue Errno::ENOENT
    next
  end
  total
end

Sums the size of every regular file under ‘dir`

Symbolic links are not followed. Entries that disappear between the traversal and the ‘lstat` call are skipped.

@param dir [String] the directory to traverse

@return [Integer] the total size in bytes of the files under ‘dir`