git 5.0.0.beta.3 → 5.0.0.beta.4

data/lib/git/repository/logging.rb

@@ -10,9 +10,13 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module Logging
+      # Allowed option keys for {#full_log_commits}
+      #
+      # @return [Array<Symbol>] the supported option keys
+      #
       FULL_LOG_COMMITS_ALLOWED_OPTS = %i[
         count all cherry since until grep author between object path_limiter skip merges
       ].freeze
@@ -20,56 +24,59 @@ module Git
 
       # Returns commits within the given revision range
       #
-      # @overload full_log_commits(opts = {})
+      # @example Return commits from all refs
+      #   repo.full_log_commits(all: true).first['sha']
+      #   #=> "a1b2c3d4..."
       #
-      #   @example Return commits from all refs
-      #     repo.full_log_commits(all: true).first['sha']
-      #     #=> "a1b2c3d4..."
+      # @example Return commits between two revisions
+      #   repo.full_log_commits(between: ['v1.0.0', 'HEAD']).map { |c| c['sha'] }
+      #   #=> ["d4e5f6...", "a1b2c3..."]
       #
-      #   @example Return commits between two revisions
-      #     repo.full_log_commits(between: ['v1.0.0', 'HEAD']).map { |c| c['sha'] }
-      #     #=> ["d4e5f6...", "a1b2c3..."]
+      # @param opts [Hash] options for the log query
       #
-      #   @param opts [Hash] options for the log query
+      # @option opts [Integer, nil] :count (nil) maximum number of commits to return
       #
-      #   @option opts [Integer, nil] :count (nil) maximum number of commits to return
+      # @option opts [Boolean, nil] :all (nil) include commits reachable from any ref
       #
-      #   @option opts [Boolean, nil] :all (nil) include commits reachable from any ref
+      # @option opts [Boolean, nil] :cherry (nil) omit commits equivalent to
+      #   cherry-picked commits
       #
-      #   @option opts [Boolean, nil] :cherry (nil) omit commits equivalent to cherry-picked commits
+      # @option opts [String] :since (nil) include commits newer than this date expression
       #
-      #   @option opts [String] :since (nil) include commits newer than this date expression
+      # @option opts [String] :until (nil) include commits older than this date expression
       #
-      #   @option opts [String] :until (nil) include commits older than this date expression
+      # @option opts [String] :grep (nil) only include commits whose message matches
+      #   this pattern
       #
-      #   @option opts [String] :grep (nil) only include commits whose message matches this pattern
+      # @option opts [String] :author (nil) only include commits whose author matches
+      #   this pattern
       #
-      #   @option opts [String] :author (nil) only include commits whose author matches this pattern
+      # @option opts [Array(String, String), nil] :between (nil) revision range as
+      #   two commit-ish values
       #
-      #   @option opts [Array<String>] :between (nil) revision range as two commit-ish values
+      #   When both `:between` and `:object` are provided, `:between` takes precedence.
       #
-      #     When both `:between` and `:object` are provided, `:between` takes precedence.
+      # @option opts [String] :object (nil) single revision range expression for
+      #   `git log`
       #
-      #   @option opts [String] :object (nil) single revision range expression for git log
+      #   Ignored when `:between` is provided.
       #
-      #     Ignored when `:between` is provided.
+      # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
+      #   only include commits that impact files from the specified path(s)
       #
-      #   @option opts [String, Pathname, Array<String, Pathname>] :path_limiter (nil)
-      #     only include commits that impact files from the specified path(s)
+      # @option opts [Integer, nil] :skip (nil) skip this many commits before output
       #
-      #   @option opts [Integer] :skip (nil) skip this many commits before output
+      # @option opts [Boolean, nil] :merges (nil) include only merge commits
       #
-      #   @option opts [Boolean, nil] :merges (nil) include only merge commits
+      # @return [Array<Hash>] the parsed raw log output for each commit
       #
-      #   @return [Array<Hash>] the parsed raw log output for each commit
+      # @raise [ArgumentError] if unsupported options are provided
       #
