git 4.3.2 → 5.0.0.beta.1

data/lib/git/commands/write_tree.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git write-tree` command
+    #
+    # Creates a tree object using the current index and prints the SHA-1 name of
+    # the new tree object to standard output. The index must be in a fully
+    # merged state.
+    #
+    # @example Write the current index as a tree object
+    #   write_tree = Git::Commands::WriteTree.new(execution_context)
+    #   result = write_tree.call
+    #   sha = result.stdout   # => "abc123..."
+    #
+    # @example Write only a subdirectory as a tree object
+    #   write_tree = Git::Commands::WriteTree.new(execution_context)
+    #   result = write_tree.call(prefix: 'lib/')
+    #
+    # @example Allow missing objects in the object database
+    #   write_tree = Git::Commands::WriteTree.new(execution_context)
+    #   result = write_tree.call(missing_ok: true)
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-write-tree/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-write-tree git-write-tree
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class WriteTree < Git::Commands::Base
+      arguments do
+        literal 'write-tree'
+        flag_option :missing_ok
+        value_option :prefix, inline: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(**options)
+      #
+      #     Execute the `git write-tree` command
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :missing_ok (nil) disable the check that
+      #       all objects referenced by the directory exist in the object
+      #       database
+      #
+      #     @option options [String] :prefix (nil) write a tree object that
+      #       represents a subdirectory
+      #
+      #       The prefix path should end with `/` (e.g., `'lib/'`).
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git write-tree`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      #   @api public
+      #
+    end
+  end
+end

data/lib/git/commands.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative 'commands/base'
+require_relative 'commands/add'
+require_relative 'commands/am'
+require_relative 'commands/apply'
+require_relative 'commands/archive'
+require_relative 'commands/branch'
+require_relative 'commands/cat_file'
+require_relative 'commands/checkout'
+require_relative 'commands/checkout_index'
+require_relative 'commands/clean'
+require_relative 'commands/clone'
+require_relative 'commands/commit'
+require_relative 'commands/commit_tree'
+require_relative 'commands/config_option_syntax'
+require_relative 'commands/describe'
+require_relative 'commands/diff'
+require_relative 'commands/diff_files'
+require_relative 'commands/diff_index'
+require_relative 'commands/fetch'
+require_relative 'commands/fsck'
+require_relative 'commands/gc'
+require_relative 'commands/grep'
+require_relative 'commands/init'
+require_relative 'commands/log'
+require_relative 'commands/ls_files'
+require_relative 'commands/ls_remote'
+require_relative 'commands/ls_tree'
+require_relative 'commands/maintenance'
+require_relative 'commands/merge'
+require_relative 'commands/merge_base'
+require_relative 'commands/mv'
+require_relative 'commands/name_rev'
+require_relative 'commands/pull'
+require_relative 'commands/push'
+require_relative 'commands/read_tree'
+require_relative 'commands/remote'
+require_relative 'commands/repack'
+require_relative 'commands/reset'
+require_relative 'commands/rev_parse'
+require_relative 'commands/revert'
+require_relative 'commands/rm'
+require_relative 'commands/show'
+require_relative 'commands/show_ref'
+require_relative 'commands/stash'
+require_relative 'commands/status'
+require_relative 'commands/symbolic_ref'
+require_relative 'commands/tag'
+require_relative 'commands/update_ref'
+require_relative 'commands/version'
+require_relative 'commands/worktree'
+require_relative 'commands/write_tree'
+
+module Git
+  # Internal command layer for the git gem
+  #
+  # Each git operation is represented by a class within this namespace. Command
+  # classes define the CLI contract via the {Arguments} DSL, bind caller-supplied
+  # parameters to command-line flags and operands, execute the subprocess through
+  # {Git::CommandLine}, and return a raw {Git::CommandLineResult}.
+  #
+  # Commands do **not** parse output — that responsibility belongs to the
+  # {Git::Parsers} layer, orchestrated by the facade ({Git::Lib} / future
+  # {Git::Repository}).
+  #
+  # All classes in this namespace are internal (`@api private`). End users
+  # should interact with the public API on {Git::Base} instead.
+  #
+  # ## Architecture
+  #
+  # ```
+  # Git::Base (public API)
+  #   └── Git::Lib / Git::Repository (facade — orchestrates commands + parsers)
+  #         └── Git::Commands::* (defines CLI API, binds args, executes)
+  #               └── Git::CommandLine (subprocess execution)
+  # ```
+  #
+  # Simple commands inherit from {Commands::Base} and only need an `arguments`
+  # block. Multi-mode git commands (e.g., `git branch`, `git stash`) are split
+  # into namespace modules with one class per mode.
+  #
+  # @api private
+  #
+  # @see Git::Commands::Base
+  # @see Git::Commands::Arguments
+  #
+  module Commands; end
+end

