git 4.3.2 → 5.0.0.beta.2

data/lib/git/repository.rb

@@ -1,6 +1,208 @@
 # frozen_string_literal: true
 
+require 'find'
+require 'pathname'
+
+require 'git/configuring'
+require 'git/deprecation'
+require 'git/execution_context/repository'
+require 'git/repository/branching'
+require 'git/repository/context_helpers'
+require 'git/repository/committing'
+require 'git/repository/configuring'
+require 'git/repository/diffing'
+require 'git/repository/factories'
+require 'git/repository/inspecting'
+require 'git/repository/logging'
+require 'git/repository/maintenance'
+require 'git/repository/merging'
+require 'git/repository/object_operations'
+require 'git/repository/remote_operations'
+require 'git/repository/staging'
+require 'git/repository/stashing'
+require 'git/repository/status_operations'
+require 'git/repository/worktree_operations'
+
 module Git
-  class Repository < Path
+  # 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. {Git::Repository::Staging}) and included into this class.
+  #
+  # @api public
+  #
+  class Repository
+    extend Git::Repository::Factories
+
+    include Git::Configuring
+    include Git::Repository::Branching
+    include Git::Repository::ContextHelpers
+    include Git::Repository::Committing
+    include Git::Repository::Configuring
+    include Git::Repository::Diffing
+    include Git::Repository::Inspecting
+    include Git::Repository::Logging
+    include Git::Repository::Maintenance
+    include Git::Repository::Merging
+    include Git::Repository::ObjectOperations
+    include Git::Repository::RemoteOperations
+    include Git::Repository::Staging
+    include Git::Repository::Stashing
+    include Git::Repository::StatusOperations
+    include Git::Repository::WorktreeOperations
+
+    # @return [Git::ExecutionContext::Repository] the execution context used to run
+    #   git commands for this repository
+    # @api private
+    attr_reader :execution_context
+
+    # @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
+    #
+    def initialize(execution_context:)
+      raise ArgumentError, 'execution_context must not be nil' if execution_context.nil?
+
+      @execution_context = execution_context
+    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
+    #
+    def dir
+      working_dir = execution_context.git_work_dir
+      working_dir && Pathname.new(working_dir)
+    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
+    #
+    def repo
+      repository = execution_context.git_dir
+      repository && Pathname.new(repository)
+    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
+    #
+    def index
+      index_file = execution_context.git_index_file
+      index_file && Pathname.new(index_file)
+    end
+
+    # 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.
+    #
+    # @return [self]
+    #
+    # @api private
+    #
+    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
+
+    # @return [String, nil] the git directory path
+    #
+    # @api private
+    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
+
+    # @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
+    #
+    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
+
+    private
+
+    # All git config scopes are valid in a repository context
+    #
+    # @return [void]
+    #
+    def assert_valid_scope!(**)
+      nil
+    end
   end
 end

data/lib/git/stash.rb

@@ -1,26 +1,100 @@
 # frozen_string_literal: true
 
 module Git
-  # A stash in a Git repository
+  # Represents a single stash entry in a Git repository
+  #
+  # @example Create a stash and inspect the result
+  #   stash = Git::Stash.new(repo, 'WIP: feature work')
+  #   stash.message  #=> "WIP: feature work"
+  #   stash.saved?   #=> true
+  #
+  # @api public
+  #
   class Stash
-    def initialize(base, message, save: false)
+    # Initialize a Stash object
+    #
+    # When `existing` is `false` (the default), immediately calls {#save} to push
+    # the current working-directory state onto the stash stack.
+    #
+    # @param base [Git::Repository] the git repository
+    #
+    # @param message [String] the stash message
+    #
+    # @param existing [Boolean] (false) when `true`, wraps an existing stash entry
+    #   without pushing any changes
+    #
+    # @return [void]
+    #
+    # @example Create a new stash entry
+    #   stash = Git::Stash.new(repo, 'WIP: feature work')
+    #   stash.saved?  #=> true
+    #
+    # @example Reference an existing stash without pushing
+    #   stash = Git::Stash.new(repo, 'WIP: feature work', existing: true)
+    #   stash.saved?  #=> nil
+    #
+    def initialize(base, message, existing: false)
       @base = base
       @message = message
-      self.save unless save
+      save unless existing
     end
 
+    # Saves the current working-directory state to the stash stack
+    #
+    # @return [Boolean] `true` if changes were stashed, `false` if there were no
+    #   local changes to save
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @example Save changes to the stash stack
+    #   stash = Git::Stash.new(repo, 'WIP', existing: true)
+    #   stash.save  #=> true
+    #
     def save
-      @saved = @base.lib.stash_save(@message)
+      @saved = stash_repository.stash_save(@message)
     end
 
