git 4.3.2 → 5.0.0.beta.1

data/lib/git/repository/committing.rb

@@ -0,0 +1,191 @@
+# 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 public
+    #
+    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
+      #
+      # @overload commit(message = nil, **options)
+      #
+      #   @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 options [Hash] options for the commit command
+      #
+      #   @option options [Boolean, nil] :all (nil) automatically stage modified and
+      #     deleted files before committing
+      #
+      #   @option options [Boolean, nil] :amend (nil) replace the tip of the current
+      #     branch with a new commit
+      #
+      #   @option options [Boolean, nil] :allow_empty (nil) allow committing with no
+      #     changes
+      #
+      #   @option options [Boolean, nil] :allow_empty_message (nil) allow committing
+      #     with an empty message
+      #
+      #   @option options [String] :author (nil) override the commit author in
+      #     `A U Thor <author@example.com>` format
+      #
+      #   @option options [String] :date (nil) override the author date
+      #
+      #   @option options [Boolean, nil] :gpg_sign (nil) GPG-sign the commit
+      #
+      #   @option options [Boolean, nil] :no_gpg_sign (nil) disable GPG signing
+      #
+      #   @option options [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 = nil, **opts)
+        if opts.key?(:add_all)
+          Git::Deprecation.warn('The :add_all option for #commit is deprecated, use :all instead')
+          opts[:all] = opts.delete(:add_all)
+        end
+
+        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 `commit(message, all: true, **options)`.
+      #
+      # @overload commit_all(message, **options)
+      #
+      #   @example Commit all changes with a message
+      #     repo.commit_all('Update everything')
+      #
+      #   @param message [String] the commit message
+      #
+      #   @param options [Hash] additional options forwarded to {#commit}
+      #
+      #   @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(*, **)
+        commit(*, 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`.
+      #
+      # @overload commit_tree(tree, **options)
+      #
+      #   @example Commit a tree with a parent
+      #     repo.commit_tree('deadbeef', message: 'snapshot', parent: 'HEAD')
+      #
+      #   @param tree [String] the tree SHA to commit
+      #
+      #   @param options [Hash] options for the commit-tree command
+      #
+      #   @option options [String] :m (nil) the commit message (short form)
+      #
+      #   @option options [String] :message (nil) the commit message (normalized
+      #     to `:m` before passing to the command)
+      #
+      #   @option options [String, Array<String>] :p (nil) parent commit SHA(s)
+      #
+      #   @option options [String] :parent (nil) a single parent commit SHA
+      #     (normalized to `:p`)
+      #
+      #   @option options [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, **opts)
+        SharedPrivate.assert_valid_opts!(COMMIT_TREE_ALLOWED_OPTS, **opts)
+
+        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.
+      #
+      # @overload write_and_commit_tree(**options)
+      #
+      #   @example Commit the current index as a snapshot
+      #     commit_sha = repo.write_and_commit_tree(message: 'snapshot')
+      #
+      #   @param options [Hash] options forwarded to {#commit_tree}
+      #
+      #   @return [String] the SHA of the newly created commit object
+      #
+      #   @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def write_and_commit_tree(**)
+        commit_tree(write_tree, **)
+      end
+    end
+  end
+end

data/lib/git/repository/configuring.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'git/commands/config_option_syntax'
+require 'git/repository/shared_private'
+
+module Git
+  class Repository
+    # Facade methods for reading and writing git configuration
+    #
+    # Provides the {#config} method, which dispatches to read a single entry,
+    # list all entries, or write a value depending on the arguments supplied.
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api public
+    #
+    module Configuring
+      # Option keys accepted by {#config} when writing a value
+      CONFIG_SET_ALLOWED_OPTS = %i[file].freeze
+      private_constant :CONFIG_SET_ALLOWED_OPTS
+
+      # Read or write a git configuration entry
+      #
+      # Dispatches to one of three modes depending on the arguments supplied:
+      #
+      # * **List** — `config()` returns all visible config entries as a `Hash`.
+      # * **Get** — `config(name)` returns the value for a single key as a `String`.
+      # * **Set** — `config(name, value)` writes a value and returns the raw
+      #   command result.
+      #
+      # @overload config
+      #
+      #   @example List all config entries
+      #     repo.config #=> { "user.name" => "Alice", "core.bare" => "false" }
+      #
+      #   @return [Hash{String => String}] all visible config entries, keyed by
+      #     their full dotted key names (e.g. `"user.name"`)
+      #
+      # @overload config(name)
+      #
+      #   @example Read the committer name from config
+      #     repo.config('user.name') #=> "Alice"
+      #
+      #   @param name [String] the dotted config key to look up (e.g.
+      #     `"user.name"`)
+      #
+      #   @return [String] the value of the config entry
+      #
+      # @overload config(name, value, options = {})
+      #
+      #   @example Set the committer name in local config
+      #     repo.config('user.name', 'Alice')
+      #
+      #   @example Write a value to a custom config file
+      #     repo.config('user.name', 'Alice', file: '/path/to/custom/config')
+      #
+      #   @param name [String] the dotted config key to write (e.g.
+      #     `"user.name"`)
+      #
+      #   @param value [String] the value to assign
+      #
+      #   @param options [Hash] options for the set operation
+      #
+      #   @option options [String, nil] :file (nil) path to a custom config file
+      #     to write to instead of the repository's default `.git/config`
+      #
+      #   @return [Git::CommandLineResult] the raw result of
+      #     `git config <name> <value>`
+      #
+      #   @raise [ArgumentError] if unsupported options are provided
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      def config(name = nil, value = nil, options = {})
+        if name && value
+          Private.config_set(@execution_context, name, value, **options)
+        elsif name
+          Private.config_get(@execution_context, name)
+        else
+          Private.config_list(@execution_context)
+        end
+      end
+
+      # Private helpers local to {Git::Repository::Configuring}
+      #
+      # @api private
+      #
+      module Private
+        module_function
+
+        # Set a config value by key name
+        #
+        # @overload config_set(execution_context, name, value, **options)
+        #
+        #   @param execution_context [Git::ExecutionContext] the execution context
+        #
+        #   @param name [String] the dotted config key to write (e.g. `"user.name"`)
+        #
+        #   @param value [String] the value to assign
+        #
+        #   @param options [Hash] keyword options forwarded to the command
+        #
+        #   @option options [String, nil] :file (nil) path to a custom config file
+        #     to write to instead of the repository's default `.git/config`
+        #
+        #   @return [Git::CommandLineResult] the raw result of
+        #     `git config <name> <value>`
+        #
+        # @raise [ArgumentError] if unsupported options are provided
+        #
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        def config_set(execution_context, name, value, **)
+          SharedPrivate.assert_valid_opts!(CONFIG_SET_ALLOWED_OPTS, **)
+          Git::Commands::ConfigOptionSyntax::Set.new(execution_context).call(name, value, **)
+        end
+
+        # Retrieve a config value by key name
+        #
+        # @param execution_context [Git::ExecutionContext] the execution context
+        #
+        # @param name [String] the dotted config key to look up (e.g. `"user.name"`)
+        #
+        # @return [String] the value of the config entry
+        #
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        def config_get(execution_context, name)
+          result = Git::Commands::ConfigOptionSyntax::Get.new(execution_context).call(name)
+          raise Git::FailedError, result if result.status.exitstatus != 0
+
+          result.stdout
+        end
+
+        # Retrieve all config entries as a hash
+        #
+        # @param execution_context [Git::ExecutionContext] the execution context
+        #
+        # @return [Hash{String => String}] all config entries, keyed by their full
+        #   dotted key names (e.g. `"user.name"`)
+        #
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        def config_list(execution_context)
+          lines = Git::Commands::ConfigOptionSyntax::List.new(execution_context).call.stdout.split("\n")
+          lines.each_with_object({}) do |line, hsh|
+            key, value = line.split('=', 2)
+            hsh[key] = value || ''
+          end
+        end
+      end
+
+      private_constant :Private
+    end
+  end
+end