data/lib/git/detached_head_info.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Git
+  # Value object representing a detached HEAD state
+  #
+  # When HEAD points directly to a commit rather than a branch reference,
+  # the repository is in a "detached HEAD" state. This object captures
+  # that state along with the commit SHA that HEAD points to.
+  #
+  # This class shares a minimal interface with {Git::BranchInfo} to allow
+  # polymorphic usage where appropriate:
+  # - `short_name` - returns 'HEAD'
+  # - `target_oid` - returns the commit SHA
+  # - `to_s` - returns 'HEAD'
+  # - `detached?` - returns true
+  #
+  # @example Detecting detached HEAD state
+  #   head = repo.show_current
+  #   if head.detached?
+  #     puts "HEAD detached at #{head.target_oid[0, 7]}"
+  #   else
+  #     puts "On branch #{head.short_name}"
+  #   end
+  #
+  # @example Polymorphic usage
+  #   head = repo.show_current
+  #   puts "Checked out: #{head.short_name}"  # Works for both types
+  #   system("git log #{head.short_name}")    # Works for both types
+  #
+  # @see Git::BranchInfo for the branch counterpart
+  # @see Git::Commands::Branch::ShowCurrent for the command that produces this
+  #
+  # @api public
+  #
+  # @!attribute [r] target_oid
+  #
+  #   The commit object ID (SHA) that HEAD points to
+  #
+  #   @return [String] the full 40-character object ID
+  #
+  DetachedHeadInfo = Data.define(:target_oid) do
+    # @return [Boolean] always true for DetachedHeadInfo
+    def detached? = true
+
+    # @return [Boolean] always false for DetachedHeadInfo (detached HEAD always has a commit)
+    def unborn? = false
+
+    # @return [String] always 'HEAD'
+    def short_name = 'HEAD'
+
+    # @return [String] always 'HEAD'
+    def to_s = 'HEAD'
+  end
+end

data/lib/git/diff.rb

@@ -4,10 +4,37 @@ require_relative 'diff_path_status'
 require_relative 'diff_stats'
 
 module Git
-  # object that holds the diff between two commits
+  # Diff between two commits or between a commit and the working tree
+  #
+  # @example Diff between two commits
+  #   diff = repo.diff('HEAD~1', 'HEAD')
+  #   diff.size       # => 3
+  #   diff.insertions # => 20
+  #   diff.deletions  # => 5
+  #
+  # @example Limit diff to a specific path
+  #   diff = repo.diff('HEAD~1', 'HEAD').path('lib/')
+  #
+  # @api public
+  #
   class Diff
     include Enumerable
 
+    # Creates a new Diff
+    #
+    # @example
+    #   diff = Git::Diff.new(base, 'HEAD~1', 'HEAD')
+    #
+    # @param base [Git::Base, Git::Repository] the git repository
+    #
+    # @param from [String, nil] the starting commit ref, or `nil` to compare
+    #   from the index
+    #
+    # @param to [String, nil] the ending commit ref, or `nil` to compare to
+    #   the working tree
+    #
+    # @return [void]
+    #
     def initialize(base, from = nil, to = nil)
       @base = base
       @from = from&.to_s
@@ -16,7 +43,18 @@ module Git
       @path = nil
       @full_diff_files = nil
     end
-    attr_reader :from, :to
+
+    # The starting commit ref
+    #
+    # @return [String, nil] the starting commit ref, or `nil` if not set
+    #
+    attr_reader :from
+
+    # The ending commit ref
+    #
+    # @return [String, nil] the ending commit ref, or `nil` if not set
+    #
+    attr_reader :to
 
     # Limits the diff to the specified path(s)
     #
