git 1.19.1 → 5.5.0

data/lib/git/repository/status_operations.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require 'git/commands/ls_files'
+require 'git/commands/rev_parse'
+require 'git/commands/status'
+require 'git/escaped_path'
+require 'git/parsers/status'
+require 'git/status'
+require 'git/status_info'
+
+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 private
+    #
+    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 v6.0.0. ' \
+          '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::StatusInfo} describing the index and working tree state
+      #
+      # Runs `git status` in porcelain v2 format with NUL-separated entries and
+      # every untracked file listed individually, then reads `core.ignoreCase`
+      # as a boolean so that the path predicates on the result compare paths the
+      # way git does in this repository. Every entry type git reports is
+      # represented, including renames, copies, and merge conflicts. Clean
+      # tracked paths are not reported by `git status`, so they are absent from
+      # the result; the deprecated {#status} listed them, and {#ls_files} still
+      # does.
+      #
+      # @example Check which files are modified
+      #   repo.status_info.changed
+      #   #=> { "lib/foo.rb" => #<data Git::StatusFileInfo path="lib/foo.rb", ...> }
+      #
+      # @example Check for untracked files
+      #   repo.status_info.untracked.keys #=> ["new_file.rb"]
+      #
+      # @example Check one path
+      #   repo.status_info.changed?('lib/foo.rb') #=> true
+      #
+      # @example Iterate over every entry
+      #   repo.status_info.files.each do |file|
+      #     puts "#{file.index_status}#{file.worktree_status} #{file.path}"
+      #   end
+      #
+      # @return [Git::StatusInfo] the status of the repository
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-status git-status
+      #
+      def status_info
+        result = Git::Commands::Status.new(@execution_context).call(
+          porcelain: 'v2', z: true, untracked_files: 'all'
+        )
+        files = Git::Parsers::Status.parse(result.stdout)
+        ignore_case = config_get('core.ignoreCase', type: 'bool')&.value == 'true'
+        Git::StatusInfo.new(files: files, ignore_case: ignore_case)
+      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.
+      #
+      # Emits one deprecation warning per call. The {Git::Status} it constructs is
+      # built with warnings silenced so the caller does not see a second one.
+      #
+      # @example Check which files are modified (deprecated; use status_info)
+      #   repo.status.changed.keys      #=> ["lib/foo.rb"]
+      #   repo.status_info.changed.keys #=> ["lib/foo.rb"]
+      #
+      # @return [Git::Status] the status of the repository
+      #
+      # @raise [Git::FailedError] if any underlying git command exits with a
+      #   non-zero exit status
+      #
+      # @deprecated Use {#status_info} instead
+      #
+      def status
+        Git::Deprecation.warn(
+          'Git::Repository#status is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#status_info instead.'
+        )
+        Git::Deprecation.silence { 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,339 @@
+# frozen_string_literal: true
+
+require 'git/commands/worktree'
+require 'git/parsers/worktree'
+require 'git/worktree'
+require 'git/worktree_info'
+require 'git/worktrees'
+
+module Git
+  class Repository
+    # Facade methods for worktree operations: listing, adding, removing, moving,
+    # locking, repairing, and pruning worktrees
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api private
+    #
+    module WorktreeOperations
+      # Returns every worktree attached to the repository
+      #
+      # Lists the main worktree first, then each linked worktree, in the order
+      # git reports them. The main worktree of a bare repository is included
+      # with {Git::WorktreeInfo#bare?} true and no head or branch.
+      #
+      # @example List all worktrees
+      #   repo.worktree_list.map(&:path)
+      #   #=> ["/path/to/main", "/tmp/feature"]
+      #
+      # @example Find the worktree that has a branch checked out
+      #   info = repo.worktree_list.find { |w| w.branch == 'refs/heads/feature' }
+      #   info.path     #=> "/tmp/feature"
+      #   info.head     #=> "b8c63202c3c0ebd37b7e45fd0c22e6c20d5bead1"
+      #   info.locked?  #=> false
+      #
+      # @return [Array<Git::WorktreeInfo>] one entry per worktree
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @raise [Git::UnexpectedResultError] if the worktree listing cannot be
+      #   parsed
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktree_list
+        result = Git::Commands::Worktree::List.new(@execution_context).call(porcelain: true)
+        Git::Parsers::Worktree.parse_list(result.stdout)
+      end
+
+      # Returns all worktrees as an array of directory and SHA pairs
+      #
+      # Lists the main worktree and all linked worktrees. The main worktree of
+      # a bare repository has no checked-out commit and is omitted.
+      #
+      # @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
+      #
+      # @deprecated Use {#worktree_list} instead
+      #
+      #   {#worktree_list} returns one {Git::WorktreeInfo} per worktree, with
+      #   `path` and `head` in place of the pair, and includes the main worktree
+      #   of a bare repository.
+      #
+      # @see #worktree_list
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktrees_all
+        Git::Deprecation.warn(
+          'Git::Repository#worktrees_all is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#worktree_list instead.'
+        )
+        worktree_list.reject { |worktree| worktree.head.nil? }.map { |worktree| [worktree.path, worktree.head] }
+      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 by path
+      #   repo.worktree_remove('/tmp/feature')
+      #
+      # @example Remove a worktree from the list
+      #   info = repo.worktree_list.find { |w| w.branch == 'refs/heads/feature' }
+      #   repo.worktree_remove(info)
+      #
+      # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
+      #   remove, or its entry from {#worktree_list}
+      #
+      # @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(worktree)
+        Git::Commands::Worktree::Remove.new(@execution_context).call(worktree.to_s).stdout
+      end
+
+      # Move a linked worktree to a new location
+      #
+      # @example Move a worktree
+      #   repo.worktree_move('/tmp/feature', '/tmp/feature-moved')
+      #
+      # @example Move a locked worktree
+      #   repo.worktree_move('/tmp/feature', '/tmp/feature-moved', force: 2)
+      #
+      # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
+      #   move, or its entry from {#worktree_list}
+      #
+      # @param new_path [String] the destination path
+      #
+      # @param opts [Hash] options for the move
+      #
+      # @option opts [Boolean, Integer, nil] :force (nil) override git's
+      #   safeguards; git refuses to move a locked worktree unless the flag is
+      #   given twice, so pass `2` for that
+      #
+      # @return [String] the output from the git worktree move command
+      #   (typically empty)
+      #
+      # @raise [ArgumentError] if unsupported options are provided
+      #
+      # @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_move(worktree, new_path, opts = {})
+        Git::Commands::Worktree::Move.new(@execution_context).call(worktree.to_s, new_path, **opts).stdout
+      end
+
+      # Lock a linked worktree so that `git worktree prune` leaves it alone
+      #
+      # Lock a worktree whose directory is on removable media or a network
+      # share that is not always mounted.
+      #
+      # @example Lock a worktree
+      #   repo.worktree_lock('/tmp/feature')
+      #
+      # @example Lock a worktree with a reason
+      #   repo.worktree_lock('/tmp/feature', reason: 'on an external drive')
+      #
+      # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
+      #   lock, or its entry from {#worktree_list}
+      #
+      # @param opts [Hash] options for the lock
+      #
+      # @option opts [String, nil] :reason (nil) an explanation stored with the
+      #   lock and reported as {Git::WorktreeInfo#lock_reason}
+      #
+      # @return [String] the output from the git worktree lock command
+      #   (typically empty)
+      #
+      # @raise [ArgumentError] if unsupported options are provided
+      #
+      # @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_lock(worktree, opts = {})
+        Git::Commands::Worktree::Lock.new(@execution_context).call(worktree.to_s, **opts).stdout
+      end
+
+      # Unlock a linked worktree
+      #
+      # @example Unlock a worktree
+      #   repo.worktree_unlock('/tmp/feature')
+      #
+      # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
+      #   unlock, or its entry from {#worktree_list}
+      #
+      # @return [String] the output from the git worktree unlock 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_unlock(worktree)
+        Git::Commands::Worktree::Unlock.new(@execution_context).call(worktree.to_s).stdout
+      end
+
+      # Repair the links between the repository and its linked worktrees
+      #
+      # With no paths, repairs the link from each linked worktree back to the
+      # repository, which is needed after the repository directory was moved.
+      # Given the current paths of linked worktrees that were moved without
+      # {#worktree_move}, also repairs the repository's links to them.
+      #
+      # @example Repair after the repository directory was moved
+      #   repo.worktree_repair
+      #
+      # @example Repair after a linked worktree was moved by hand
+      #   repo.worktree_repair('/new/path/to/feature')
+      #
+      # @param paths [Array<String, Git::WorktreeInfo>] the current paths of the
+      #   worktrees to repair, or their entries from {#worktree_list}
+      #
+      # @return [String] the output from the git worktree repair command, which
+      #   reports each repair made
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @raise [Git::VersionError] if the installed git is older than 2.29.0
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktree_repair(*paths)
+        Git::Commands::Worktree::Repair.new(@execution_context).call(*paths.map(&:to_s)).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
+      #
+      # @deprecated Use {#worktree_add} and {#worktree_remove} instead
+      #
+      #   `repo.worktree(dir, commitish).add` becomes
+      #   `repo.worktree_add(dir, commitish)` and `repo.worktree(dir).remove`
+      #   becomes `repo.worktree_remove(dir)`. Read a worktree's checked-out
+      #   commit from {Git::WorktreeInfo#head} via {#worktree_list}.
+      #
+      # @see #worktree_add
+      #
+      # @see #worktree_remove
+      #
+      def worktree(dir, commitish = nil)
+        Git::Deprecation.warn(
+          'Git::Repository#worktree is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#worktree_add and Git::Repository#worktree_remove instead.'
+        )
+        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
+      #
+      # @deprecated Use {#worktree_list} instead
+      #
+      #   {#worktree_list} returns `Array<Git::WorktreeInfo>`. Look a worktree up
+      #   by path with `worktree_list.find { |w| w.path == path }` in place of
+      #   `worktrees[path]`, and call {#worktree_prune} in place of
+      #   `worktrees.prune`. Calling this method emits one deprecation warning.
+      #
+      # @see #worktree_list
+      #
+      def worktrees
+        Git::Deprecation.warn(
+          'Git::Repository#worktrees is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#worktree_list instead.'
+        )
+        Git::Worktrees.new(self)
+      end
+    end
+  end
+end