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

data/lib/git/parsers/stash.rb

@@ -67,15 +67,34 @@ module Git
 
       # Field indices for parsed output
       module Fields
+        # Index of the full object ID (`%H`) field
         OID = 0
+
+        # Index of the abbreviated object ID (`%h`) field
         SHORT_OID = 1
+
+        # Index of the reflog selector (`%gd`) field
         REFLOG = 2
+
+        # Index of the reflog subject (`%gs`) field
         MESSAGE = 3
+
+        # Index of the author name (`%an`) field
         AUTHOR_NAME = 4
+
+        # Index of the author email (`%ae`) field
         AUTHOR_EMAIL = 5
+
+        # Index of the author date (`%aI`) field
         AUTHOR_DATE = 6
+
+        # Index of the committer name (`%cn`) field
         COMMITTER_NAME = 7
+
+        # Index of the committer email (`%ce`) field
         COMMITTER_EMAIL = 8
+
+        # Index of the committer date (`%cI`) field
         COMMITTER_DATE = 9
       end
 
@@ -92,6 +111,7 @@ module Git
       #   # => [#<Git::StashInfo index: 0, ...>]
       #
       # @param stdout [String] output from git stash list --format=...
+      #
       # @return [Array<Git::StashInfo>] parsed stash information
       #
       # @raise [Git::UnexpectedResultError] if stash output cannot be parsed
@@ -104,7 +124,9 @@ module Git
       # Parse a single stash list line into a StashInfo object
       #
       # @param line [String] a line from git stash list output (custom format)
+      #
       # @param expected_index [Integer] the expected stash index for validation
+      #
       # @param all_lines [Array<String>] all output lines (for error messages)
       #
       # @return [Git::StashInfo] parsed stash info
@@ -121,7 +143,9 @@ module Git
       # Build a StashInfo from parsed format parts
       #
       # @param parts [Array<String>] the parsed format fields
+      #
       # @param expected_index [Integer] fallback index if not parseable from reflog
+      #
       # @return [Git::StashInfo]
       #
       def build_stash_info(parts, expected_index)
@@ -133,13 +157,23 @@ module Git
       # Build StashInfo attributes hash from parsed parts
       #
       # @param parts [Array<String>] the parsed format fields
+      #
       # @param index [Integer] the resolved stash index
+      #
       # @return [Hash] attributes for StashInfo.new
       #
       def stash_info_attrs(parts, index)
         core_attrs(parts, index).merge(author_attrs(parts)).merge(committer_attrs(parts))
       end
 
+      # Build core StashInfo attributes from parsed fields
+      #
+      # @param parts [Array<String>] the parsed format fields
+      #
+      # @param index [Integer] the resolved stash index
+      #
+      # @return [Hash<Symbol, Object>] core attributes for StashInfo.new
+      #
       def core_attrs(parts, index)
         {
           index: index, name: parts[Fields::REFLOG], oid: parts[Fields::OID],
@@ -148,6 +182,12 @@ module Git
         }
       end
 
+      # Build author-related StashInfo attributes from parsed fields
+      #
+      # @param parts [Array<String>] the parsed format fields
+      #
+      # @return [Hash<Symbol, String>] author attributes for StashInfo.new
+      #
       def author_attrs(parts)
         {
           author_name: parts[Fields::AUTHOR_NAME], author_email: parts[Fields::AUTHOR_EMAIL],
@@ -155,6 +195,12 @@ module Git
         }
       end
 