@@ -33,8 +71,11 @@ module Git
     # @example Remove path filtering (show all files)
     #   diff.path  # or diff.path(nil)
     #
-    # @param paths [String, Pathname] one or more paths to filter the diff. Pass no arguments to remove filtering.
+    # @param paths [String, Pathname] one or more paths to filter the diff;
+    #   pass no arguments to remove filtering
+    #
     # @return [self] returns self for method chaining
+    #
     # @raise [ArgumentError] if any path is an Array (use splatted arguments instead)
     #
     def path(*paths)
@@ -53,21 +94,69 @@ module Git
       self
     end
 
+    # Returns the full diff output as a string
+    #
+    # @example
+    #   diff.patch # => "diff --git a/file.rb b/file.rb\n..."
+    #
+    # @return [String] the raw output of `git diff`
+    #
     def patch
-      @base.lib.diff_full(@from, @to, { path_limiter: @path })
+      if @base.respond_to?(:diff_full)
+        @base.diff_full(@from, @to, path_limiter: @path)
+      else
+        @base.lib.diff_full(@from, @to, { path_limiter: @path })
+      end
     end
     alias to_s patch
 
+    # Returns the diff file info for the given path
+    #
+    # @example
+    #   diff['lib/git.rb'] # => #<Git::Diff::DiffFile ...>
+    #
+    # @param key [String] the file path to look up
+    #
+    # @return [Git::Diff::DiffFile] the diff file object for the given path
+    #
     def [](key)
       process_full
       @full_diff_files.assoc(key)[1]
     end
 
+    # Iterates over each changed file in the diff
+    #
+    # @overload each
+    #   @example Get an enumerator
+    #     diff.each.map(&:path) # => ["lib/git.rb", "README.md"]
+    #
+    #   @return [Enumerator<Git::Diff::DiffFile>] an enumerator over the
+    #     changed files
+    #
+    # @overload each(&block)
+    #   @example Iterate with a block
+    #     diff.each { |file| puts file.path }
+    #
+    #   @yield [file] each changed file in the diff
+    #
+    #   @yieldparam file [Git::Diff::DiffFile] a changed file
+    #
+    #   @yieldreturn [void]
+    #
+    #   @return [Array<Git::Diff::DiffFile>] the array of changed files
+    #
     def each(&)
       process_full
       @full_diff_files.map { |file| file[1] }.each(&)
     end
 
+    # Returns the number of changed files in the diff
+    #
+    # @example
+    #   diff.size # => 3
+    #
+    # @return [Integer] the number of changed files
+    #
     def size
       stats_provider.total[:files]
     end
@@ -76,22 +165,61 @@ module Git
     # DEPRECATED METHODS
     #
 
+    # Returns the path-to-status hash for all changed files in the diff
+    #
+    # @example
+    #   diff.name_status # => { "lib/git.rb" => "M", "README.md" => "A" }
+    #
+    # @return [Hash<String, String>] map of file path to git status letter
+    #
     def name_status
       path_status_provider.to_h
     end
 
+    # Returns the total number of changed lines in the diff
+    #
+    # @example
+    #   diff.lines # => 42
+    #
+    # @return [Integer] the total number of inserted and deleted lines
+    #
     def lines
       stats_provider.lines
     end
 
+    # Returns the total number of deleted lines in the diff
+    #
+    # @example
+    #   diff.deletions # => 10
+    #
+    # @return [Integer] the number of deleted lines
+    #
     def deletions
       stats_provider.deletions
     end
 
+    # Returns the total number of inserted lines in the diff
+    #
+    # @example
+    #   diff.insertions # => 32
+    #
+    # @return [Integer] the number of inserted lines
+    #
     def insertions
       stats_provider.insertions
     end
 
+    # Returns a statistics hash for the diff
+    #
+    # @example
+    #   diff.stats
+    #   # => {
+    #   #   files: { "lib/git.rb" => { insertions: 5, deletions: 2 } },
+    #   #   total: { insertions: 5, deletions: 2, lines: 7 }
+    #   # }
+    #
+    # @return [Hash] statistics including per-file and total insert/delete counts
+    #
     def stats
       {
         files: stats_provider.files,
@@ -99,13 +227,72 @@ module Git
       }
     end
 