+    # Returns whether the stash was saved successfully
+    #
+    # @return [Boolean, nil] `true` if changes were stashed, `false` if there were no
+    #   local changes, `nil` if {#save} has not been called (e.g. `existing: true`)
+    #
+    # @example Check if changes were stashed
+    #   stash = Git::Stash.new(repo, 'WIP: feature work')
+    #   stash.saved?  #=> true
+    #
     def saved?
       @saved
     end
 
+    # Returns the stash description
+    #
+    # @return [String] the stash message
+    #
+    # @example Read the stash message
+    #   stash = Git::Stash.new(repo, 'WIP: feature work', existing: true)
+    #   stash.message  #=> "WIP: feature work"
+    #
     attr_reader :message
 
+    # Returns the stash description as a string
+    #
+    # @return [String] the stash message
+    #
+    # @example Convert stash to string
+    #   stash = Git::Stash.new(repo, 'WIP: feature work', existing: true)
+    #   stash.to_s  #=> "WIP: feature work"
+    #
     def to_s
       message
     end
+
+    private
+
+    # @return [Git::Repository]
+    #
+    def stash_repository
+      @base
+    end
   end
 end

data/lib/git/stash_info.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Git
+  # Immutable value object representing stash entry information
+  #
+  # StashInfo encapsulates the parsed data from `git stash list` output.
+  # Each entry contains comprehensive information about the stash including
+  # its index, reference name, commit SHA, branch, message, author/committer
+  # details, and timestamps.
+  #
+  # @api public
+  #
+  # @example Create a StashInfo from parsed stash list output
+  #   info = Git::StashInfo.new(
+  #     index: 0,
+  #     name: 'stash@{0}',
+  #     oid: 'abc123def456789...',
+  #     short_oid: 'abc123d',
+  #     branch: 'main',
+  #     message: 'WIP on main: abc123 Initial commit',
+  #     author_name: 'Jane Doe',
+  #     author_email: 'jane@example.com',
+  #     author_date: '2026-01-24T10:30:00-08:00',
+  #     committer_name: 'Jane Doe',
+  #     committer_email: 'jane@example.com',
+  #     committer_date: '2026-01-24T10:30:00-08:00'
+  #   )
+  #
+  #   info.index           # => 0
+  #   info.name            # => 'stash@{0}'
+  #   info.oid             # => 'abc123def456789...'
+  #   info.short_oid       # => 'abc123d'
+  #   info.branch          # => 'main'
+  #   info.message         # => 'WIP on main: abc123 Initial commit'
+  #   info.author_name     # => 'Jane Doe'
+  #   info.author_email    # => 'jane@example.com'
+  #   info.author_date     # => '2026-01-24T10:30:00-08:00'
+  #   info.committer_name  # => 'Jane Doe'
+  #   info.committer_email # => 'jane@example.com'
+  #   info.committer_date  # => '2026-01-24T10:30:00-08:00'
+  #
+  # @!attribute [r] index
+  #   @return [Integer] the stash index (0, 1, 2, ...)
+  #
+  # @!attribute [r] name
+  #   @return [String] the stash reference name (e.g., 'stash@\\{0\\}')
+  #
+  # @!attribute [r] oid
+  #   @return [String] the full 40-character object identifier of the stash
+  #
+  # @!attribute [r] short_oid
+  #   @return [String] the abbreviated object identifier (typically 7 characters)
+  #
+  # @!attribute [r] branch
+  #   @return [String, nil] the branch name where the stash was created,
+  #     or nil for custom stash messages
+  #
+  # @!attribute [r] message
+  #   @return [String] the stash message (e.g., 'WIP on main: abc123 commit msg')
+  #
+  # @!attribute [r] author_name
+  #   @return [String] the name of the stash author
+  #
+  # @!attribute [r] author_email
+  #   @return [String] the email of the stash author
+  #
+  # @!attribute [r] author_date
+  #   @return [String] the author date in ISO 8601 format
+  #
+  # @!attribute [r] committer_name
+  #   @return [String] the name of the stash committer
+  #
+  # @!attribute [r] committer_email
+  #   @return [String] the email of the stash committer
+  #
+  # @!attribute [r] committer_date
+  #   @return [String] the committer date in ISO 8601 format
+  #
+  StashInfo = Data.define(
+    :index,
+    :name,
+    :oid,
+    :short_oid,
+    :branch,
+    :message,
+    :author_name,
+    :author_email,
+    :author_date,
+    :committer_name,
+    :committer_email,
+    :committer_date
+  ) do
+    # Returns the stash reference name
+    #
+    # @return [String] the stash name (e.g., 'stash@\\{0}')
+    #
+    # @example
+    #   info.to_s # => 'stash@{0}'
+    #
+    def to_s
+      name
+    end
+  end
+end

