git 5.0.0.beta.2 → 5.0.0.beta.4

data/lib/git/commands/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'git/commands/arguments'
+require 'git/version'
 require 'git/version_constraint'
 
 module Git
@@ -52,11 +53,12 @@ module Git
 
         # Define the command's arguments using the {Arguments} DSL.
         #
-        # @yield the block passed to {Arguments.define}
+        # @return [void]
         #
         # @raise [ArgumentError] if called more than once on the same class
         #
-        # @return [void]
+        # @yield the block passed to {Arguments.define}
+        #
         def arguments(&)
           raise ArgumentError, "arguments already defined for #{name}" if @args_definition
 
@@ -76,9 +78,10 @@ module Git
         #
         # @param range [Range] range of accepted exit status values
         #
+        # @return [void]
+        #
         # @raise [ArgumentError] if range is invalid
         #
-        # @return [void]
         def allow_exit_status(range)
           raise ArgumentError, 'allow_exit_status expects a Range' unless range.is_a?(Range)
           unless range.begin.is_a?(Integer) && range.end.is_a?(Integer)
@@ -96,7 +99,8 @@ module Git
         attr_reader :git_version_constraint
 
         # @!attribute [r] skip_version_validation?
-        # @return [Boolean] whether this command skips version validation
+        #
+        #   @return [Boolean] whether this command skips version validation
         def skip_version_validation? = !!@skip_version_validation
 
         # Declare that this command should skip version validation.
@@ -105,9 +109,10 @@ module Git
         # `git version` command, which cannot validate versions without
         # causing infinite recursion.
         #
+        # @return [void]
+        #
         # @api private
         #
-        # @return [void]
         def skip_version_validation
           @skip_version_validation = true
         end
@@ -129,11 +134,13 @@ module Git
         #   requires_git_version before: '2.50.0'
         #
         # @param min [String, nil] minimum version
+        #
         # @param before [String, nil] upper bound version (exclusive)
         #
+        # @return [void]
+        #
         # @raise [ArgumentError] if version format is invalid or called twice
         #
-        # @return [void]
         def requires_git_version(min = nil, before: nil)
           raise ArgumentError, 'requires_git_version already declared for this class' if @git_version_constraint
 
@@ -145,6 +152,7 @@ module Git
         # Normalize a version constraint to a VersionConstraint
         #
         # @param min [String, nil] minimum version
+        #
         # @param before_version [String, nil] upper bound version
         #
         # @return [Git::VersionConstraint] the normalized constraint
@@ -155,22 +163,43 @@ module Git
           raise ArgumentError, 'requires_git_version requires min or before:' unless min || before_version
 
           min_version = min ? parse_version(min, 'min') : nil
-          before_parsed = before_version ? parse_version(before_version, 'before') : nil
+          before_parsed = before_version ? parse_version(before_version, 'before:') : nil
 
           Git::VersionConstraint.new(min: min_version, before: before_parsed)
         end
 
+        # Parse a version string into a Git version object
+        #
+        # @param version [String] version string to parse
+        #
+        # @param key_name [String] argument name used in validation errors
+        #
+        # @return [Git::Version] the parsed version
+        #
+        # @raise [ArgumentError] if the version format is invalid
+        #
         def parse_version(version, key_name)
           validate_version_format!(version, key_name)
           Git::Version.parse(version)
         end
 
+        # Validate a version string uses the required format
+        #
+        # @param version [Object] value to validate
+        #
+        # @param context [String, nil] argument name included in validation errors
+        #
+        # @return [void]
+        #
+        # @raise [ArgumentError] if the value is not a `major.minor.patch` version string
+        #
         def validate_version_format!(version, context = nil)
           return if version.is_a?(String) && version.match?(/\A\d+\.\d+\.\d+\z/)
 
-          ctx = context ? " for #{context}" : ''
+          subject = context || 'a version'
           raise ArgumentError,
-                "requires_git_version expects a 'major.minor.patch' string#{ctx}, got: #{version.inspect}"
+                "requires_git_version expects #{subject} to be a 'major.minor.patch' version string, " \
+                "got: #{version.inspect}"
         end
       end
 
@@ -202,7 +231,7 @@ module Git
       #
       #   @param kwargs [Hash] keyword arguments forwarded to {Arguments#bind}
       #