-      #   @raise [ArgumentError] if unsupported options are provided
+      # @raise [ArgumentError] if `:count` is not an Integer
       #
-      #   @raise [ArgumentError] if `:count` is not an Integer
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      #   @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      #   @see https://git-scm.com/docs/git-log git-log
+      # @see https://git-scm.com/docs/git-log git-log
       #
       def full_log_commits(opts = {})
         SharedPrivate.assert_valid_opts!(FULL_LOG_COMMITS_ALLOWED_OPTS, **opts)
@@ -106,12 +113,35 @@ module Git
       module Private
         module_function
 
+        # Validates the :count log option
+        #
+        # @param opts [Hash] the log options
+        #
+        # @option opts [Integer, nil] :count (nil) the maximum number of commits to
+        #   return
+        #
+        # @return [void]
+        #
+        # @raise [ArgumentError] if the log count option is not an Integer
+        #
         def validate_log_count_option!(opts)
           return if opts[:count].nil? || opts[:count].is_a?(Integer)
 
           raise ArgumentError, "The log count option must be an Integer but was #{opts[:count].inspect}"
         end
 
+        # Validates the :between log option
+        #
+        # @param opts [Hash] the log options
+        #
+        # @option opts [Array(String, String), nil] :between (nil) the two-commit
+        #   revision range to validate
+        #
+        # @return [void]
+        #
+        # @raise [ArgumentError] if the :between option is not an Array with exactly
+        #   two non-nil values
+        #
         def validate_log_between_option!(opts)
           between = opts[:between]
           return if between.nil?
@@ -121,6 +151,17 @@ module Git
                 "The log between option must be an Array with exactly two non-nil values but was #{between.inspect}"
         end
 
+        # Builds positional revision arguments for `git log`
+        #
+        # @param opts [Hash] the log options
+        #
+        # @option opts [Array(String, String), nil] :between (nil) a two-revision
+        #   range where index `0` is the start and index `1` is the end
+        #
+        # @option opts [String, nil] :object (nil) a single revision range expression
+        #
+        # @return [Array<String>] zero or one positional revision arguments
+        #
         def log_revision_range_args(opts)
           if opts[:between]
             ["#{opts[:between][0]}..#{opts[:between][1]}"]
@@ -131,6 +172,40 @@ module Git
           end
         end
 
+        # Builds keyword options passed to {Git::Commands::Log#call}
+        #
+        # @param opts [Hash] the log options
+        #
+        # @param extra [Hash] additional keyword options merged into the call options
+        #
+        # @option opts [Boolean, nil] :all (nil) include commits reachable from any ref
+        #
+        # @option opts [Boolean, nil] :cherry (nil) omit commits equivalent to
+        #   cherry-picked commits
+        #
+        # @option opts [String, nil] :since (nil) include commits newer than this date
+        #   expression
+        #
+        # @option opts [String, nil] :until (nil) include commits older than this date
+        #   expression
+        #
+        # @option opts [String, nil] :grep (nil) only include commits whose message
+        #   matches this pattern
+        #
+        # @option opts [String, nil] :author (nil) only include commits whose author
+        #   matches this pattern
+        #
+        # @option opts [Integer, nil] :count (nil) maximum number of commits to return
+        #
+        # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
+        #   only include commits that impact files from the specified path(s)
+        #
+        # @option extra [Integer, nil] :skip (nil) skip this many commits before output
+        #
+        # @option extra [Boolean, nil] :merges (nil) include only merge commits
+        #
+        # @return [Hash] keyword options for {Git::Commands::Log#call}
+        #
         def log_base_call_options(opts, extra = {})
           {
             all: opts[:all],
@@ -144,6 +219,18 @@ module Git
           }.merge(extra).compact
         end
 
