git 1.19.1 → 5.5.0

data/lib/git/repository/committing.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require 'git/commands/commit'
+require 'git/commands/commit_tree'
+require 'git/commands/write_tree'
+require 'git/repository/shared_private'
+
+module Git
+  class Repository
+    # Facade methods for committing operations: recording commits, manipulating
+    # tree objects, and building commit objects outside the working tree
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api private
+    #
+    module Committing
+      # Option keys accepted by {#commit}
+      COMMIT_ALLOWED_OPTS = %i[
+        all amend allow_empty allow_empty_message author date
+        gpg_sign no_gpg_sign no_verify
+      ].freeze
+      private_constant :COMMIT_ALLOWED_OPTS
+
+      # Option keys accepted by {#commit_tree}
+      COMMIT_TREE_ALLOWED_OPTS = %i[parent p parents message m].freeze
+      private_constant :COMMIT_TREE_ALLOWED_OPTS
+
+      # Record staged changes as a new commit
+      #
+      # @example Commit with a message
+      #   repo.commit('Add README')
+      #
+      # @example Amend the previous commit, reusing its message
+      #   repo.commit(nil, amend: true)
+      #
+      # @example Stage all modified files and commit
+      #   repo.commit('Cleanup', all: true)
+      #
+      # @param message [String, nil] the commit message; pass `nil` to omit
+      #   (e.g. when using `:amend` to reuse the previous message)
+      #
+      # @param opts [Hash] options for the commit command
+      #
+      # @option opts [Boolean, nil] :all (nil) automatically stage modified and
+      #   deleted files before committing
+      #
+      # @option opts [Boolean, nil] :amend (nil) replace the tip of the current
+      #   branch with a new commit
+      #
+      # @option opts [Boolean, nil] :allow_empty (nil) allow committing with no
+      #   changes
+      #
+      # @option opts [Boolean, nil] :allow_empty_message (nil) allow committing
+      #   with an empty message
+      #
+      # @option opts [String] :author (nil) override the commit author in
+      #   `A U Thor <author@example.com>` format
+      #
+      # @option opts [String] :date (nil) override the author date
+      #
+      # @option opts [Boolean, String, nil] :gpg_sign (nil) GPG-sign the commit
+      #
+      # @option opts [Boolean, nil] :no_gpg_sign (nil) disable GPG signing
+      #
+      # @option opts [Boolean, nil] :no_verify (nil) bypass the pre-commit and
+      #   commit-msg hooks
+      #
+      # @return [String] git's stdout from the commit
+      #
+      # @raise [ArgumentError] when unsupported options are provided
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def commit(message, opts = {})
+        opts = normalize_commit_options(opts)
+        SharedPrivate.assert_valid_opts!(COMMIT_ALLOWED_OPTS, **opts)
+
+        call_opts = { no_edit: true }
+        call_opts[:message] = message if message
+
+        Git::Commands::Commit.new(@execution_context).call(**call_opts, **opts).stdout
+      end
+
+      # Commit all modified tracked files without explicitly staging them first
+      #
+      # Equivalent to calling {#commit} with `all: true` merged into `opts`.
+      #
+      # @example Commit all changes with a message
+      #   repo.commit_all('Update everything')
+      #
+      # @param message [String, nil] the commit message; pass `nil` to omit
+      #   (e.g. when using `:amend` to reuse the previous message)
+      #
+      # @param opts [Hash] additional options forwarded to {#commit}
+      #
+      # @option opts [Boolean, nil] :all (nil) ignored because this method
+      #   always commits with `all: true`
+      #
+      # @option opts [Boolean, nil] :amend (nil) replace the tip of the current
+      #   branch with a new commit
+      #
+      # @option opts [Boolean, nil] :allow_empty (nil) allow committing with no
+      #   changes
+      #
+      # @option opts [Boolean, nil] :allow_empty_message (nil) allow committing
+      #   with an empty message
+      #
+      # @option opts [String] :author (nil) override the commit author in
+      #   `A U Thor <author@example.com>` format
+      #
+      # @option opts [String] :date (nil) override the author date
+      #
+      # @option opts [Boolean, String, nil] :gpg_sign (nil) GPG-sign the commit
+      #
+      # @option opts [Boolean, nil] :no_gpg_sign (nil) disable GPG signing
+      #
+      # @option opts [Boolean, nil] :no_verify (nil) bypass the pre-commit and
+      #   commit-msg hooks
+      #
+      # @return [String] git's stdout from the commit
+      #
+      # @raise [ArgumentError] when unsupported options are provided
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def commit_all(message, opts = {})
+        commit(message, opts.merge(all: true))
+      end
+
+      # Create a commit object from a tree SHA without moving HEAD
+      #
+      # Unlike {#commit}, this does not read the index; it directly wraps
+      # `git commit-tree`.
+      #
+      # @example Commit a tree with a parent
+      #   repo.commit_tree('deadbeef', message: 'snapshot', parent: 'HEAD')
+      #
+      # @param tree [String, nil] the tree SHA to commit; defaults to `nil`
+      #
+      # @param opts [Hash] options for the commit-tree command
+      #
+      # @option opts [String, Array<String>] :m (nil) the commit message
+      #   paragraph(s) (short form)
+      #
+      # @option opts [String, Array<String>] :message (nil) the commit message
+      #   paragraph(s) (normalized to `:m` before passing to the command)
+      #
+      # @option opts [String, Array<String>] :p (nil) parent commit SHA(s)
+      #
+      # @option opts [String] :parent (nil) a single parent commit SHA
+      #   (normalized to `:p`)
+      #
+      # @option opts [Array<String>] :parents (nil) multiple parent commit
+      #   SHAs (normalized to `:p`)
+      #
+      # @return [String] the SHA of the newly created commit object
+      #
+      # @raise [ArgumentError] when unsupported options are provided
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def commit_tree(tree = nil, opts = {}) # rubocop:disable Metrics/AbcSize
+        SharedPrivate.assert_valid_opts!(COMMIT_TREE_ALLOWED_OPTS, **opts)
+
+        opts = opts.dup
+        opts[:p] = opts.delete(:parents) if opts.key?(:parents)
+        opts[:p] = opts.delete(:parent) if opts.key?(:parent)
+        opts[:m] = opts.delete(:message) if opts.key?(:message)
+        opts[:m] = "commit tree #{tree}" unless opts[:m]
+
+        Git::Commands::CommitTree.new(@execution_context).call(tree, **opts).stdout
+      end
+
+      # Write the current index to a tree object in the object store
+      #
+      # @example Get the tree SHA of the current index
+      #   tree_sha = repo.write_tree
+      #
+      # @return [String] the SHA of the tree object written
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def write_tree
+        Git::Commands::WriteTree.new(@execution_context).call.stdout
+      end
+
+      # Write the current index to a tree object and immediately commit it
+      #
+      # Combines {#write_tree} and {#commit_tree} in a single call.
+      #
+      # @example Commit the current index as a snapshot
+      #   commit_sha = repo.write_and_commit_tree(message: 'snapshot')
+      #
+      # @param opts [Hash] options forwarded to {#commit_tree}
+      #
+      # @option opts [String, Array<String>] :m (nil) the commit message
+      #   paragraph(s) (short form)
+      #
+      # @option opts [String, Array<String>] :message (nil) the commit message
+      #   paragraph(s) (normalized to `:m` before passing to the command)
+      #
+      # @option opts [String, Array<String>] :p (nil) parent commit SHA(s)
+      #
+      # @option opts [String] :parent (nil) a single parent commit SHA
+      #   (normalized to `:p`)
+      #
+      # @option opts [Array<String>] :parents (nil) multiple parent commit
+      #   SHAs (normalized to `:p`)
+      #
+      # @return [String] the SHA of the newly created commit object
+      #
+      # @raise [ArgumentError] when unsupported options are provided
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def write_and_commit_tree(opts = {})
+        commit_tree(write_tree, opts)
+      end
+
+      private
+
+      # Normalizes deprecated commit options into their supported form
+      #
+      # @param opts [Hash] caller-provided commit options
+      #
+      # @option opts [Boolean, nil] :add_all (nil) deprecated alias for `:all`
+      #
+      # @return [Hash] options with deprecated aliases translated
+      #
+      # @api private
+      #
+      def normalize_commit_options(opts)
+        opts = opts.dup
+        return opts unless opts.key?(:add_all)
+
+        Git::Deprecation.warn(
+          'The :add_all option for #commit is deprecated and will be removed in v6.0.0. ' \
+          'Use :all instead.'
+        )
+        opts[:all] = opts.delete(:add_all)
+        opts
+      end
+    end
+  end
+end