+      # Build committer-related StashInfo attributes from parsed fields
+      #
+      # @param parts [Array<String>] the parsed format fields
+      #
+      # @return [Hash<Symbol, String>] committer attributes for StashInfo.new
+      #
       def committer_attrs(parts)
         {
           committer_name: parts[Fields::COMMITTER_NAME], committer_email: parts[Fields::COMMITTER_EMAIL],
@@ -165,6 +211,7 @@ module Git
       # Extract the stash index from a reflog selector
       #
       # @param reflog_selector [String] e.g., "stash@\\{0}"
+      #
       # @return [Integer, nil] the index or nil if not found
       #
       def extract_index(reflog_selector)
@@ -175,6 +222,7 @@ module Git
       # Extract the branch name from a stash message
       #
       # @param message [String] the stash message
+      #
       # @return [String, nil] the branch name or nil for custom messages
       #
       def extract_branch(message)
@@ -185,8 +233,11 @@ module Git
       # Generate error message for unexpected stash line format
       #
       # @param lines [Array<String>] all output lines
+      #
       # @param line [String] the problematic line
+      #
       # @param index [Integer] the stash index
+      #
       # @return [String] formatted error message
       #
       def unexpected_stash_line_error(lines, line, index)

data/lib/git/parsers/tag.rb

@@ -94,6 +94,7 @@ module Git
       #   # => [#<Git::TagInfo name: "v1.0.0", ...>]
       #
       # @param stdout [String] output from git tag --list --format=...
+      #
       # @return [Array<Git::TagInfo>] parsed tag information
       #
       # @raise [Git::UnexpectedResultError] if any record has unexpected format
@@ -116,8 +117,11 @@ module Git
       # these are converted to nil by {#parse_optional_field} and {#parse_message}.
       #
       # @param record [String] a single tag record from git tag --format output
+      #
       # @param index [Integer] record index for error reporting
+      #
       # @param all_records [Array<String>] all output records for error messages
+      #
       # @return [Git::TagInfo] tag info with all fields populated
       #
       # @raise [Git::UnexpectedResultError] if record format is unexpected
@@ -135,6 +139,7 @@ module Git
       # Build a TagInfo object from parsed parts
       #
       # @param parts [Array<String>] the parsed format fields
+      #
       # @return [Git::TagInfo]
       #
       # @note For annotated tags:
@@ -150,10 +155,31 @@ module Git
         build_tag_info_object(parts, oid, target_oid)
       end
 
+      # Resolves canonical and target object OIDs from git tag format fields
+      #
+      # @param objecttype [String] the object type from git output
+      #
+      # @param objectname [String] the object OID from %(objectname)
+      #
+      # @param dereferenced [String] the object OID from %(*objectname)
+      #
+      # @return [Array((String, nil), String)] the two-element tuple
+      #   `[oid, target_oid]`
+      #
       def resolve_oids(objecttype, objectname, dereferenced)
         objecttype == 'tag' ? [objectname, dereferenced] : [nil, objectname]
       end
 
+      # Builds a TagInfo object from normalized parser values
+      #
+      # @param parts [Array<String>] the parsed format fields
+      #
+      # @param oid [String, nil] the tag object's OID or nil for lightweight tags
+      #
+      # @param target_oid [String] the target object OID
+      #
+      # @return [Git::TagInfo] the tag info with all fields populated
+      #
       def build_tag_info_object(parts, oid, target_oid)
         Git::TagInfo.new(
           name: parts[0], oid: oid, target_oid: target_oid, objecttype: parts[3],
@@ -165,6 +191,7 @@ module Git
       # Parse an optional field, returning nil if empty
       #
       # @param value [String] the field value
+      #
       # @return [String, nil] the value or nil if empty
       #
       def parse_optional_field(value)
@@ -175,7 +202,9 @@ module Git
       # Strips trailing newlines that git adds to %(contents) output
       #
       # @param objecttype [String] the object type ('tag' or 'commit')
+      #
       # @param message [String] the raw message field
+      #
       # @return [String, nil] the message or nil
       #
       def parse_message(objecttype, message)
@@ -190,6 +219,7 @@ module Git
       #   # => ["v1.0.0"]
       #
       # @param stdout [String] command stdout
+      #
       # @return [Array<String>] names of successfully deleted tags
       #
       def parse_deleted_tags(stdout)
@@ -203,6 +233,7 @@ module Git
       #   # => {"missing" => "error: tag 'missing' not found."}
       #
       # @param stderr [String] command stderr
+      #
       # @return [Hash<String, String>] map of tag name to error message
       #
       def parse_error_messages(stderr)
@@ -215,9 +246,13 @@ module Git
       # Build the TagDeleteResult from parsed data
       #
       # @param requested_names [Array<String>] originally requested tag names
+      #
       # @param existing_tags [Hash<String, Git::TagInfo>] tags that existed before delete
+      #
       # @param deleted_names [Array<String>] names confirmed deleted in stdout
+      #
       # @param error_map [Hash<String, String>] map of tag name to error message
+      #
       # @return [Git::TagDeleteResult] the result object
       #
       def build_delete_result(requested_names, existing_tags, deleted_names, error_map)
@@ -234,8 +269,11 @@ module Git
       # Generate error message for unexpected tag record format
       #
       # @param records [Array<String>] all output records
+      #
       # @param record [String] the problematic record
+      #
       # @param index [Integer] the record index
+      #
       # @return [String] formatted error message
       #
       def unexpected_tag_record_error(records, record, index)

data/lib/git/remote.rb

@@ -59,7 +59,31 @@ module Git
     # @example Fetch from origin
     #   git.remote('origin').fetch
     #
-    # @param opts [Hash] fetch options (see `Git::Repository#fetch`)
+    # @param opts [Hash] options for the fetch command
+    #
+    # @option opts [Boolean, nil] :tags (nil) fetch all tags from the remote
+    #   (`--tags`)
+    #
+    # @option opts [Boolean, nil] :prune (nil) remove remote-tracking references
+    #   that no longer exist on the remote (`--prune`)
+    #
+    # @option opts [Boolean, nil] :prune_tags (nil) remove local tags that no
+    #   longer exist on the remote (`--prune-tags`)
+    #
+    # @option opts [Boolean, nil] :force (nil) override the fast-forward check
+    #   when using explicit refspecs (`--force`)
+    #
+    # @option opts [Boolean, nil] :update_head_ok (nil) allow `git fetch` to
+    #   update the branch pointed to by `HEAD` (`--update-head-ok`)
+    #
+    # @option opts [Boolean, nil] :unshallow (nil) convert a shallow clone into a
+    #   full repository (`--unshallow`)
+    #
+    # @option opts [String, Integer, nil] :depth (nil) limit history to N commits
+    #   from each branch tip (`--depth=N`)
+    #
+    # @option opts [String, Array<String>, nil] :ref (nil) one or more refspecs to
+    #   fetch as positional arguments after the remote name
     #
     # @return [String] git's stdout from the fetch
     #
@@ -107,7 +131,7 @@ module Git
     # @example Remove the upstream remote
     #   git.remote('upstream').remove
     #
-    # @return [Git::CommandLineResult] the result of `git remote remove`
+    # @return [Git::CommandLine::Result] the result of `git remote remove`
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
@@ -136,6 +160,14 @@ module Git
       @base
     end
 
+    # Builds branch metadata for a remote-tracking branch
+    #
+    # @param refname [String] remote-tracking branch name (for example,
+    #   `'origin/main'`)
+    #
+    # @return [Git::BranchInfo] minimal branch metadata for constructing
+    #   {Git::Branch}
+    #
     def build_branch_info(refname)
       Git::BranchInfo.new(
         refname: refname,

data/lib/git/repository/branching.rb

@@ -24,11 +24,13 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module Branching # rubocop:disable Metrics/ModuleLength
       # Represents the state of HEAD in a repository
       #
+      # @api private
+      #
       # @!attribute [r] state
       #   @return [Symbol] one of `:active`, `:unborn`, or `:detached`
       #
@@ -343,7 +345,7 @@ module Git
       # @param start_point [String, nil] the commit, branch, or tag to start the
       #   new branch from; defaults to the current HEAD when `nil`
       #
-      # @param options [Hash] reserved; must be empty — no options are currently
+      # @param branch_options [Hash] reserved; must be empty — no options are currently
       #   supported
       #
       # @return [void]
@@ -352,14 +354,14 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      def branch_new(branch, start_point = nil, options = {})
-        if start_point.is_a?(Hash) && options.empty?
-          options = start_point
+      def branch_new(branch, start_point = nil, branch_options = {})
+        if start_point.is_a?(Hash) && branch_options.empty?
+          branch_options = start_point
           start_point = nil
         end
 
-        SharedPrivate.assert_valid_opts!(BRANCH_NEW_ALLOWED_OPTS, **options)
-        Git::Commands::Branch::Create.new(@execution_context).call(branch, start_point, **options)
+        SharedPrivate.assert_valid_opts!(BRANCH_NEW_ALLOWED_OPTS, **branch_options)
+        Git::Commands::Branch::Create.new(@execution_context).call(branch, start_point, **branch_options)
 
         nil
       end
@@ -432,6 +434,12 @@ module Git
       #   repo.change_head_branch('my-branch')
       #   # HEAD now points at refs/heads/my-branch before any commits exist
       #
+      # @param branch_name [String] the branch name to point HEAD at
+      #
+      # @return [void]
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
       # @note Pointing HEAD at a branch that does not yet exist places the
       #   repository in unborn-branch state. This is intentional for repository
       #   initialization workflows — for example, setting a custom default branch
@@ -439,12 +447,6 @@ module Git
       #   The repository will appear to have no commits until the first commit is
       #   made on the new branch.
       #
-      # @param branch_name [String] the branch name to point HEAD at
-      #
-      # @return [void]
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
       def change_head_branch(branch_name)
         Git::Commands::SymbolicRef::Update.new(@execution_context).call('HEAD', "refs/heads/#{branch_name}")
         nil
@@ -547,7 +549,7 @@ module Git
       #
       # @param commit [String] the commit SHA to point the branch at
       #
-      # @return [Git::CommandLineResult] the result of calling `git update-ref`
+      # @return [Git::CommandLine::Result] the result of calling `git update-ref`
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
@@ -652,7 +654,7 @@ module Git
         #
         # @param branch [String, nil] the branch argument passed to {#checkout}
         #
-        # @param options [Hash] the raw options passed to {#checkout}
+        # @param checkout_options [Hash] the raw options passed to {#checkout}
         #
         # @return [Array] a two-element tuple `[target, options]` containing the
         #   translated checkout arguments
@@ -663,13 +665,13 @@ module Git
         #
         # @api private
         #
-        def translate_checkout_opts(branch, options)
-          if options[:new_branch] == true || options[:b] == true
-            [options[:start_point], options.except(:new_branch, :b, :start_point).merge(b: branch)]
-          elsif options[:new_branch].is_a?(String)
-            [branch, options.except(:new_branch).merge(b: options[:new_branch])]
+        def translate_checkout_opts(branch, checkout_options)
+          if checkout_options[:new_branch] == true || checkout_options[:b] == true
+            [checkout_options[:start_point], checkout_options.except(:new_branch, :b, :start_point).merge(b: branch)]
+          elsif checkout_options[:new_branch].is_a?(String)
+            [branch, checkout_options.except(:new_branch).merge(b: checkout_options[:new_branch])]
           else
-            [branch, options]
+            [branch, checkout_options]
           end
         end
 

data/lib/git/repository/committing.rb

@@ -12,7 +12,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module Committing
       # Option keys accepted by {#commit}
@@ -59,7 +59,7 @@ module Git
       #
       # @option opts [String] :date (nil) override the author date
       #
-      # @option opts [Boolean, nil] :gpg_sign (nil) GPG-sign the commit
+      # @option opts [Boolean, String, nil] :gpg_sign (nil) GPG-sign the commit
       #
       # @option opts [Boolean, nil] :no_gpg_sign (nil) disable GPG signing
       #
@@ -94,10 +94,35 @@ module Git
       # @example Commit all changes with a message
       #   repo.commit_all('Update everything')
       #
-      # @param message [String] the commit message
+      # @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
@@ -120,10 +145,11 @@ module Git
       #
       # @param opts [Hash] options for the commit-tree command
       #
-      # @option opts [String] :m (nil) the commit message (short form)
+      # @option opts [String, Array<String>] :m (nil) the commit message
+      #   paragraph(s) (short form)
       #
-      # @option opts [String] :message (nil) the commit message (normalized
-      #   to `:m` before passing to the command)
+      # @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)
       #
@@ -173,6 +199,20 @@ module Git
       #
       # @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

data/lib/git/repository/context_helpers.rb

@@ -15,7 +15,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module ContextHelpers
       # Changes the current working directory to the repository working directory
@@ -27,17 +27,17 @@ module Git
       #     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
       #
-      # @return [Object] the value returned by the block
-      #
-      # @raise [ArgumentError] if the repository has no working directory (bare
-      #   repository)
-      #
       def chdir
         raise ArgumentError, 'cannot chdir: repository has no working directory (bare repository)' if dir.nil?
 
@@ -58,14 +58,14 @@ module Git
       #
       # @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
       #
-      # @return [Object] the value returned by the block
-      #
       def with_index(new_index) # :yields: self
         old_context = @execution_context
         set_index(new_index, must_exist: false)
@@ -90,14 +90,14 @@ module Git
       #     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
       #
-      # @return [Object] the value returned by the block
-      #
       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
@@ -127,6 +127,10 @@ module Git
       # @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
       #
@@ -134,10 +138,6 @@ module Git
       #
       # @yieldreturn [Object] returned as the method's return value
       #
-      # @return [Object] the value returned by the block
-      #
-      # @raise [ArgumentError] if `work_dir` does not exist on disk
-      #
       def with_working(work_dir) # :yields: self
         old_context = @execution_context
         set_working(work_dir)
@@ -158,6 +158,8 @@ module Git
       #     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
       #
@@ -165,8 +167,6 @@ module Git
       #
       # @yieldreturn [Object] returned as the method's return value
       #
-      # @return [Object] the value returned by the block
-      #
       def with_temp_working(&block) # :yields: self
         Dir.mktmpdir('temp-workdir') { |temp_dir| with_working(temp_dir, &block) }
       end
@@ -231,6 +231,14 @@ module Git
 
       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(
@@ -250,12 +258,33 @@ module Git
         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