data/lib/git/stashes.rb

@@ -1,56 +1,168 @@
 # frozen_string_literal: true
 
 module Git
-  # object that holds all the available stashes
+  # Collection of stash entries for a Git repository
+  #
+  # @example Iterate over stash entries
+  #   git.stashes.each { |s| puts s.message }
+  #
+  # @example Check and apply a stash
+  #   git.stashes.size   #=> 2
+  #   git.stashes.apply
+  #
+  # @api public
+  #
   class Stashes
     include Enumerable
 
+    # Initialize the stashes collection
+    #
+    # Loads all existing stash entries from the repository at construction time.
+    #
+    # @param base [Git::Repository] the git repository
+    #
+    # @return [void]
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @example Load stashes for a repository
+    #   stashes = Git::Stashes.new(repo)
+    #   stashes.size  #=> 2
+    #
     def initialize(base)
       @stashes = []
-
       @base = base
 
-      @base.lib.stashes_all.each do |indexed_message|
-        _index, message = indexed_message
-        @stashes.unshift(Git::Stash.new(@base, message, save: true))
+      stash_repository.stashes_all.each do |stash|
+        message = stash[1]
+        @stashes.unshift(Git::Stash.new(@base, message, existing: true))
       end
     end
 
+    # Returns all stash entries as an array of index and message pairs
+    #
+    # Entries are listed in oldest-first order matching {Git::Repository#stashes_all}.
+    #
+    # @example List all stash entries
+    #   git.stashes.all  #=> [[0, "testing-stash-all"], [1, "another-stash"]]
     #
-    # Returns an multi-dimensional Array of elements that have been stash saved.
-    # Array is based on position and name. See Example
+    # @return [Array<Array(Integer, String)>] array of `[index, message]` pairs where
+    #   index 0 is the oldest stash
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
-    # @example Returns Array of items that have been stashed
-    #     .all - [0, "testing-stash-all"]]
-    # @return [Array]
     def all
-      @base.lib.stashes_all
+      stash_repository.stashes_all
     end
 
+    # Saves the current working-directory state to a new stash entry
+    #
+    # @param message [String] the stash message
+    #
+    # @return [void]
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @example Save current changes to the stash
+    #   git.stashes.save('WIP: feature work')
+    #   git.stashes.size  #=> 1
+    #
     def save(message)
       s = Git::Stash.new(@base, message)
       @stashes.unshift(s) if s.saved?
     end
 
+    # Applies a stash entry to the working directory
+    #
+    # @param index [Integer, nil] the stash index to apply (default: latest)
+    #
+    # @return [String] the output from the git stash apply command
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @example Apply the most recent stash
+    #   git.stashes.apply
+    #
+    # @example Apply a specific stash by index
+    #   git.stashes.apply(1)
+    #
     def apply(index = nil)
-      @base.lib.stash_apply(index)
+      stash_repository.stash_apply(index)
     end
 
+    # Removes all stash entries
+    #
+    # @return [void]
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @example Clear all stashes
+    #   git.stashes.clear
+    #   git.stashes.size  #=> 0
+    #
     def clear
-      @base.lib.stash_clear
+      stash_repository.stash_clear
       @stashes = []
+      nil
     end
 
+    # Returns the number of stash entries
+    #
+    # @return [Integer] the number of stashes
+    #
+    # @example Check how many stashes exist
+    #   git.stashes.size  #=> 2
+    #
     def size
       @stashes.size
     end
 
+    # Iterates over each stash entry in newest-first order
+    #
+    # @example Iterate over stashes
+    #   git.stashes.each { |s| puts s.message }
+    #
+    # @overload each
+    #
+    #   @return [Enumerator<Git::Stash>] an enumerator over stash entries
+    #
+    # @overload each(&block)
+    #
+    #   @yield [stash] each stash entry
+    #
+    #   @yieldparam stash [Git::Stash] the current stash entry
+    #
+    #   @yieldreturn [void]
+    #
+    #   @return [Array<Git::Stash>] the stash entries
+    #
     def each(&)
       @stashes.each(&)
     end
 
+    # Returns the stash entry at the given index
+    #
+    # Stashes are stored in newest-first order; index 0 is the most recent stash.
+    #
+    # @param index [Integer, #to_i] the stash index (0 = most recent)
+    #
+    # @return [Git::Stash, nil] the stash entry, or `nil` if the index is out of bounds
+    #
+    # @example Access the most recent stash
+    #   git.stashes[0].message  #=> "WIP: feature work"
+    #
     def [](index)
       @stashes[index.to_i]
     end
+
+    private
+
+    # Returns the facade interface for stash operations
+    #
+    # @return [Git::Repository]
+    #
+    def stash_repository
+      @base
+    end
   end
 end