git 4.3.2 → 5.0.0.beta.1

data/lib/git/repository/status_operations.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'git/commands/ls_files'
+require 'git/commands/rev_parse'
+require 'git/escaped_path'
+require 'git/status'
+
+module Git
+  class Repository
+    # Facade methods for repository-status operations
+    #
+    # Provides methods for querying the state of the repository: checking
+    # whether any commits exist, listing untracked working-tree files, and
+    # listing files tracked in the index.
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api public
+    #
+    module StatusOperations
+      # Returns `true` if the repository has no commits yet
+      #
+      # Checks whether `HEAD` can be resolved to a commit object. A brand-new
+      # repository (or one created with `git checkout --orphan`) where no commit
+      # has been made yet will have no commits.
+      #
+      # @example Check whether a repository is empty
+      #   repo.no_commits? #=> true   # freshly initialized, no commits yet
+      #   repo.no_commits? #=> false  # at least one commit exists
+      #
+      # @return [Boolean] `true` when the repository has no commits, `false` otherwise
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status other
+      #   than when the repository has no commits
+      #
+      def no_commits?
+        Git::Commands::RevParse.new(@execution_context).call('HEAD', verify: true)
+        false
+      rescue Git::FailedError => e
+        raise unless e.result.status.exitstatus == 128 &&
+                     e.result.stderr == 'fatal: Needed a single revision'
+
+        true
+      end
+
+      # List all files in the working tree that are not tracked by git
+      #
+      # Runs `git ls-files --others --exclude-standard` from the working tree
+      # root and returns an array of repository-relative file paths. Files that
+      # match `.gitignore` or other standard exclusion rules are omitted.
+      #
+      # @example Get untracked files
+      #   repo.untracked_files #=> ["new_feature.rb", "tmp/debug.log"]
+      #
+      # @example No untracked files
+      #   repo.untracked_files #=> []
+      #
+      # @return [Array<String>] repository-relative paths of untracked,
+      #   non-ignored files; empty when there are none
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      def untracked_files
+        Git::Commands::LsFiles.new(@execution_context).call(
+          others: true, exclude_standard: true, chdir: @execution_context.git_work_dir
+        ).stdout.split("\n").map { |f| Private.unescape_quoted_path(f) }
+      end
+
+      # Returns a {Git::Status} object describing the working tree and index state
+      #
+      # Constructs a {Git::Status} for this repository by collecting information from
+      # `git ls-files --stage`, `git ls-files --others`, `git diff-files`, and
+      # `git diff-index HEAD` (the last only when at least one commit exists). The
+      # result identifies which files have been modified, added, deleted, or are
+      # untracked.
+      #
+      # @example Check which files are modified
+      #   repo.status.changed #=> { "lib/foo.rb" => <Git::Status::StatusFile ...> }
+      #
+      # @example Check for untracked files
+      #   repo.status.untracked #=> { "new_file.rb" => <Git::Status::StatusFile ...> }
+      #
+      # @example Iterate over all status files
+      #   repo.status.each { |file| puts "#{file.path}: #{file.type}" }
+      #
+      # @return [Git::Status] the status of the repository
+      #
+      # @raise [Git::FailedError] if any underlying git command exits with a
+      #   non-zero exit status
+      #
+      def status
+        Git::Status.new(self)
+      end
+
+      # List all files tracked in the index
+      #
+      # Runs `git ls-files --stage` under the given `location` and returns a
+      # hash keyed by file path with per-file index metadata.
+      #
+      # @example List all indexed files in the working tree
+      #   repo.ls_files
+      #   #=> { "README.md" => { path: "README.md", mode_index: "100644",
+      #   #=>                    sha_index: "abc123...", stage: "0" }, ... }
+      #
+      # @example List indexed files under a specific directory
+      #   repo.ls_files('lib/')
+      #   #=> { "lib/git.rb" => { path: "lib/git.rb", ... }, ... }
+      #
+      # @param location [String, nil] the path to restrict the listing to;
+      #   defaults to `'.'` (all tracked files) when `nil`
+      #
+      # @return [Hash{String => Hash}] a hash of index entries keyed by file path
+      #
+      #   Each value is a Hash with the following keys:
+      #   * `:path` [String] the file path
+      #   * `:mode_index` [String] the file's index mode (e.g. `"100644"`)
+      #   * `:sha_index` [String] the file's index SHA
+      #   * `:stage` [String] the merge stage (`"0"` for normal entries)
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      def ls_files(location = nil)
+        location ||= '.'
+        {}.tap do |files|
+          Git::Commands::LsFiles.new(@execution_context).call(location, stage: true).stdout.split("\n").each do |line|
+            info, file = Private.split_status_line(line)
+            mode, sha, stage = info.split
+            files[file] = { path: file, mode_index: mode, sha_index: sha, stage: stage }
+          end
+        end
+      end
+
+      # Private helpers local to {Git::Repository::StatusOperations}
+      #
+      # @api private
+      #
+      module Private
+        module_function
+
+        # Split a tab-delimited status line from `git ls-files --stage` output
+        #
+        # The output format is `<mode> <sha> <stage>\t<file>`. Quoted file paths
+        # (which git uses when the path contains non-ASCII or special characters)
+        # are unescaped before being returned. `line` is assumed to be non-empty
+        # because `git ls-files --stage` never emits blank lines.
+        #
+        # @param line [String] a single line of git ls-files output
+        #
+        # @return [Array<String>] the tab-delimited parts with the last part
+        #   unescaped when it was git-quoted
+        #
+        def split_status_line(line)
+          parts = line.split("\t")
+          parts[-1] = unescape_quoted_path(parts[-1])
+          parts
+        end
+
+        # Unescape a git-quoted path
+        #
+        # Git wraps paths containing non-ASCII or special characters in
+        # double-quotes and octal-escapes each byte. This method strips the
+        # surrounding quotes and delegates unescaping to {Git::EscapedPath}.
+        #
+        # @param path [String] the path as it appears in git output
+        #
+        # @return [String] the unescaped path
+        #
+        def unescape_quoted_path(path)
+          if path.start_with?('"') && path.end_with?('"')
+            Git::EscapedPath.new(path[1..-2]).unescape
+          else
+            path
+          end
+        end
+      end
+
+      private_constant :Private
+    end
+  end
+end