-      # @return [Git::CommandLineResult] the result of calling `git`
+      # @return [Git::CommandLine::Result] the result of calling `git`
       #
       # @raise [ArgumentError] if no arguments definition is declared on the command class
       #
@@ -219,10 +248,22 @@ module Git
 
       private
 
+      # Return the argument definition declared by this command class
+      #
+      # @return [Git::Commands::Arguments] the argument definition
+      #
+      # @raise [ArgumentError] if no argument definition is declared
+      #
       def args_definition
         self.class.args_definition || raise(ArgumentError, "arguments not defined for #{self.class.name}")
       end
 
+      # Execute a bound git command through the execution context
+      #
+      # @param bound [Git::Commands::Arguments::Bound] bound command arguments
+      #
+      # @return [Git::CommandLine::Result] the command result
+      #
       def execute_command(bound)
         exec_opts = execution_opts(bound)
 
@@ -233,6 +274,12 @@ module Git
         end
       end
 
+      # Build execution options for a bound command
+      #
+      # @param bound [Git::Commands::Arguments::Bound] bound command arguments
+      #
+      # @return [Hash] execution options for the command line
+      #
       def execution_opts(bound)
         caller_env = bound.execution_options.fetch(:env, {}) || {}
         merged_env = caller_env.merge(env)
@@ -240,6 +287,12 @@ module Git
         merged_env.empty? ? opts : opts.merge(env: merged_env)
       end
 
+      # Build options for captured command output
+      #
+      # @param exec_opts [Hash] execution options for the command line
+      #
+      # @return [Hash] options for captured command output
+      #
       def capturing_opts(exec_opts)
         opts = exec_opts
         opts = opts.merge(normalize: false) unless normalize_captured_stdout?
@@ -297,10 +350,22 @@ module Git
         {}
       end
 
+      # Return the allowed exit status range for this command
+      #
+      # @return [Range] range of accepted exit status values
+      #
       def allowed_exit_status_range
         self.class.allowed_exit_status_range || (0..0)
       end
 
+      # Validate that a command result has an accepted exit status
+      #
+      # @param result [Git::CommandLine::Result] command result to validate
+      #
+      # @return [void]
+      #
+      # @raise [Git::FailedError] if the result exit status is not accepted
+      #
       def validate_exit_status!(result)
         raise Git::FailedError, result unless allowed_exit_status_range.include?(result.status.exitstatus)
       end
@@ -313,6 +378,12 @@ module Git
       #
       # Floor check always runs first and fails fast.
       #
+      # @param exec_opts [Hash] execution options used to query git version
+      #
+      # @return [void]
+      #
+      # @raise [Git::VersionError] if the installed git version is unsupported
+      #
       def validate_version!(exec_opts = {})
         return if self.class.skip_version_validation?
 
@@ -325,6 +396,14 @@ module Git
         validate_class_version_constraint!(actual_version)
       end
 
+      # Validate that git satisfies the gem-wide minimum version
+      #
+      # @param actual_version [Git::Version] installed git version
+      #
+      # @return [void]
+      #
+      # @raise [Git::VersionError] if the installed git version is too old
+      #
       def validate_floor_version!(actual_version)
         return if actual_version >= Git::MINIMUM_GIT_VERSION
 
@@ -335,6 +414,14 @@ module Git
         )
       end
 
+      # Validate that git satisfies this command class's version constraint
+      #
+      # @param actual_version [Git::Version] installed git version
+      #
+      # @return [void]
+      #
+      # @raise [Git::VersionError] if the installed git version is unsupported
+      #
       def validate_class_version_constraint!(actual_version)
         constraint = self.class.git_version_constraint
         return unless constraint
@@ -365,7 +452,7 @@ module Git
       # when `--batch-all-objects` is used and git enumerates objects itself).
       #
       # @example Feed bound object names to a git batch command
-      #   bound = args_definition.bind(*, **)
+      #   bound = args_definition.bind(*args, **kwargs)
       #   stdin_content = Array(bound.objects).map { |object| "#{object}\n" }.join
       #   with_stdin(stdin_content) do |reader|
       #     @execution_context.command_capturing('cat-file', '--batch-check', in: reader, raise_on_failure: false)
@@ -373,10 +460,14 @@ module Git
       #
       # @param content [String] text to write to the process's stdin
       #
