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

data/lib/git/object.rb

@@ -9,11 +9,37 @@ module Git
   # represents a git object
   class Object
     # A base class for all Git objects
+    #
+    # @api private
+    #
     class AbstractObject
-      attr_accessor :objectish, :type, :mode
+      # @return [String] the object name, SHA, ref, or treeish path
+      #
+      attr_accessor :objectish
+
+      # @return [String, nil] the git object type
+      #
+      attr_accessor :type
 
+      # @return [String, nil] the file mode from tree listings
+      #
+      attr_accessor :mode
+
+      # Sets the size of the git object in bytes
+      #
+      # @example Set the size to 60 bytes
+      #   object.size = 60
+      #
+      # @return [Integer] the size of the git object in bytes
+      #
       attr_writer :size
 
+      # Creates a lazy wrapper for a git object
+      #
+      # @param base [Git::Repository] the repository used to query object data
+      #
+      # @param objectish [String, #to_s] the object name, SHA, ref, or treeish path
+      #
       def initialize(base, objectish)
         @base = base
         @objectish = objectish.to_s
@@ -23,10 +49,18 @@ module Git
         @sha = nil
       end
 
+      # Returns the resolved SHA for this object
+      #
+      # @return [String] the resolved object SHA
+      #
       def sha
         @sha ||= object_repository.rev_parse(@objectish)
       end
 
+      # Returns the size of this object in bytes
+      #
+      # @return [Integer] the object size in bytes
+      #
       def size
         @size ||= object_repository.cat_file_size(@objectish)
       end
@@ -76,56 +110,152 @@ module Git
         end
       end
 
+      # Returns the object contents split into lines
+      #
+      # @return [Array<String>] the raw contents split on newline boundaries
+      #
       def contents_array
         contents.split("\n")
       end
 
+      # Returns the original object expression
+      #
+      # @return [String] the object name, SHA, ref, or treeish path
+      #
       def to_s
         @objectish
       end
 
+      # Searches this object for matching tracked file contents
+      #
+      # Always searches this object's resolved SHA. A caller-provided `:object`
+      # option is ignored.
+      #
+      # @param string [String] the pattern to search for
+      #
+      # @param path_limiter [String, Pathname, Array<String, Pathname>, nil]
+      #   path or paths to limit the search to
+      #
+      # @param opts [Hash] additional grep options
+      #
+      # @option opts [Boolean, nil] :ignore_case (nil) ignore case
+      #   distinctions in the pattern and file contents
+      #
+      #   Alias: :i
+      #
+      # @option opts [Boolean, nil] :invert_match (nil) select non-matching
+      #   lines
+      #
+      #   Alias: :v
+      #
+      # @option opts [Boolean, nil] :extended_regexp (nil) use POSIX extended
+      #   regular expressions for the pattern
+      #
+      #   Alias: :E
+      #
+      # @return [Hash<String, Array<Array(Integer, String)>>] matching lines by path
+      #
       def grep(string, path_limiter = nil, opts = {})
         object_repository.grep(string, path_limiter, opts.merge(object: sha))
       end
 
+      # Returns a diff from this object to another object
+      #
+      # @param objectish [String] the object name, SHA, ref, or treeish path to diff
+      #   against
+      #
+      # @return [Git::Diff] the diff between the two objects
+      #
       def diff(objectish)
         Git::Diff.new(@base, @objectish, objectish)
       end
 
+      # Returns a log scoped to this object
+      #
+      # @param count [Integer] maximum number of commits to include
+      #
+      # @return [Git::Log] the scoped log object
+      #
       def log(count = 30)
         Git::Log.new(@base, count).object(@objectish)
       end
 
       # Creates an archive of this object and writes it to a file
       #
-      # @api public
+      # @example Archive a tree to a zip file
+      #   git.object('v1.0').archive('/tmp/release.zip', format: 'zip')
+      #
+      # @example Archive a tree to a temporary tar file
+      #   git.object('v2.6').archive(nil, format: 'tar')
+      #
+      # @example Archive a tree to a tgz file with a path prefix
+      #   git.object('v2.6').archive('/tmp/release.tgz', format: 'tgz', prefix: 'test/')
+      #
+      # @example Archive one directory with a path prefix
+      #   git.object('v2.6').archive(
+      #     '/tmp/ex-dir.tar',
+      #     format: 'tar',
+      #     prefix: 'test/',
+      #     path: 'ex_dir/'
+      #   )
       #
       # @param file [String, nil] destination file path; a temp file is created if `nil`
       #
       # @param opts [Hash] archive options (see {Git::Repository#archive})
       #