-    # The changes for a single file within a diff
+    # Information about a single changed file within a {Git::Diff}
+    #
+    # @example Access diff file information
+    #   diff.each do |file|
+    #     puts file.path
+    #     puts file.binary? ? 'binary' : file.patch
+    #   end
+    #
+    # @api public
+    #
     class DiffFile
-      attr_accessor :patch, :path, :mode, :src, :dst, :type
+      # The raw diff patch text for this file
+      #
+      # @return [String, nil] the patch text
+      #
+      attr_accessor :patch
+
+      # The file path relative to the repository root
+      #
+      # @return [String, nil] the file path
+      #
+      attr_accessor :path
+
+      # The file mode
+      #
+      # @return [String] the octal file mode (e.g. `"100644"`)
+      #
+      attr_accessor :mode
+
+      # The source (pre-change) blob SHA
+      #
+      # @return [String] the source blob SHA
+      #
+      attr_accessor :src
+
+      # The destination (post-change) blob SHA
+      #
+      # @return [String] the destination blob SHA
+      #
+      attr_accessor :dst
+
+      # The type of change
+      #
+      # @return [String] the change type (e.g. `"modified"`, `"new"`, `"deleted"`)
+      #
+      attr_accessor :type
 
       @base = nil
+
+      # Regexp matching a nil blob SHA (all-zero hash of 4 to 40 hex digits)
       NIL_BLOB_REGEXP = /\A0{4,40}\z/
 
+      # Creates a new DiffFile from parsed diff data
+      #
+      # @example
+      #   file = Git::Diff::DiffFile.new(base,
+      #     patch: "diff --git ...", path: 'lib/git.rb',
+      #     mode: '100644', src: 'abc123', dst: 'def456',
+      #     type: 'modified', binary: false)
+      #
+      # @param base [Git::Base, Git::Repository] the git repository
+      #
+      # @param hash [Hash] the parsed diff attributes
+      #
+      # @return [void]
+      #
       def initialize(base, hash)
         @base = base
         @patch = hash[:patch]
@@ -117,10 +304,31 @@ module Git
         @binary = hash[:binary]
       end
 
+      # Returns true if this file is a binary file
+      #
+      # @example
+      #   diff['path/to/image.png'].binary? # => true
+      #
+      # @return [Boolean] `true` if the file is binary, `false` otherwise
+      #
       def binary?
         !!@binary
       end
 
+      # Returns the blob object for this file
+      #
+      # @example Retrieve the destination blob
+      #   file.blob       # => #<Git::Object::Blob ...>
+      #
+      # @example Retrieve the source blob
+      #   file.blob(:src) # => #<Git::Object::Blob ...>
+      #
+      # @param type [Symbol] `:src` to retrieve the source blob, or `:dst`
+      #   (default) for the destination blob
+      #
+      # @return [Git::Object::Blob, nil] the blob object, or `nil` if the blob
+      #   SHA is the null SHA
+      #
       def blob(type = :dst)
         if type == :src && !NIL_BLOB_REGEXP.match(@src)
           @base.object(@src)
@@ -132,6 +340,14 @@ module Git
 
     private
 
+    # Validates that no path argument is an Array
+    #
+    # @param paths [Array] the raw paths array passed to {#path}
+    #
+    # @return [void]
+    #
+    # @raise [ArgumentError] if any element of paths is an Array
+    #
     def validate_paths_not_arrays(paths)
       return unless paths.any?(Array)
 
@@ -140,27 +356,58 @@ module Git
             "Use path('lib/', 'docs/') not path(['lib/', 'docs/'])"
     end
 
+    # Triggers full diff processing if not yet done
+    #
+    # @return [void]
+    #
     def process_full
       return if @full_diff_files
 
       @full_diff_files = process_full_diff
     end
 
+    # Returns a memoized DiffPathStatus provider for this diff
+    #
+    # @return [Git::DiffPathStatus] the path status provider
+    #
     def path_status_provider
       @path_status_provider ||= Git::DiffPathStatus.new(@base, @from, @to, @path)
     end
 