-      # @yield [reader [IO]] the read end of the pipe; valid only for the
+      # @return [Object] the value returned by the block
+      #
+      # @yield [reader] the read end of the pipe
+      #
+      # @yieldparam reader [IO] the read end of the pipe; valid only for the
       #   duration of the block
       #
-      # @return [Object] the value returned by the block
+      # @yieldreturn [Object] the block's return value, which becomes the method's return value
       #
       def with_stdin(content)
         reader, writer = IO.pipe
@@ -390,6 +481,13 @@ module Git
       # Spawns a thread that writes content to writer then closes it.
       # Rescues EPIPE/IOError so the thread exits cleanly when the subprocess
       # closes its stdin early (e.g. on error exit before reading all input).
+      #
+      # @param content [String] text to write to the pipe
+      #
+      # @param writer [IO] write end of the pipe
+      #
+      # @return [Thread] thread writing content to the pipe
+      #
       def start_stdin_writer(content, writer)
         Thread.new do
           writer.write(content) unless content.empty?

data/lib/git/commands/branch/copy.rb

@@ -47,47 +47,55 @@ module Git
           operand :new_branch, required: true
         end
 
-        # @!method call(*, **)
+        # Executes the git branch --copy command to copy a branch
         #
-        #   Execute the git branch --copy command to copy a branch
+        # @overload call(new_branch, **options)
         #
-        #   @overload call(new_branch, **options)
+        #   Copies the current branch to the new_branch
         #
-        #     Copies the current branch to the new_branch
+        #   @param new_branch [String] the new name for the copied branch
         #
-        #     @param new_branch [String] the new name for the copied branch
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, nil] :force (nil) allow copying even if new_branch already
+        #     exists
         #
-        #     @option options [Boolean, nil] :force (nil) allow copying even if new_branch already exists
+        #     Alias: :f
         #
-        #       Alias: :f
+        #   @return [Git::CommandLine::Result] the result of calling `git branch --copy`
         #
-        #     @return [Git::CommandLineResult] the result of calling `git branch --copy`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #   @api public
         #
-        #   @overload call(old_branch, new_branch, **options)
+        # @overload call(old_branch, new_branch, **options)
         #
-        #     Copies old_branch to new_branch
+        #   Copies old_branch to new_branch
         #
-        #     @param old_branch [String] branch to copy from
+        #   @param old_branch [String] branch to copy from
         #
-        #     @param new_branch [String] the new name for the copied branch
+        #   @param new_branch [String] the new name for the copied branch
         #
-        #     @param options [Hash] command options
+        #   @param options [Hash] command options
         #
-        #     @option options [Boolean, nil] :force (nil) allow copying even if new_branch already exists
+        #   @option options [Boolean, nil] :force (nil) allow copying even if new_branch already
+        #     exists
         #
-        #       Alias: :f
+        #     Alias: :f
         #
-        #     @return [Git::CommandLineResult] the result of calling `git branch --copy`
+        #   @return [Git::CommandLine::Result] the result of calling `git branch --copy`
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
+        #
+        def call(*, **)
+          super
+        end
       end
     end
   end

data/lib/git/commands/branch/create.rb

@@ -55,118 +55,122 @@ module Git
           operand :start_point
         end
 
-        # @!method call(*, **)
+        # @overload call(branch_name, **options)
         #
-        #   @overload call(branch_name, **options)
+        #   Create a new branch from the current HEAD
         #
-        #     Create a new branch from the current HEAD
+        #   @param branch_name [String] the name of the branch to create
         #
-        #     @param branch_name [String] the name of the branch to create
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, String, nil] :track (nil) configure upstream tracking for
+        #     the new branch
         #
-        #     @option options [Boolean, String, nil] :track (nil)
-        #       configure upstream tracking for the new branch
+        #     - `true`: Set up tracking using the start-point branch itself (`--track`)
+        #     - `'direct'`: Same as `true`, explicitly use start-point as upstream (`--track=direct`)
+        #     - `'inherit'`: Copy upstream configuration from start-point branch (`--track=inherit`)
         #
-        #       - `true`: Set up tracking using the start-point branch itself (`--track`)
-        #       - `'direct'`: Same as `true`, explicitly use start-point as upstream (`--track=direct`)
-        #       - `'inherit'`: Copy upstream configuration from start-point branch (`--track=inherit`)
+        #     Alias: :t
         #
