git 4.3.2 → 5.0.0.beta.2

data/lib/git/repository/stashing.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'git/commands/stash'
+require 'git/parsers/stash'
+
+module Git
+  class Repository
+    # Facade methods for stash operations
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api public
+    #
+    module Stashing
+      # Returns all stash entries as an array of index and message pairs
+      #
+      # Lists all stash entries in the repository ordered from oldest to newest.
+      # The index is a sequential number starting from 0 for the oldest stash. The
+      # message is the stash description with the leading branch prefix (e.g.
+      # `"On main:"` or `"WIP on main:"`) stripped.
+      #
+      # @note The sequential index returned here is **not** the same as git's
+      #   `stash@{N}` reference used by {#stash_apply}. In git, `stash@{0}` is the
+      #   **most recent** stash, while index `0` here is the **oldest**. To apply a
+      #   specific stash from this list, convert the entry's position to a git
+      #   reference: `'stash@{%d}' % (total - 1 - index)`, or pass the string
+      #   reference directly to {#stash_apply}.
+      #
+      # @example List all stashes (oldest first)
+      #   repo.stashes_all #=> [[0, "Fix bug"], [1, "Add feature"]]
+      #
+      # @return [Array<Array(Integer, String)>] array of `[index, message]` pairs
+      #   where index is the sequential position (0 is oldest) and message is the
+      #   stash description with the branch prefix stripped
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      def stashes_all
+        result = Git::Commands::Stash::List.new(@execution_context).call
+        stashes = Git::Parsers::Stash.parse_list(result.stdout)
+        stashes.reverse.each_with_index.map do |info, i|
+          message = info.message.sub(/^(?:WIP on|On)\s+[^:]+:\s*/, '')
+          [i, message]
+        end
+      end
+
+      # Returns stash entries as a formatted string matching `git stash list` output
+      #
+      # @deprecated Use {#stashes_all} instead.
+      #
+      # @example List stashes as a formatted string
+      #   repo.stash_list #=> "stash@{0}: On main: WIP\nstash@{1}: On feature: Fix bug"
+      #
+      # @return [String] newline-joined `"stash@{n}: <full message>"` entries, or an
+      #   empty string when there are no stashes; the format matches `git stash list`
+      #   output
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see #stashes_all
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      def stash_list
+        Git::Deprecation.warn(
+          'Git::Repository#stash_list is deprecated and will be removed in a future version. ' \
+          'Use Git::Repository#stashes_all instead.'
+        )
+        result = Git::Commands::Stash::List.new(@execution_context).call
+        stashes = Git::Parsers::Stash.parse_list(result.stdout)
+        stashes.map { |info| "#{info.name}: #{info.message}" }.join("\n")
+      end
+
+      # Save the current working directory and index state to a new stash
+      #
+      # @param message [String] the stash message
+      #
+      # @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 current changes
+      #   repo.stash_save('WIP: feature work')
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      def stash_save(message) # rubocop:disable Naming/PredicateMethod
+        result = Git::Commands::Stash::Push.new(@execution_context).call(message: message)
+        !result.stdout.include?('No local changes to save')
+      end
+
+      # Apply a stash to the working directory
+      #
+      # Applies the changes recorded in a stash entry to the working directory
+      # without removing the entry from the stash list. Unlike `git stash pop`,
+      # the stash entry is preserved after applying.
+      #
+      # @example Apply the most recent stash
+      #   repo.stash_apply #=> "HEAD is now at abc1234 Initial commit"
+      #
+      # @example Apply a specific stash entry by reference
+      #   repo.stash_apply('stash@{1}') #=> "HEAD is now at abc1234 Initial commit"
+      #
+      # @param id [String, Integer, nil] the stash identifier (e.g., `'stash@{0}'`,
+      #   `0`) or `nil` to apply the most recent stash entry. When an Integer is
+      #   given it is passed directly to git as `stash@{N}`, where `0` is the
+      #   **most recent** stash — the opposite order from {#stashes_all}'s
+      #   sequential indices, where `0` is the **oldest** stash.
+      #
+      # @return [String] the output from the git stash apply command
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      def stash_apply(id = nil)
+        Git::Commands::Stash::Apply.new(@execution_context).call(id).stdout
+      end
+
+      # Remove all stash entries
+      #
+      # Removes all entries from the stash list. Use with caution as this
+      # operation cannot be undone.
+      #
+      # @return [String] the output from the git stash clear command
+      #   (typically empty)
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @example Clear all stashes
+      #   repo.stash_clear #=> ""
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      def stash_clear
+        Git::Commands::Stash::Clear.new(@execution_context).call.stdout
+      end
+    end
+  end
+end

data/lib/git/repository/status_operations.rb

@@ -0,0 +1,201 @@
+# 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
+
+      # Returns `true` if the repository has no commits yet
+      #
+      # @example Check whether a repository is empty
+      #   repo.empty? #=> true   # freshly initialized, no commits yet
+      #   repo.empty? #=> 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
+      #
+      # @deprecated Use {#no_commits?} instead
+      #
+      def empty?
+        Git::Deprecation.warn(
+          'Git::Repository#empty? is deprecated and will be removed in a future version. ' \
+          'Use Git::Repository#no_commits? instead.'
+        )
+        no_commits?
+      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