+        # Executes git log and parses the raw output
+        #
+        # @param execution_context [Git::ExecutionContext] the execution context
+        #
+        # @param revision_range_args [Array<String>] positional revision range arguments
+        #
+        # @param call_opts [Hash] keyword options for {Git::Commands::Log#call}
+        #
+        # @return [Array<Hash>] parsed commits from the command output
+        #
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
         def run_log_command(execution_context, revision_range_args, call_opts)
           log_or_empty_on_unborn do
             result = Git::Commands::Log.new(execution_context).call(
@@ -156,6 +243,16 @@ module Git
           end
         end
 
+        # Returns an empty result when the repository has no commits yet
+        #
+        # @return [Array<Hash>] parsed commits or an empty array for unborn repositories
+        #
+        # @raise [Git::FailedError] if git fails for a reason other than unborn history
+        #
+        # @yield [] runs the wrapped log command
+        #
+        # @yieldreturn [Array<Hash>] the parsed commits from the wrapped command
+        #
         def log_or_empty_on_unborn
           yield
         rescue Git::FailedError => e
@@ -170,6 +267,12 @@ module Git
         # @api private
         #
         class RawLogParser
+          # Initializes a parser for raw git log output lines
+          #
+          # @param lines [Array<String>] raw output lines from `git log --pretty=raw`
+          #
+          # @return [void]
+          #
           def initialize(lines)
             @lines = lines
             @commits = []
@@ -190,6 +293,12 @@ module Git
 
           private
 
+          # Routes a raw line to message or metadata parsing
+          #
+          # @param line [String] the current raw log output line
+          #
+          # @return [void]
+          #
           def process_line(line)
             if line.empty?
               @in_message = !@in_message
@@ -201,10 +310,22 @@ module Git
             @in_message ? process_message_line(line) : process_metadata_line(line)
           end
 
+          # Appends a commit message line to the current commit buffer
+          #
+          # @param line [String] an indented message line from raw output
+          #
+          # @return [void]
+          #
           def process_message_line(line)
             @current_commit['message'] << "#{line[4..]}\n"
           end
 
+          # Parses metadata lines and multi-line metadata continuations
+          #
+          # @param line [String] a metadata line from raw output
+          #
+          # @return [void]
+          #
           def process_metadata_line(line)
             if line.start_with?(' ') && @last_metadata_key
               @current_commit[@last_metadata_key] << "\n#{line[1..]}"
@@ -217,6 +338,14 @@ module Git
             dispatch_metadata_key(key, value)
           end
 
+          # Applies a metadata key/value pair to the current commit
+          #
+          # @param key [String] the metadata key from the raw log line
+          #
+          # @param value [String] the parsed metadata value
+          #
+          # @return [void]
+          #
           def dispatch_metadata_key(key, value)
             case key
             when 'commit'
@@ -229,12 +358,22 @@ module Git
             end
           end
 
+          # Starts a new commit record in the parser state
+          #
+          # @param sha [String] the commit SHA for the new record
+          #
+          # @return [void]
+          #
           def start_new_commit(sha)
             finalize_commit
             @current_commit = { 'sha' => sha, 'message' => +'', 'parent' => [] }
             @last_metadata_key = nil
           end
 
+          # Appends the current commit to the parsed results when present
+          #
+          # @return [void]
+          #
           def finalize_commit
             @commits << @current_commit if @current_commit
           end

data/lib/git/repository/maintenance.rb

@@ -12,7 +12,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module Maintenance
       # Repack loose objects into pack files

data/lib/git/repository/merging.rb

@@ -15,7 +15,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module Merging
       # Option keys accepted by {#merge}
@@ -333,14 +333,14 @@ module Git
         #
         # @param stage [Integer] git stage index (2 = ours, 3 = theirs)
         #
+        # @return [void]
+        #
         # @yield [f] yields the open Tempfile containing the staged content
         #
         # @yieldparam f [Tempfile] open IO object for the staged content
         #
         # @yieldreturn [void]
         #
-        # @return [void]
-        #
         # @api private
         #
         def write_staged_file(execution_context, file_path, stage)

data/lib/git/repository/object_operations.rb

@@ -27,7 +27,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module ObjectOperations # rubocop:disable Metrics/ModuleLength
       # Returns the raw content of a git object, or streams it into a tempfile
@@ -854,7 +854,7 @@ module Git
       #
       #   @param name [String] the name of the tag to delete
       #
-      #   @param delete_options [{ d: true }, { delete: true }] deletion options;
+      #   @param delete_options [Hash{Symbol => Boolean}] deletion options;
       #     only `:d` or `:delete` (set to `true`) is accepted — no other keys
       #     and no `target` argument may be combined with this form
       #
@@ -885,8 +885,6 @@ module Git
         tag(name)
       end
 
-      # @deprecated Use {#tag_add} instead.
-      #
       # @overload add_tag(name, options = {})
       #
       #   @param name [String] the name of the tag to create
@@ -912,12 +910,14 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      def add_tag(name, *options)
+      # @deprecated Use {#tag_add} instead
+      #
+      def add_tag(name, *)
         Git::Deprecation.warn(
           'Git::Repository#add_tag is deprecated and will be removed in v6.0.0. ' \
           'Use Git::Repository#tag_add instead.'
         )
-        tag_add(name, *options)
+        tag_add(name, *)
       end
 
       # Delete a tag
@@ -938,14 +938,14 @@ module Git
         result.stdout
       end
 
-      # @deprecated Use {#tag_delete} instead.
-      #
       # @param name [String] the name of the tag to delete
       #
       # @return [String] git's stdout from the delete
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @deprecated Use {#tag_delete} instead
+      #
       def delete_tag(name)
         Git::Deprecation.warn(
           'Git::Repository#delete_tag is deprecated and will be removed in v6.0.0. ' \
@@ -966,6 +966,26 @@ module Git
         #
         # @param opts [Hash] the tag-creation options
         #
+        # @option opts [Boolean, nil] :annotate request an annotated tag
+        #
+        # @option opts [Boolean, nil] :a alias for `:annotate`
+        #
+        # @option opts [Boolean, nil] :sign request a signed tag
+        #
+        # @option opts [Boolean, nil] :s alias for `:sign`
+        #
+        # @option opts [String] :local_user key id used when signing
+        #
+        # @option opts [String] :u alias for `:local_user`
+        #
+        # @option opts [String] :message tag message text
+        #
+        # @option opts [String] :m alias for `:message`
+        #
+        # @option opts [String] :file path to a tag message file
+        #
+        # @option opts [String] :F alias for `:file`
+        #
         # @return [void]
         #
         # @raise [ArgumentError] when an annotated or signed tag is requested
@@ -986,10 +1006,18 @@ module Git
         # ArgumentError if a target or incompatible options are also supplied.
         #
         # @param facade [ObjectOperations] the calling facade instance
+        #
         # @param name [String] tag name
+        #
         # @param target [String, nil] target argument (must be nil)
+        #
         # @param opts [Hash] options hash (must contain only :d/:delete)
         #
+        # @option opts [Boolean] :d (true) request deletion in the deprecated
+        #   `tag_add` form
+        #
+        # @option opts [Boolean] :delete (true) alias for `:d`
+        #
         # @return [String] stdout from tag_delete
         #
         # @api private
@@ -1007,6 +1035,20 @@ module Git
           facade.tag_delete(name)
         end
 
+        # Returns the direct SHA for a tag reference
+        #
+        # Returns the hash from `refs/tags/<name>` only. Returns an empty string
+        # when the ref does not exist.
+        #
+        # @param execution_context [Git::ExecutionContext] for running
+        #   `git show-ref`
+        #
+        # @param tag_name [String] tag name without the `refs/tags/` prefix
+        #
+        # @return [String] direct ref SHA or an empty string when missing
+        #
+        # @api private
+        #
         def show_ref_tag_sha(execution_context, tag_name)
           ref = "refs/tags/#{tag_name}"
           result = Git::Commands::ShowRef::List.new(execution_context).call(ref)
@@ -1016,6 +1058,13 @@ module Git
           line ? line.split[0] : ''
         end
 
+        # Parses the result of a git grep command
+        #
+        # @param result [Git::CommandLine::Result] the result of a git grep command
+        #
+        # @return [Hash<String, Array<Array(Integer, String)>>] hash mapping "treeish:filename"
+        #   keys to arrays of [line_number, text] pairs
+        #
         def parse_grep_result(result)
           exitstatus = result.status.exitstatus
           return {} if exitstatus == 1 && result.stderr.empty?
@@ -1051,11 +1100,27 @@ module Git
         # are determined from `opts` via {#parse_archive_format_options}.
         #
         # @param execution_context [Git::ExecutionContext] for the git command
+        #
         # @param treeish [String] tree-ish passed to `git archive`
-        # @param opts [Hash] caller-supplied options (read-only)
+        #
         # @param dest_dir [String] directory for the staging temp file; use
         #   {#staging_dir_for} to select the optimal directory for the destination
         #
+        # @param opts [Hash] caller-supplied options (read-only)
+        #
+        # @option opts [String] :format ('zip') archive format (`'tar'`, `'zip'`,
+        #   or `'tgz'`)
+        #
+        # @option opts [Boolean, nil] :add_gzip (nil) apply gzip post-processing
+        #   to the generated archive
+        #
+        # @option opts [String] :prefix (nil) prefix for entries in the archive
+        #
+        # @option opts [String] :path (nil) path within `treeish` to archive
+        #
+        # @option opts [String] :remote (nil) remote repository from which to
+        #   retrieve the archive
+        #
         # @return [String] path to the populated temporary file
         #
         # @api private
@@ -1078,12 +1143,23 @@ module Git
         # method returns and after the caller stores only the path string.
         #
         # @param execution_context [Git::ExecutionContext] for the git command
+        #
         # @param treeish [String] tree-ish passed to `git archive`
-        # @param opts [Hash] caller-supplied options (read-only; used for :prefix,
-        #   :remote, and :path)
+        #
         # @param format [String] archive format string (e.g. `'zip'` or `'tar'`)
+        #
         # @param dest_dir [String] directory in which to create the temp file
         #
+        # @param opts [Hash] caller-supplied options (read-only; used for :prefix,
+        #   :remote, and :path)
+        #
+        # @option opts [String] :prefix (nil) prefix for entries in the archive
+        #
+        # @option opts [String] :path (nil) path within `treeish` to archive
+        #
+        # @option opts [String] :remote (nil) remote repository from which to
+        #   retrieve the archive
+        #
         # @return [File] the closed file containing the archive
         #
         # @api private
@@ -1102,13 +1178,24 @@ module Git
         # Invoke `git archive` and stream output into `tmp_file`
         #
         # @param execution_context [Git::ExecutionContext] for the git command
+        #
         # @param treeish [String] tree-ish passed to `git archive`
-        # @param opts [Hash] caller-supplied options (read-only; used for :prefix,
-        #   :remote, and :path)
+        #
         # @param format [String] archive format to pass to `git archive --format`
+        #
         # @param tmp_file [File] open, binary-mode IO to write archive data to
         #
-        # @return [Git::CommandLineResult] the result of the git command
+        # @param opts [Hash] caller-supplied options (read-only; used for :prefix,
+        #   :remote, and :path)
+        #
+        # @option opts [String] :prefix (nil) prefix for entries in the archive
+        #
+        # @option opts [String] :path (nil) path within `treeish` to archive
+        #
+        # @option opts [String] :remote (nil) remote repository from which to
+        #   retrieve the archive
+        #
+        # @return [Git::CommandLine::Result] the result of the git command
         #
         # @api private
         #
@@ -1134,6 +1221,7 @@ module Git
         # staging file rather than writing through the link to its target.
         #
         # @param src [String] staging file path to rename; removed on success
+        #
         # @param dest [String] destination file path
         #
         # @return [void]
@@ -1157,6 +1245,12 @@ module Git
         #
         # @param opts [Hash] caller-supplied options hash (read-only)
         #
+        # @option opts [String] :format ('zip') archive format (`'tar'`, `'zip'`,
+        #   or `'tgz'`)
+        #
+        # @option opts [Boolean, nil] :add_gzip (nil) apply gzip post-processing
+        #   after archive generation
+        #
         # @return [Array(String, Boolean)] a two-element array `[format, gzip]`
         #
         #   `format` is the string to pass to `git archive --format`; `gzip` is