+    # Returns a memoized DiffStats provider for this diff
+    #
+    # @return [Git::DiffStats] the stats provider
+    #
     def stats_provider
       @stats_provider ||= Git::DiffStats.new(@base, @from, @to, @path)
     end
 
+    # Parses the full diff output into DiffFile objects
+    #
+    # @return [Array<Array(String, Git::Diff::DiffFile)>] list of
+    #   `[filename, DiffFile]` pairs
+    #
     def process_full_diff
       FullDiffParser.new(@base, patch).parse
     end
 
-    # A private parser class to process the output of `git diff`
+    # Private parser for `git diff` output
+    #
+    # @example Parse a diff patch
+    #   parser = Git::Diff::FullDiffParser.new(base, patch_text)
+    #   files = parser.parse
+    #
     # @api private
+    #
     class FullDiffParser
+      # Creates a new FullDiffParser
+      #
+      # @param base [Git::Base, Git::Repository] the git repository
+      #
+      # @param patch_text [String] the raw `git diff` output to parse
+      #
+      # @return [void]
+      #
       def initialize(base, patch_text)
         @base = base
         @patch_text = patch_text
@@ -169,6 +416,11 @@ module Git
         @defaults = { mode: '', src: '', dst: '', type: 'modified', binary: false }
       end
 
+      # Parses the diff text into a list of filename/DiffFile pairs
+      #
+      # @return [Array<Array(String, Git::Diff::DiffFile)>] list of
+      #   `[filename, DiffFile]` pairs
+      #
       def parse
         @patch_text.split("\n").each { |line| process_line(line) }
         @final_files.map { |filename, data| [filename, DiffFile.new(@base, data)] }
@@ -176,6 +428,12 @@ module Git
 
       private
 
+      # Dispatches a single diff line to the appropriate handler
+      #
+      # @param line [String] a line from the diff output
+      #
+      # @return [void]
+      #
       def process_line(line)
         if (new_file_match = line.match(%r{\Adiff --git ("?)a/(.+?)\1 ("?)b/(.+?)\3\z}))
           start_new_file(new_file_match, line)
@@ -184,12 +442,26 @@ module Git
         end
       end
 
+      # Starts tracking a new file from a diff header line
+      #
+      # @param match [MatchData] the regex match from the diff header line
+      #
+      # @param line [String] the original diff header line
+      #
+      # @return [void]
+      #
       def start_new_file(match, line)
         filename = Git::EscapedPath.new(match[2]).unescape
         @current_file_data = @defaults.merge({ patch: line, path: filename })
         @final_files[filename] = @current_file_data
       end
 
+      # Appends a diff line to the current file's accumulated data
+      #
+      # @param line [String] a diff line to append
+      #
+      # @return [void]
+      #
       def append_to_current_file(line)
         return unless @current_file_data
 
@@ -200,6 +472,12 @@ module Git
         @current_file_data[:patch] << "\n#{line}"
       end
 
+      # Parses an index line to extract source and destination blob SHAs
+      #
+      # @param line [String] a diff line that may be an index line
+      #
+      # @return [void]
+      #
       def parse_index_line(line)
         return unless (match = line.match(/^index ([0-9a-f]{4,40})\.\.([0-9a-f]{4,40})( ......)*/))
 
@@ -208,6 +486,12 @@ module Git
         @current_file_data[:mode] = match[3].strip if match[3]
       end
 
+      # Parses a file mode line to extract the change type and file mode
+      #
+      # @param line [String] a diff line that may be a file mode line
+      #
+      # @return [void]
+      #
       def parse_file_mode_line(line)
         return unless (match = line.match(/^([[:alpha:]]*?) file mode (......)/))
 
@@ -215,6 +499,12 @@ module Git
         @current_file_data[:mode] = match[2]
       end
 
+      # Marks the current file as binary if this is a binary diff line
+      #
+      # @param line [String] a diff line to check for the binary file marker
+      #
+      # @return [void]
+      #
       def check_for_binary(line)
         @current_file_data[:binary] = true if line.match?(/^Binary files /)
       end