-        #       Alias: :t
+        #   @option options [Boolean, nil] :no_track (nil) do not set up tracking even if
+        #     `branch.autoSetupMerge` is set (`--no-track`)
         #
-        #     @option options [Boolean, nil] :no_track (nil)
-        #       do not set up tracking even if `branch.autoSetupMerge` is set (`--no-track`)
+        #   @option options [Boolean, nil] :force (nil) reset the branch to start point even if
+        #     it already exists
         #
-        #     @option options [Boolean, nil] :force (nil)
-        #       reset the branch to start point even if it already exists
+        #     Without this, git branch refuses to change an existing branch
         #
-        #       Without this, git branch refuses to change an existing branch.
+        #     Alias: :f
         #
-        #       Alias: :f
+        #   @option options [Boolean, nil] :recurse_submodules (nil) create the branch in the
+        #     superproject and all submodules
         #
-        #     @option options [Boolean, nil] :recurse_submodules (nil)
-        #       create the branch in the superproject and all submodules
+        #     This is an experimental feature
         #
-        #       This is an experimental feature.
+        #   @option options [Boolean, nil] :quiet (nil) suppress informational messages
         #
-        #     @option options [Boolean, nil] :quiet (nil)
-        #       suppress informational messages
+        #     Alias: :q
         #
-        #       Alias: :q
+        #   @option options [Boolean, nil] :create_reflog (nil) create the branch's reflog
+        #     (`--create-reflog`)
         #
-        #     @option options [Boolean, nil] :create_reflog (nil)
-        #       create the branch's reflog (`--create-reflog`)
+        #     Enables date-based sha1 expressions such as `branch@\\{yesterday}`
+        #     In non-bare repositories, reflogs are usually enabled by default via
+        #     `core.logAllRefUpdates`
         #
-        #       Enables date-based sha1 expressions such as `branch@{yesterday}`.
-        #       In non-bare repositories, reflogs are usually enabled by default
-        #       via `core.logAllRefUpdates`.
+        #   @option options [Boolean, nil] :no_create_reflog (nil) forcibly disable the
+        #     branch's reflog (`--no-create-reflog`)
         #
-        #     @option options [Boolean, nil] :no_create_reflog (nil)
-        #       forcibly disable the branch's reflog (`--no-create-reflog`)
+        #   @return [Git::CommandLine::Result] the result of calling `git branch`
         #
-        #     @return [Git::CommandLineResult] the result of calling `git branch`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #   @api public
         #
-        #   @overload call(branch_name, start_point, **options)
+        # @overload call(branch_name, start_point, **options)
         #
-        #     Create a new branch from the specified start point
+        #   Create a new branch from the specified start point
         #
-        #     @param branch_name [String] the name of the branch to create
+        #   @param branch_name [String] the name of the branch to create
         #
-        #     @param start_point [String, nil] the commit, branch, or tag to
-        #       start the new branch from
+        #   @param start_point [String, nil] the commit, branch, or tag to
+        #     start the new branch from
         #
-        #       Can also use `<rev-A>...<rev-B>` syntax for merge base.
+        #     Can also use `<rev-A>...<rev-B>` syntax for merge base
         #
-        #     @param options [Hash] command options
+        #   @param options [Hash] command options
         #
-        #     @option options [Boolean, String, nil] :track (nil)
-        #       configure upstream tracking for the new branch
+        #   @option options [Boolean, String, nil] :track (nil) configure upstream tracking for
+        #     the new branch
         #
-        #       - `true`: Set up tracking using the start-point branch itself (`--track`)
-        #       - `'direct'`: Same as `true`, explicitly use start-point as upstream (`--track=direct`)
-        #       - `'inherit'`: Copy upstream configuration from start-point branch (`--track=inherit`)
+        #     - `true`: Set up tracking using the start-point branch itself (`--track`)
+        #     - `'direct'`: Same as `true`, explicitly use start-point as upstream (`--track=direct`)
+        #     - `'inherit'`: Copy upstream configuration from start-point branch (`--track=inherit`)
         #
-        #       Alias: :t
+        #     Alias: :t
         #
-        #     @option options [Boolean, nil] :no_track (nil)
-        #       do not set up tracking even if `branch.autoSetupMerge` is set (`--no-track`)
+        #   @option options [Boolean, nil] :no_track (nil) do not set up tracking even if
+        #     `branch.autoSetupMerge` is set (`--no-track`)
         #