+      # @option opts [String] :format ('zip') archive format: `'tar'`, `'zip'`,
+      #   or `'tgz'`
+      #
+      # @option opts [String] :prefix (nil) prefix prepended to every filename
+      #   in the archive
+      #
+      # @option opts [String] :path (nil) path within the tree to include
+      #
+      # @option opts [String] :remote (nil) retrieve the archive from a remote
+      #   repository
+      #
+      # @option opts [Boolean, nil] :add_gzip (nil) apply gzip compression after
+      #   writing the archive
+      #
       # @return [String] the path to the written archive file
       #
+      # @raise [ArgumentError] when archive options or destination path are invalid
+      #
       # @raise [Git::FailedError] if `git archive` fails
       #
-      # @example Archive a tree to a zip file
-      #   git.object('v1.0').archive('/tmp/release.zip', format: 'zip')
+      # @api public
       #
       def archive(file = nil, opts = {})
         object_repository.archive(@objectish, file, opts)
       end
 
+      # Returns whether this object is a tree
+      #
+      # @return [Boolean] `true` when this object is a tree
+      #
       def tree? = false
 
+      # Returns whether this object is a blob
+      #
+      # @return [Boolean] `true` when this object is a blob
+      #
       def blob? = false
 
+      # Returns whether this object is a commit
+      #
+      # @return [Boolean] `true` when this object is a commit
+      #
       def commit? = false
 
+      # Returns whether this object is a tag
+      #
+      # @return [Boolean] `true` when this object is a tag
+      #
       def tag? = false
 
       private
 
-      # @return [Git::Repository]
+      # @return [Git::Repository] the repository used for object lookup
       #
       def object_repository
         @base
@@ -134,11 +264,23 @@ module Git
 
     # A Git blob object
     class Blob < AbstractObject
+      # Creates a blob object wrapper
+      #
+      # @param base [Git::Repository] the repository used to query object data
+      #
+      # @param sha [String] the blob SHA or object expression
+      #
+      # @param mode [String, nil] the file mode from tree listings
+      #
       def initialize(base, sha, mode = nil)
         super(base, sha)
         @mode = mode
       end
 
+      # Returns whether this object is a blob
+      #
+      # @return [Boolean] `true`
+      #
       def blob?
         true
       end
@@ -146,6 +288,14 @@ module Git
 
     # A Git tree object
     class Tree < AbstractObject
+      # Creates a tree object wrapper
+      #
+      # @param base [Git::Repository] the repository used to query object data
+      #
+      # @param sha [String] the tree SHA or object expression
+      #
+      # @param mode [String, nil] the file mode from tree listings
+      #
       def initialize(base, sha, mode = nil)
         super(base, sha)
         @mode = mode
@@ -153,29 +303,53 @@ module Git
         @blobs = nil
       end
 
+      # Returns child blobs and subtrees keyed by name
+      #
+      # @return [Hash<String, Git::Object::AbstractObject>] child objects by name
+      #
       def children
         blobs.merge(subtrees)
       end
 
+      # Returns blobs directly under this tree
+      #
+      # @return [Hash<String, Git::Object::Blob>] blob objects by filename
+      #
       def blobs
         @blobs ||= check_tree[:blobs]
       end
       alias files blobs
 
+      # Returns subtrees directly under this tree
+      #
+      # @return [Hash<String, Git::Object::Tree>] subtree objects by directory name
+      #
       def trees
         @trees ||= check_tree[:trees]
       end
       alias subtrees trees
       alias subdirectories trees
 
+      # Returns the full tree listing for this tree
+      #
+      # @return [Hash] parsed recursive tree data
+      #
       def full_tree
         object_repository.full_tree(@objectish)
       end
 
+      # Returns the maximum depth of this tree
+      #
+      # @return [Integer] maximum tree depth
+      #
       def depth
         object_repository.tree_depth(@objectish)
       end
 
+      # Returns whether this object is a tree
+      #
+      # @return [Boolean] `true`
+      #
       def tree?
         true
       end
@@ -203,6 +377,14 @@ module Git
 
     # A Git commit object
     class Commit < AbstractObject
+      # Creates a commit object wrapper
+      #
+      # @param base [Git::Repository] the repository used to query object data
+      #
+      # @param sha [String] the commit SHA or object expression
+      #
+      # @param init [Hash, nil] parsed commit data used to initialize eagerly
+      #
       def initialize(base, sha, init = nil)
         super(base, sha)
         @tree = nil
@@ -215,20 +397,37 @@ module Git
         from_data(init)
       end
 
+      # Returns the commit message
+      #
+      # @return [String] the commit message without the trailing newline
+      #
       def message
         check_commit
         @message
       end
 