data/lib/git/repository/worktree_operations.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'git/commands/worktree'
+require 'git/worktree'
+require 'git/worktrees'
+
+module Git
+  class Repository
+    # Facade methods for worktree operations
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api public
+    #
+    module WorktreeOperations
+      # Returns all worktrees as an array of directory and SHA pairs
+      #
+      # Lists all worktrees attached to the repository, including the main
+      # worktree and all linked worktrees.
+      #
+      # @example List all worktrees
+      #   repo.worktrees_all
+      #   #=> [["/path/to/main", "4bef5ab..."], ["/tmp/worktree-1", "b8c6320..."]]
+      #
+      # @return [Array<Array(String, String)>] array of `[directory, sha]` pairs
+      #
+      #   `directory` is the worktree path reported by git (absolute or relative,
+      #   depending on repository configuration); `sha` is the full SHA of the
+      #   checked-out HEAD commit
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktrees_all
+        worktree_entries = []
+        current_directory = ''
+        command_output = Git::Commands::Worktree::List.new(@execution_context).call(porcelain: true).stdout
+
+        command_output.each_line(chomp: true) do |line|
+          key, value = line.split(' ', 2)
+          current_directory = value if key == 'worktree'
+          worktree_entries << [current_directory, value] if key == 'HEAD'
+        end
+
+        worktree_entries
+      end
+
+      # Create a new linked worktree at the given directory
+      #
+      # @example Create a worktree at a path (auto-creates a branch)
+      #   repo.worktree_add('/tmp/feature')
+      #
+      # @example Create a worktree and check out an existing commitish
+      #   repo.worktree_add('/tmp/hotfix', 'main')
+      #
+      # @param dir [String] filesystem path for the new worktree
+      #
+      # @param commitish [String, nil] branch, tag, or commit to check out
+      #
+      #   When `nil`, git creates a new branch named after the final path component
+      #
+      # @return [String] the output from the git worktree add command
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktree_add(dir, commitish = nil)
+        args = [dir]
+        args << commitish unless commitish.nil?
+
+        Git::Commands::Worktree::Add.new(@execution_context).call(*args).stdout
+      end
+
+      # Remove a linked worktree
+      #
+      # @example Remove a worktree
+      #   repo.worktree_remove('/tmp/feature')
+      #
+      # @param dir [String] filesystem path of the worktree to remove
+      #
+      # @return [String] the output from the git worktree remove command
+      #   (typically empty)
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktree_remove(dir)
+        Git::Commands::Worktree::Remove.new(@execution_context).call(dir).stdout
+      end
+
+      # Prune stale worktree administrative files
+      #
+      # Removes stale administrative files from `$GIT_DIR/worktrees`. A
+      # worktree becomes stale when its directory no longer exists on disk.
+      #
+      # @example Prune stale worktrees
+      #   repo.worktree_prune
+      #
+      # @return [String] the output from the git worktree prune command
+      #   (typically empty)
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktree_prune
+        Git::Commands::Worktree::Prune.new(@execution_context).call.stdout
+      end
+
+      # Return a {Git::Worktree} object for the given directory and optional commitish
+      #
+      # This is a factory method — it constructs the domain object but does not
+      # immediately execute any git commands.
+      #
+      # @example Get a worktree object for a new path
+      #   wt = repo.worktree('/tmp/feature')
+      #
+      # @example Get a worktree object for a specific branch or commit
+      #   wt = repo.worktree('/tmp/hotfix', 'main')
+      #
+      # @param dir [String] filesystem path for the worktree
+      #
+      # @param commitish [String, nil] branch, tag, or commit to associate with
+      #   the worktree; `nil` means no commitish is specified
+      #
+      # @return [Git::Worktree] a worktree domain object for the given path
+      #
+      def worktree(dir, commitish = nil)
+        Git::Worktree.new(self, dir, commitish)
+      end
+
+      # Return a {Git::Worktrees} collection of all worktrees (main and linked)
+      #
+      # The collection is populated eagerly when this method is called (git runs
+      # at construction time). It is enumerable and supports indexed access by
+      # worktree path.
+      #
+      # @example Iterate over all worktrees
+      #   repo.worktrees.each { |wt| puts wt.dir }
+      #
+      # @example Count worktrees
+      #   repo.worktrees.size
+      #
+      # @example Access a specific worktree by path
+      #   repo.worktrees['/tmp/feature']
+      #
+      # @return [Git::Worktrees] an enumerable collection of all worktrees
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      def worktrees
+        Git::Worktrees.new(self)
+      end
+    end
+  end
+end