-        #     @option options [Boolean, nil] :force (nil)
-        #       reset the branch to start point even if it already exists
+        #   @option options [Boolean, nil] :force (nil) reset the branch to start point even if
+        #     it already exists
         #
-        #       Without this, git branch refuses to change an existing branch.
+        #     Without this, git branch refuses to change an existing branch
         #
-        #       Alias: :f
+        #     Alias: :f
         #
-        #     @option options [Boolean, nil] :recurse_submodules (nil)
-        #       create the branch in the superproject and all submodules
+        #   @option options [Boolean, nil] :recurse_submodules (nil) create the branch in the
+        #     superproject and all submodules
         #
-        #       This is an experimental feature.
+        #     This is an experimental feature
         #
-        #     @option options [Boolean, nil] :quiet (nil)
-        #       suppress informational messages
+        #   @option options [Boolean, nil] :quiet (nil) suppress informational messages
         #
-        #       Alias: :q
+        #     Alias: :q
         #
-        #     @option options [Boolean, nil] :create_reflog (nil)
-        #       create the branch's reflog (`--create-reflog`)
+        #   @option options [Boolean, nil] :create_reflog (nil) create the branch's reflog
+        #     (`--create-reflog`)
         #
-        #       Enables date-based sha1 expressions such as `branch@{yesterday}`.
-        #       In non-bare repositories, reflogs are usually enabled by default
-        #       via `core.logAllRefUpdates`.
+        #     Enables date-based sha1 expressions such as `branch@\\{yesterday}`
+        #     In non-bare repositories, reflogs are usually enabled by default via
+        #     `core.logAllRefUpdates`
         #
-        #     @option options [Boolean, nil] :no_create_reflog (nil)
-        #       forcibly disable the branch's reflog (`--no-create-reflog`)
+        #   @option options [Boolean, nil] :no_create_reflog (nil) forcibly disable the
+        #     branch's reflog (`--no-create-reflog`)
         #
-        #     @return [Git::CommandLineResult] the result of calling `git branch`
+        #   @return [Git::CommandLine::Result] the result of calling `git branch`
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
+        #
+        def call(*, **)
+          super
+        end
       end
     end
   end

data/lib/git/commands/branch/delete.rb

@@ -46,34 +46,42 @@ module Git
         # git branch --delete exits 1 when one or more branches cannot be deleted
         allow_exit_status 0..1
 
-        # @!method call(*, **)
+        # Executes the git branch --delete command to delete branches
         #
-        #   Execute the git branch --delete command to delete branches
+        # @overload call(*branch_name, **options)
         #
-        #   @overload call(*branch_name, **options)
+        #   @param branch_name [Array<String>] one or more branch names to delete
         #
-        #     @param branch_name [Array<String>] One or more branch names to delete.
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, nil] :force (nil) allow deleting the branch irrespective of
+        #     its merged status, or whether it even points to a valid commit
         #
-        #     @option options [Boolean, nil] :force (nil) allow deleting the branch irrespective of its merged
-        #       status, or whether it even points to a valid commit. This is equivalent
-        #       to the `-D` shortcut (`--delete --force`).
+        #     Equivalent to the `-D` shortcut (`--delete --force`)
         #
-        #       Alias: :f
+        #     Alias: :f
         #
-        #     @option options [Boolean, nil] :remotes (nil) delete remote-tracking branches. Use this together
-        #       with `--delete` to delete remote-tracking branches. Note that this only
-        #       makes sense if the remote-tracking branches no longer exist in the remote
-        #       repository or if `git fetch` was configured not to fetch them again.
+        #   @option options [Boolean, nil] :remotes (nil) delete remote-tracking branches
         #
-        #       Alias: :r
+        #     Use this together with `--delete` to remove remote-tracking branches that no
+        #     longer exist in the remote repository, or if `git fetch` was configured not to
+        #     fetch them again
         #
-        #     @return [Git::CommandLineResult] the result of calling `git branch --delete`
+        #     Alias: :r
         #
-        #     @raise [ArgumentError] if no branch names are provided
+        #   @return [Git::CommandLine::Result] the result of calling `git branch --delete`
         #
-        #     @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
+        #   @raise [ArgumentError] if no branch names are provided
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
+        #
+        #   @api public
+        #
+        def call(*, **)
+          super
+        end
       end
     end
   end