+      # Returns the symbolic name for this commit
+      #
+      # @return [String] the name produced by `git name-rev`
+      #
       def name
         object_repository.name_rev(sha)
       end
 
+      # Returns the tree for this commit
+      #
+      # @return [Git::Object::Tree] the commit tree
+      #
       def gtree
         check_commit
         Tree.new(@base, @tree)
       end
 
+      # Returns the first parent commit
+      #
+      # @return [Git::Object::Commit, nil] the first parent commit, or `nil`
+      #   for a root commit
+      #
       def parent
         parents.first
       end
@@ -245,6 +444,10 @@ module Git
         @author
       end
 
+      # Returns the author date
+      #
+      # @return [Time] the author timestamp
+      #
       def author_date
         author.date
       end
@@ -255,15 +458,31 @@ module Git
         @committer
       end
 
+      # Returns the committer date
+      #
+      # @return [Time] the committer timestamp
+      #
       def committer_date
         committer.date
       end
       alias date committer_date
 
+      # Returns the diff between this commit and its first parent
+      #
+      # @return [Git::Diff] the diff from the first parent to this commit
+      #
       def diff_parent
         diff(parent)
       end
 
+      # Sets parsed commit data on this commit object
+      #
+      # @param data [Hash] parsed commit data
+      #
+      # @return [void]
+      #
+      # @deprecated use {#from_data} instead
+      #
       def set_commit(data) # rubocop:disable Naming/AccessorMethodName
         Git::Deprecation.warn(
           'Git::Object::Commit#set_commit is deprecated and will be removed in a future version. ' \
@@ -272,6 +491,12 @@ module Git
         from_data(data)
       end
 
+      # Loads parsed commit data into this commit object
+      #
+      # @param data [Hash] parsed commit data from `git cat-file commit`
+      #
+      # @return [void]
+      #
       def from_data(data)
         @sha ||= data['sha']
         @committer = Git::Author.new(data['committer'])
@@ -281,6 +506,10 @@ module Git
         @message = data['message'].chomp
       end
 
+      # Returns whether this object is a commit
+      #
+      # @return [Boolean] `true`
+      #
       def commit?
         true
       end
@@ -303,9 +532,9 @@ module Git
     # Annotated tags contain additional metadata such as the tagger's name, email, and
     # the date when the tag was created, along with a message.
     #
-    # TODO: Annotated tags are not objects
-    #
     class Tag < AbstractObject
+      # @return [String] the tag name
+      #
       attr_accessor :name
 
       # @overload initialize(base, name)
@@ -336,19 +565,37 @@ module Git
         @loaded = false
       end
 
+      # Returns whether this tag is annotated
+      #
+      # @return [Boolean] `true` when the tag has an annotated tag object
+      #
       def annotated?
         @annotated = @annotated.nil? ? (object_repository.cat_file_type(name) == 'tag') : @annotated
       end
 
+      # Returns the tag message
+      #
+      # @return [String, nil] the annotated tag message, or `nil` for a
+      #   lightweight tag
+      #
       def message
         check_tag
         @message
       end
 
+      # Returns whether this object is a tag
+      #
+      # @return [Boolean] `true`
+      #
       def tag?
         true
       end
 
+      # Returns the tagger identity
+      #
+      # @return [Git::Author, nil] the tagger for an annotated tag, or `nil`
+      #   for a lightweight tag
+      #
       def tagger
         check_tag
         @tagger
@@ -356,6 +603,10 @@ module Git
 
       private
 
+      # Loads annotated tag data when available
+      #
+      # @return [void]
+      #
       def check_tag
         return if @loaded
 
@@ -373,6 +624,17 @@ module Git
 
     # if we're calling this, we don't know what type it is yet
     # so this is our little factory method
+    #
+    # @param base [Git::Repository] the repository used to query object data
+    #
+    # @param objectish [String] the object name, SHA, ref, or treeish path
+    #
+    # @param type [String, nil] object type hint: `blob`, `commit`, or `tree`
+    #
+    # @param is_tag [Boolean] whether to construct a tag object
+    #
+    # @return [Git::Object::AbstractObject] the concrete object wrapper
+    #
     def self.new(base, objectish, type = nil, is_tag = false) # rubocop:disable Style/OptionalBooleanParameter
       return new_tag(base, objectish) if is_tag
 
@@ -387,12 +649,26 @@ module Git
       klass.new(base, objectish)
     end
 
+    # Creates a tag object through the deprecated factory path
+    #
+    # @param base [Git::Repository] the repository used to query object data
+    #
+    # @param objectish [String] the tag name or SHA
+    #
+    # @return [Git::Object::Tag] the tag object wrapper
+    #
+    # @deprecated use `Git::Object::Tag.new` instead
+    #
     private_class_method def self.new_tag(base, objectish)
       Git::Deprecation.warn('Git::Object.new with is_tag argument is deprecated. Use Git::Object::Tag.new instead.')
       Git::Object::Tag.new(base, objectish)
     end
 
-    # @return [Git::Repository]
+    # Returns the repository used for object lookup
+    #
+    # @param base [Git::Repository] the repository to return
+    #
+    # @return [Git::Repository] the repository used for object lookup
     #
     private_class_method def self.object_repository_for(base)
       base

data/lib/git/parsers/branch.rb

@@ -5,6 +5,10 @@ require 'git/branch_delete_result'
 require 'git/branch_delete_failure'
 
 module Git
+  # Internal parsers that translate raw git command output into structured Ruby objects.
+  #
+  # @api private
+  #
   module Parsers
     # Parser for git branch command output
     #
@@ -76,6 +80,7 @@ module Git
       # Parse a single formatted branch line
       #
       # @param line [String] the line to parse (pipe-delimited fields)
+      #
       # @return [Git::BranchInfo, nil] branch info object, or nil if line should be skipped
       #
       def parse_branch_line(line)
@@ -89,6 +94,7 @@ module Git
       # Build a BranchInfo from parsed fields
       #
       # @param fields [Array<String>] the parsed fields: [refname, objectname, head, worktreepath, symref, upstream]
+      #
       # @return [Git::BranchInfo] the branch info object
       #
       def build_branch_info(fields)
@@ -112,6 +118,7 @@ module Git
       # - "(not a branch)" for non-branch entries
       #
       # @param refname [String] the refname to check
+      #
       # @return [Boolean] true if this is a non-branch entry
       #
       def non_branch_entry?(refname)
@@ -125,6 +132,7 @@ module Git
       # - refs/remotes/origin/main -> remotes/origin/main
       #
       # @param refname [String] the full refname from git
+      #
       # @return [String] normalized refname
       #
       def normalize_refname(refname)
@@ -137,7 +145,9 @@ module Git
       # (worktreepath is non-empty AND it's not the current branch)
       #
       # @param worktreepath [String, nil] the worktree path from git output
+      #
       # @param current [Boolean] whether this is the current branch
+      #
       # @return [Boolean] true if checked out in another worktree
       #
       def in_other_worktree?(worktreepath, current)
@@ -148,6 +158,7 @@ module Git
       # Build upstream BranchInfo from upstream refname
       #
       # @param upstream_ref [String, nil] the upstream ref (e.g., 'refs/remotes/origin/main')
+      #
       # @return [Git::BranchInfo, nil] upstream branch info or nil
       #
       def build_upstream_info(upstream_ref)
@@ -166,6 +177,7 @@ module Git
       # Return value if non-empty, nil otherwise
       #
       # @param value [String, nil] the value to check
+      #
       # @return [String, nil] the value or nil
       #
       def presence(value)
@@ -179,6 +191,7 @@ module Git
       #   # => ["feature"]
       #
       # @param stdout [String] command stdout
+      #
       # @return [Array<String>] names of successfully deleted branches
       #
       def parse_deleted_branches(stdout)
@@ -192,6 +205,7 @@ module Git
       #   # => {"missing" => "error: branch 'missing' not found."}
       #
       # @param stderr [String] command stderr
+      #
       # @return [Hash<String, String>] map of branch name to error message
       #
       def parse_error_messages(stderr)
@@ -204,9 +218,13 @@ module Git
       # Build the BranchDeleteResult from parsed data
       #
       # @param requested_names [Array<String>] originally requested branch names
+      #
       # @param existing_branches [Hash<String, Git::BranchInfo>] branches that existed before delete
+      #
       # @param deleted_names [Array<String>] names confirmed deleted in stdout
+      #
       # @param error_map [Hash<String, String>] map of branch name to error message
+      #
       # @return [Git::BranchDeleteResult] the result object
       #
       def build_delete_result(requested_names, existing_branches, deleted_names, error_map)

data/lib/git/parsers/cat_file.rb

@@ -86,6 +86,8 @@ module Git
       #
       # @param lines [Array<String>] mutable output lines from a cat-file response
       #
+      # @return [void]
+      #
       # @yield [key, value] each parsed header pair
       #
       # @yieldparam key [String] header field name
@@ -94,8 +96,6 @@ module Git
       #
       # @yieldreturn [void]
       #
-      # @return [void]
-      #
       # @api private
       #
       def each_header(lines)