data/lib/git/repository.rb

@@ -1,6 +1,269 @@
 # frozen_string_literal: true
 
+require 'find'
+require 'pathname'
+
+require 'git/execution_context/repository'
+require 'git/repository/branching'
+require 'git/repository/committing'
+require 'git/repository/configuring'
+require 'git/repository/diffing'
+require 'git/repository/inspecting'
+require 'git/repository/logging'
+require 'git/repository/merging'
+require 'git/repository/object_operations'
+require 'git/repository/path_resolver'
+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
+    include Git::Repository::Branching
+    include Git::Repository::Committing
+    include Git::Repository::Configuring
+    include Git::Repository::Diffing
+    include Git::Repository::Inspecting
+    include Git::Repository::Logging
+    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
+
+    # Open a working copy at an existing path
+    #
+    # The new repository factories are additive scaffolding introduced by the
+    # architectural redesign. The top-level {Git.open} entry point still returns a
+    # {Git::Base} object; this method exists so future work can route construction
+    # through {Git::Repository} without changing the public entry points.
+    #
+    # Note: this method opens working copies only. To open a bare repository, use
+    # {Git::Repository.bare}.
+    #
+    # @example Open the working copy in the current directory
+    #   repository = Git::Repository.open('.')
+    #
+    # @param working_dir [String] the path to the root of the working copy
+    #
+    #   May be any path inside the working tree when `:repository` is not given.
+    #
+    # @param options [Hash] options that control how the repository is located
+    #
+    # @option options [String] :repository a non-standard path to the `.git`
+    #   directory
+    #
+    #   When given, `working_dir` is used as-is (the working tree root is not
+    #   auto-detected).
+    #
+    # @option options [String] :index a non-standard path to the index file
+    #
+    # @option options [Logger] :log a logger forwarded to the command layer
+    #
+    # @option options [String, nil, :use_global_config] :git_ssh path to a custom SSH executable;
+    #   pass `:use_global_config` (the default) to use `Git::Base.config.git_ssh`
+    #
+    # @option options [String, :use_global_config] :binary_path path to the git binary;
+    #   pass `:use_global_config` (the default) to use `Git::Base.config.binary_path`
+    #
+    # @return [Git::Repository] a repository bound to the resolved paths
+    #
+    # @raise [ArgumentError] if `working_dir` is not a directory or is not inside
+    #   a git working tree
+    #
+    def self.open(working_dir, options = {})
+      raise ArgumentError, "'#{working_dir}' is not a directory" unless Dir.exist?(working_dir)
+
+      working_dir = resolve_open_working_dir(working_dir, options) unless options[:repository]
+
+      paths = PathResolver.resolve_paths(
+        working_directory: working_dir,
+        repository: options[:repository],
+        index: options[:index]
+      )
+
+      from_paths(options, paths)
+    end
+
+    # Open an existing bare repository at `git_dir`
+    #
+    # The new repository factories are additive scaffolding introduced by the
+    # architectural redesign. The top-level {Git.bare} entry point still returns a
+    # {Git::Base} object; this method exists so future work can route construction
+    # through {Git::Repository} without changing the public entry points.
+    #
+    # @example Open a bare repository
+    #   repository = Git::Repository.bare('/path/to/repo.git')
+    #
+    # @param git_dir [String] the path to the bare repository directory
+    #
+    # @param options [Hash] options forwarded to the constructed repository
+    #
+    # @option options [Logger] :log a logger forwarded to the command layer
+    #
+    # @option options [String, nil, :use_global_config] :git_ssh path to a custom SSH executable;
+    #   pass `:use_global_config` (the default) to use `Git::Base.config.git_ssh`
+    #
+    # @option options [String, :use_global_config] :binary_path path to the git binary;
+    #   pass `:use_global_config` (the default) to use `Git::Base.config.binary_path`
+    #
+    # @return [Git::Repository] a repository bound to the bare repository directory
+    #
+    def self.bare(git_dir, options = {})
+      paths = PathResolver.resolve_paths(repository: git_dir, bare: true)
+
+      from_paths(options, paths)
+    end
+
+    # Resolve the worktree root to use as the working directory for `.open`
+    #
+    # Delegates to {PathResolver.root_of_worktree}, forwarding `:binary_path`
+    # and `:git_ssh` from `options`.
+    #
+    # @param working_dir [String] a path inside the working tree
+    #
+    # @param options [Hash] the caller-supplied options hash from `.open`
+    #
+    # @return [String] the absolute path to the root of the working tree
+    #
+    # @raise [ArgumentError] if `working_dir` is not inside a git working tree
+    #
+    # @api private
+    #
+    def self.resolve_open_working_dir(working_dir, options)
+      PathResolver.root_of_worktree(
+        working_dir,
+        binary_path: options.fetch(:binary_path, :use_global_config),
+        git_ssh: options.fetch(:git_ssh, :use_global_config)
+      )
+    end
+    private_class_method :resolve_open_working_dir
+
+    # Build a repository from caller options and resolved paths
+    #
+    # @param options [Hash] the caller-supplied options (`:git_ssh`,
+    #   `:binary_path`, `:log`)
+    #
+    # @param paths [Hash{Symbol => (String, nil)}] the resolved
+    #   `:working_directory`, `:repository`, and `:index` paths
+    #
+    # @return [Git::Repository] the constructed repository
+    #
+    # @api private
+    #
+    def self.from_paths(options, paths)
+      execution_context = Git::ExecutionContext::Repository.from_hash(
+        options.merge(paths), logger: options[:log]
+      )
+      new(execution_context: execution_context)
+    end
+    private_class_method :from_paths
+
+    # @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 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
   end
 end