data/lib/git/repository/context_helpers.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+require 'tmpdir'
+require 'git/execution_context/repository'
+
+module Git
+  class Repository
+    # Facade methods for block-based directory and index context helpers
+    #
+    # These helpers allow callers to temporarily change the working directory,
+    # the git index, or both, restoring the original state unconditionally when
+    # the block exits — even if the block raises an exception.
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api private
+    #
+    module ContextHelpers
+      # Changes the current working directory to the repository working directory
+      # for the duration of the block
+      #
+      # @example Write a file inside the repository working directory
+      #   repo.chdir do |dir|
+      #     File.write('hello.txt', 'Hello, world!')
+      #     repo.add('hello.txt')
+      #   end
+      #
+      # @return [Object] the value returned by the block
+      #
+      # @raise [ArgumentError] if the repository has no working directory (bare
+      #   repository)
+      #
+      # @yield [dir] the repository working directory
+      #
+      # @yieldparam dir [Pathname] the working directory path
+      #
+      # @yieldreturn [Object] returned as the method's return value
+      #
+      def chdir
+        raise ArgumentError, 'cannot chdir: repository has no working directory (bare repository)' if dir.nil?
+
+        Dir.chdir(dir.to_s) { yield dir }
+      end
+
+      # Temporarily switches the git index to `new_index` for the duration of
+      # the block
+      #
+      # Rebuilds the repository execution context to point to the new index file,
+      # yields `self`, then unconditionally restores the original execution
+      # context — even if the block raises an exception.
+      #
+      # @example Read a tree into a custom index
+      #   repo.with_index('/tmp/custom.index') do
+      #     repo.read_tree('HEAD')
+      #   end
+      #
+      # @param new_index [String, Pathname] path to the replacement index file
+      #
+      # @return [Object] the value returned by the block
+      #
+      # @yield [repo] the repository instance with the new index active
+      #
+      # @yieldparam repo [Git::Repository] `self`
+      #
+      # @yieldreturn [Object] returned as the method's return value
+      #
+      def with_index(new_index) # :yields: self
+        old_context = @execution_context
+        set_index(new_index, must_exist: false)
+        yield self
+      ensure
+        @execution_context = old_context
+      end
+
+      # Temporarily switches the git index to a new temporary file for the
+      # duration of the block, then removes the file
+      #
+      # The temporary index file does not exist until git creates it on first
+      # write. A unique temporary directory is created to hold the index path,
+      # avoiding the risk of presenting an empty file to git (which git would
+      # reject as a corrupt index). The directory — and any files inside it —
+      # are removed unconditionally after the block exits, even if the block
+      # raises an exception.
+      #
+      # @example Stage changes using a temporary index
+      #   repo.with_temp_index do
+      #     repo.read_tree('HEAD')
+      #     repo.write_tree
+      #   end
+      #
+      # @return [Object] the value returned by the block
+      #
+      # @yield [repo] the repository instance with the temporary index active
+      #
+      # @yieldparam repo [Git::Repository] `self`
+      #
+      # @yieldreturn [Object] returned as the method's return value
+      #
+      def with_temp_index(&) # :yields: self
+        # Use a unique temp directory so the index file path is collision-free
+        # and does not exist until git writes it. An existing empty file would
+        # be treated as a corrupt index by git.
+        temp_dir = Dir.mktmpdir('git-temp-index-')
+        begin
+          with_index(File.join(temp_dir, 'index'), &)
+        ensure
+          FileUtils.remove_entry(temp_dir, true)
+        end
+      end
+
+      # Temporarily switches the git working directory to `work_dir` for the
+      # duration of the block
+      #
+      # Rebuilds the repository execution context to point to the new working
+      # directory, changes the process working directory via `Dir.chdir`, yields
+      # `self`, then unconditionally restores the original execution context —
+      # even if the block raises an exception.
+      #
+      # @example Commit changes from a different worktree path
+      #   repo.with_working('/path/to/worktree') do
+      #     repo.add('.')
+      #     repo.commit('chore: automated update')
+      #   end
+      #
+      # @param work_dir [String, Pathname] path to the replacement working
+      #   directory
+      #
+      # @return [Object] the value returned by the block
+      #
+      # @raise [ArgumentError] if `work_dir` does not exist on disk
+      #
+      # @yield [repo] the repository instance with the new working directory
+      #   active
+      #
+      # @yieldparam repo [Git::Repository] `self`
+      #
+      # @yieldreturn [Object] returned as the method's return value
+      #
+      def with_working(work_dir) # :yields: self
+        old_context = @execution_context
+        set_working(work_dir)
+        Dir.chdir(dir.to_s) { yield self }
+      ensure
+        @execution_context = old_context
+      end
+
+      # Temporarily switches the git working directory to a new temporary
+      # directory for the duration of the block, then removes the directory and
+      # its contents
+      #
+      # The temporary directory is removed unconditionally after the block
+      # exits, even if the block raises an exception.
+      #
+      # @example Write files in an isolated temporary working directory
+      #   repo.with_temp_working do
+      #     File.write('scratch.txt', 'temporary content')
+      #   end
+      #
+      # @return [Object] the value returned by the block
+      #
+      # @yield [repo] the repository instance with the temporary working
+      #   directory active
+      #
+      # @yieldparam repo [Git::Repository] `self`
+      #
+      # @yieldreturn [Object] returned as the method's return value
+      #
+      def with_temp_working(&block) # :yields: self
+        Dir.mktmpdir('temp-workdir') { |temp_dir| with_working(temp_dir, &block) }
+      end
+
+      # Sets the git index to `index_file` and rebuilds the execution context
+      #
+      # By default raises if `index_file` does not exist. Pass `must_exist:
+      # false` to skip the existence check (useful when the index will be
+      # created by git later).
+      #
+      # @example Set the index to a custom path
+      #   repo.set_index('/path/to/custom.index')
+      #
+      # @param index_file [String, Pathname] path to the new index file
+      #
+      # @param check [Boolean, nil] deprecated positional argument — use
+      #   `must_exist:` instead; emits a deprecation warning when non-`nil`
+      #
+      # @param must_exist [Boolean, nil] when `true` (the default), raises
+      #   `ArgumentError` if `index_file` does not exist on disk
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] if `must_exist: true` (the default) and
+      #   `index_file` does not exist
+      #
+      def set_index(index_file, check = nil, must_exist: nil)
+        must_exist = context_helpers_deprecate_check_argument(check, must_exist)
+        new_path = context_helpers_validate_path(index_file, must_exist)
+        context_helpers_rebuild_context(git_index_file: new_path.to_s)
+        nil
+      end
+
+      # Sets the git working directory to `work_dir` and rebuilds the execution
+      # context
+      #
+      # By default raises if `work_dir` does not exist. Pass `must_exist:
+      # false` to skip the existence check.
+      #
+      # @example Set the working directory to a custom path
+      #   repo.set_working('/path/to/working')
+      #
+      # @param work_dir [String, Pathname] path to the new working directory
+      #
+      # @param check [Boolean, nil] deprecated positional argument — use
+      #   `must_exist:` instead; emits a deprecation warning when non-`nil`
+      #
+      # @param must_exist [Boolean, nil] when `true` (the default), raises
+      #   `ArgumentError` if `work_dir` does not exist on disk
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] if `must_exist: true` (the default) and
+      #   `work_dir` does not exist
+      #
+      def set_working(work_dir, check = nil, must_exist: nil)
+        must_exist = context_helpers_deprecate_check_argument(check, must_exist)
+        new_path = context_helpers_validate_path(work_dir, must_exist)
+        context_helpers_rebuild_context(git_work_dir: new_path.to_s)
+        nil
+      end
+
+      private
+
+      # Resolves deprecated `check` argument semantics with `must_exist:`
+      #
+      # @param check [Boolean, nil] deprecated positional existence-check value
+      #
+      # @param must_exist [Boolean, nil] keyword existence-check override
+      #
+      # @return [Boolean] whether path existence must be enforced
+      #
+      def context_helpers_deprecate_check_argument(check, must_exist)
+        if !check.nil? && defined?(Git::Deprecation)
+          Git::Deprecation.warn(
+            'The "check" argument is deprecated and will be removed in v6.0.0. ' \
+            'Use "must_exist:" instead.'
+          )
+        end
+        # Preserve the original Git::Base semantics: when both the deprecated
+        # positional `check` and the new `must_exist:` keyword are given, OR
+        # them so the more restrictive value wins.
+        #
+        # NilClass#| is defined in Ruby: nil | false → false, nil | true → true.
+        # This means single-argument callers (check only, or must_exist: only)
+        # are handled correctly without any nil-special-casing.
+        return true if must_exist.nil? && check.nil?
+
+        must_exist | check
+      end
+
+      # Expands `path` and validates existence when required
+      #
+      # @param path [String, Pathname] path to normalize and validate
+      #
+      # @param must_exist [Boolean] whether the expanded path must already exist
+      #
+      # @return [Pathname] the expanded absolute path
+      #
+      # @raise [ArgumentError] if `must_exist` is `true` and the path does not exist
+      #
+      def context_helpers_validate_path(path, must_exist)
+        Pathname.new(File.expand_path(path.to_s)).tap do |expanded_path|
+          raise ArgumentError, "path does not exist: #{expanded_path}" if must_exist && !expanded_path.exist?
+        end
+      end
+
+      # Rebuilds the repository execution context with selected overrides
+      #
+      # @param overrides [Hash] execution-context attributes to override
+      #
+      # @option overrides [String, nil] :git_index_file replacement index file path
+      #
+      # @option overrides [String, nil] :git_work_dir replacement working directory
+      #   path
+      #
+      # @return [void]
+      #
+      def context_helpers_rebuild_context(**overrides)
+        @execution_context = @execution_context.dup_with(**overrides)
+      end
+    end
+  end
+end