git 4.3.2 → 5.0.0.beta.1

data/lib/git/repository/inspecting.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'git/commands/fsck'
+require 'git/commands/show'
+require 'git/parsers/fsck'
+require 'git/repository/shared_private'
+
+module Git
+  class Repository
+    # Facade methods for read-only repository inspection operations
+    #
+    # These methods report on the contents and integrity of the repository.
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api public
+    #
+    module Inspecting
+      # Show a single git object (a commit, tag, tree, or blob)
+      #
+      # @example Show the HEAD commit
+      #   repo.show
+      #
+      # @example Show a specific commit
+      #   repo.show('HEAD~1')
+      #
+      # @example Show the contents of a file at a revision
+      #   repo.show('HEAD', 'README.md')
+      #
+      # @param objectish [String, nil] the object to show; a ref, SHA, or
+      #   `objectish:path` expression
+      #
+      #   Defaults to `HEAD` when `nil`.
+      #
+      # @param path [String, nil] the file whose contents to show at `objectish`,
+      #   when given
+      #
+      #   Combined with `objectish` as `objectish:path`. When `objectish` is `nil`
+      #   and `path` is given, `HEAD` is used as the objectish, so
+      #   `show(nil, 'README.md')` resolves to `HEAD:README.md`.
+      #
+      # @return [String] git's stdout from the show, with trailing newlines
+      #   preserved
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def show(objectish = nil, path = nil)
+        object = path ? "#{objectish || 'HEAD'}:#{path}" : objectish
+        Git::Commands::Show.new(@execution_context).call(*[object].compact).stdout
+      end
+
+      # Option keys accepted by {#fsck}
+      #
+      # `:progress`/`:no_progress` are intentionally excluded: progress output is
+      # always suppressed (see {#fsck}), so callers may not toggle it.
+      FSCK_ALLOWED_OPTS = %i[
+        tags root unreachable cache no_reflogs
+        full no_full strict verbose lost_found dangling no_dangling
+        connectivity_only name_objects no_name_objects references no_references
+      ].freeze
+      private_constant :FSCK_ALLOWED_OPTS
+
+      # Verify the connectivity and validity of the objects in the database
+      #
+      # Runs `git fsck` and returns the categorized objects it flags. Progress
+      # output is always suppressed (`--no-progress`) so that stdout contains only
+      # the machine-parsable findings.
+      #
+      # @overload fsck(*objects, **options)
+      #
+      #   @example Check repository integrity
+      #     result = repo.fsck
+      #     result.dangling.each { |obj| puts "#{obj.type}: #{obj.oid}" }
+      #
+      #   @example Check if the repository is clean
+      #     repo.fsck.empty? #=> true
+      #
+      #   @example List root commits
+      #     repo.fsck(root: true).root.each { |obj| puts obj.oid }
+      #
+      #   @example Check specific objects
+      #     repo.fsck('abc1234', 'def5678')
+      #
+      #   @param objects [Array<String>] specific objects to treat as heads for the
+      #     unreachability trace
+      #
+      #     When none are given, git fsck defaults to the index file, all refs, and
+      #     all reflogs.
+      #
+      #   @param options [Hash] options for the fsck command
+      #
+      #   @option options [Boolean, nil] :tags (nil) report tags
+      #
+      #   @option options [Boolean, nil] :root (nil) report root nodes
+      #
+      #   @option options [Boolean, nil] :unreachable (nil) print objects that exist
+      #     but are not reachable from any reference node
+      #
+      #   @option options [Boolean, nil] :cache (nil) consider objects recorded in the
+      #     index as head nodes for reachability
+      #
+      #   @option options [Boolean, nil] :no_reflogs (nil) do not consider commits
+      #     referenced only by reflogs to be reachable
+      #
+      #   @option options [Boolean, nil] :full (nil) also check alternate object
+      #     pools and packed archives, not just the local store
+      #
+      #   @option options [Boolean, nil] :no_full (nil) skip alternate object pools and
+      #     packed archives
+      #
+      #   @option options [Boolean, nil] :strict (nil) enable stricter checking
+      #
+      #   @option options [Boolean, nil] :verbose (nil) be chatty
+      #
+      #   @option options [Boolean, nil] :lost_found (nil) write dangling objects
+      #     into `.git/lost-found`
+      #
+      #     This modifies the repository by creating files.
+      #
+      #   @option options [Boolean, nil] :dangling (nil) print dangling objects
+      #
+      #   @option options [Boolean, nil] :no_dangling (nil) suppress dangling object
+      #     reporting
+      #
+      #   @option options [Boolean, nil] :connectivity_only (nil) check only
+      #     connectivity; faster but does not validate blob content
+      #
+      #   @option options [Boolean, nil] :name_objects (nil) show the name of each
+      #     reachable object alongside its identifier
+      #
+      #   @option options [Boolean, nil] :no_name_objects (nil) suppress object name
+      #     display
+      #
+      #   @option options [Boolean, nil] :references (nil) check reference database
+      #     consistency
+      #
+      #   @option options [Boolean, nil] :no_references (nil) skip reference checking
+      #
+      #   @return [Git::FsckResult] the objects flagged by fsck, categorized by status
+      #
+      #   @raise [ArgumentError] when unsupported options are provided
+      #
+      #   @raise [Git::FailedError] when git exits outside the allowed range (exit
+      #     code > 7)
+      #
+      def fsck(*objects, **)
+        SharedPrivate.assert_valid_opts!(FSCK_ALLOWED_OPTS, **)
+        result = Git::Commands::Fsck.new(@execution_context).call(*objects, **, no_progress: true)
+        Git::Parsers::Fsck.parse(result.stdout)
+      end
+    end
+  end
+end

data/lib/git/repository/logging.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'git/commands/log'
+require 'git/log'
+require 'git/repository/shared_private'
+
+module Git
+  class Repository
+    # Facade methods for querying commit history
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api public
+    #
+    module Logging
+      FULL_LOG_COMMITS_ALLOWED_OPTS = %i[
+        count all cherry since until grep author between object path_limiter skip merges
+      ].freeze
+      private_constant :FULL_LOG_COMMITS_ALLOWED_OPTS
+
+      # 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 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
+      #
+      #   @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] :cherry (nil) omit commits equivalent to cherry-picked commits
+      #
+      #   @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] :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 [Array<String>] :between (nil) revision range as two commit-ish values
+      #
+      #     When both `:between` and `:object` are provided, `:between` takes precedence.
+      #
+      #   @option opts [String] :object (nil) single revision range expression for git log
+      #
+      #     Ignored when `:between` is provided.
+      #
+      #   @option opts [String, Pathname, Array<String, Pathname>] :path_limiter (nil)
+      #     only include commits that impact files from the specified path(s)
+      #
+      #   @option opts [Integer] :skip (nil) skip this many commits before output
+      #
+      #   @option opts [Boolean, nil] :merges (nil) include only merge commits
+      #
+      #   @return [Array<Hash>] the parsed raw log output for each commit
+      #
+      #   @raise [ArgumentError] if unsupported options are provided
+      #
+      #   @raise [ArgumentError] if `:count` is not an Integer
+      #
+      #   @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      #   @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)
+        Private.validate_log_count_option!(opts)
+        Private.validate_log_between_option!(opts)
+
+        call_opts = Private.log_base_call_options(opts, skip: opts[:skip], merges: opts[:merges])
+        revision_range_args = Private.log_revision_range_args(opts)
+        Private.run_log_command(@execution_context, revision_range_args, call_opts)
+      end
+
+      # Returns a new {Git::Log} query builder scoped to this repository
+      #
+      # @example Build a log query and execute it
+      #   results = repo.log(50).author('Alice').since('2 weeks ago').execute
+      #   results.each { |commit| puts commit.sha }
+      #
+      # @param count [Integer, Symbol, nil] the maximum number of commits to return,
+      #   or `:all` / `nil` to return all commits; passed directly to {Git::Log#initialize}
+      #
+      # @return [Git::Log] a new log query builder
+      #
+      # @see Git::Log
+      #
+      def log(count = 30)
+        Git::Log.new(self, count)
+      end
+
+      # Internal helpers for {Logging} that should not be mixed into
+      # {Git::Repository} instances
+      #
+      # @api private
+      #
+      module Private
+        module_function
+
+        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
+
+        def validate_log_between_option!(opts)
+          between = opts[:between]
+          return if between.nil?
+          return if between.is_a?(Array) && between.length == 2 && between.none?(&:nil?)
+
+          raise ArgumentError,
+                "The log between option must be an Array with exactly two non-nil values but was #{between.inspect}"
+        end
+
+        def log_revision_range_args(opts)
+          if opts[:between]
+            ["#{opts[:between][0]}..#{opts[:between][1]}"]
+          elsif opts[:object].is_a?(String)
+            [opts[:object]]
+          else
+            []
+          end
+        end
+
+        def log_base_call_options(opts, extra = {})
+          {
+            all: opts[:all],
+            cherry: opts[:cherry],
+            since: opts[:since],
+            until: opts[:until],
+            grep: opts[:grep],
+            author: opts[:author],
+            max_count: opts[:count],
+            path: opts[:path_limiter] ? Array(opts[:path_limiter]) : nil
+          }.merge(extra).compact
+        end
+
+        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(
+              *revision_range_args,
+              no_color: true,
+              pretty: 'raw',
+              **call_opts
+            )
+            RawLogParser.new(result.stdout.split("\n")).parse
+          end
+        end
+
+        def log_or_empty_on_unborn
+          yield
+        rescue Git::FailedError => e
+          raise unless e.result.status.exitstatus == 128 &&
+                       e.result.stderr =~ /does not have any commits yet/
+
+          []
+        end
+
+        # Parser for `git log --pretty=raw` output into commit hashes
+        #
+        # @api private
+        #
+        class RawLogParser
+          def initialize(lines)
+            @lines = lines
+            @commits = []
+            @current_commit = nil
+            @in_message = false
+            @last_metadata_key = nil
+          end
+
+          # Parse raw `git log --pretty=raw` lines into commit hashes
+          #
+          # @return [Array<Hash>] the parsed commits in command output order
+          #
+          def parse
+            @lines.each { |line| process_line(line.chomp) }
+            finalize_commit
+            @commits
+          end
+
+          private
+
+          def process_line(line)
+            if line.empty?
+              @in_message = !@in_message
+              return
+            end
+
+            @in_message = false if @in_message && !line.start_with?('    ')
+
+            @in_message ? process_message_line(line) : process_metadata_line(line)
+          end
+
+          def process_message_line(line)
+            @current_commit['message'] << "#{line[4..]}\n"
+          end
+
+          def process_metadata_line(line)
+            if line.start_with?(' ') && @last_metadata_key
+              @current_commit[@last_metadata_key] << "\n#{line[1..]}"
+              return
+            end
+
+            key, *value = line.split
+            value = value.join(' ')
+            @last_metadata_key = nil
+            dispatch_metadata_key(key, value)
+          end
+
+          def dispatch_metadata_key(key, value)
+            case key
+            when 'commit'
+              start_new_commit(value)
+            when 'parent'
+              @current_commit['parent'] << value
+            else
+              @current_commit[key] = value
+              @last_metadata_key = key
+            end
+          end
+
+          def start_new_commit(sha)
+            finalize_commit
+            @current_commit = { 'sha' => sha, 'message' => +'', 'parent' => [] }
+            @last_metadata_key = nil
+          end
+
+          def finalize_commit
+            @commits << @current_commit if @current_commit
+          end
+        end
+        private_constant :RawLogParser
+      end
+      private_constant :Private
+    end
+  end
+end

data/lib/git/repository/merging.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require 'git/commands/diff'
+require 'git/commands/merge/start'
+require 'git/commands/merge_base'
+require 'git/commands/revert/start'
+require 'git/commands/show'
+require 'git/repository/shared_private'
+
+module Git
+  class Repository
+    # Facade methods for merge operations: merging branches into the current branch,
+    # and finding common ancestors between commits
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api public
+    #
+    module Merging
+      # Option keys accepted by {#merge}
+      #
+      # Derived from the 4.x option map for `Git::Lib#merge`.
+      MERGE_ALLOWED_OPTS = %i[no_commit no_ff m message].freeze
+      private_constant :MERGE_ALLOWED_OPTS
+
+      # Option keys accepted by {#merge_base}
+      #
+      # Derived from the 4.x option map for `Git::Lib#merge_base`.
+      MERGE_BASE_ALLOWED_OPTS = %i[octopus independent fork_point all].freeze
+      private_constant :MERGE_BASE_ALLOWED_OPTS
+
+      # Merge one or more branches into the current branch
+      #
+      # The merge commit message may be given by the message positional argument, the
+      # `:message` option, or the `:m` option; if more than one is provided, the
+      # precedence is positional argument > `:message` > `:m`.
+      #
+      # @example Merge a single branch
+      #   repo.merge('feature')
+      #
+      # @example Merge a branch with a no-fast-forward commit message
+      #   repo.merge('feature', 'Merge feature into main', no_ff: true)
+      #
+      # @example Octopus merge of multiple branches
+      #   repo.merge(%w[feature-a feature-b])
+      #
+      # @example Merge without committing
+      #   repo.merge('feature', nil, no_commit: true)
+      #
+      # @param branch [String, Array<String>, #to_s] the branch or branches to merge
+      #   into the current branch
+      #
+      #   When an Array is given, an octopus merge is performed; a {Git::Branch}
+      #   object is coerced to a String via `#to_s`.
+      #
+      # @param message [String, nil] optional commit message for the merge commit
+      #
+      #   Translated to the `-m` flag internally. For fast-forward merges git ignores
+      #   this value; use `no_ff: true` to ensure a merge commit is created and the
+      #   message is recorded.
+      #
+      # @param opts [Hash] additional options forwarded to `git merge`
+      #
+      # @option opts [Boolean, nil] :no_commit (nil) stop before creating the merge commit
+      #   (`--no-commit`)
+      #
+      # @option opts [Boolean, nil] :no_ff (nil) create a merge commit even when
+      #   fast-forward is possible (`--no-ff`)
+      #
+      # @option opts [String] :message (nil) commit message
+      #
+      #   Prefer the `:m` option instead of this one. Translated to the `-m` flag.
+      #   Identical to the positional `message` argument and the `:m` option.
+      #
+      # @option opts [String] :m (nil) commit message (`-m` flag)
+      #
+      # @return [String] git's stdout from the merge command
+      #
+      # @raise [ArgumentError] when unsupported options are provided
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def merge(branch, message = nil, opts = {})
+        SharedPrivate.assert_valid_opts!(MERGE_ALLOWED_OPTS, **opts)
+
+        # Dup so callers who reuse the same opts hash are not affected
+        opts = opts.dup
+
+        # Merge positional message into opts so the rest of the logic is uniform
+        opts[:message] = message if message
+
+        # git merge uses -m, not --message; translate the key
+        opts[:m] = opts.delete(:message) if opts.key?(:message)
+
+        branches = Array(branch).map(&:to_s)
+        Git::Commands::Merge::Start.new(@execution_context).call(*branches, no_edit: true, **opts).stdout
+      end
+
+      # Find common ancestor commit(s) for use in a merge
+      #
+      # @example Find the common ancestor of two branches
+      #   repo.merge_base('main', 'feature') #=> ["abc123def456..."]
+      #
+      # @example Find all common ancestors of two branches
+      #   repo.merge_base('branch-a', 'branch-b', all: true)
+      #
+      # @example Find the fork point of a branch (consults the reflog)
+      #   repo.merge_base('main', 'feature', fork_point: true)
+      #
+      # @example Find independent commits not reachable from each other
+      #   repo.merge_base('abc1234', 'main', 'feature', independent: true)
+      #
+      # @overload merge_base(*commits, options = {})
+      #
+      #   @param commits [Array<String>] two or more commit SHAs, branch names,
+      #     or refs to find the common ancestor(s) of
+      #
+      #   @param options [Hash] merge-base options
+      #
+      #   @option options [Boolean, nil] :octopus (nil) compute the best common
+      #     ancestor for an n-way merge (intersection of all merge bases)
+      #
+      #   @option options [Boolean, nil] :independent (nil) list commits not
+      #     reachable from any other; useful for finding minimal merge points
+      #
+      #   @option options [Boolean, nil] :fork_point (nil) find the fork point
+      #     where a branch diverged from another, consulting the reflog
+      #
+      #   @option options [Boolean, nil] :all (nil) output all merge bases instead
+      #     of just the first when multiple equally good bases exist
+      #
+      #   @return [Array<String>] commit SHAs of the common ancestor(s); empty
+      #     when no common ancestor exists or `--fork-point` finds none
+      #
+      #   @raise [ArgumentError] when unsupported options are provided
+      #
+      #   @raise [Git::FailedError] when `git merge-base` exits outside the
+      #     allowed range (exit code > 1)
+      #
+      def merge_base(*args)
+        opts = args.last.is_a?(Hash) ? args.pop : {}
+        SharedPrivate.assert_valid_opts!(MERGE_BASE_ALLOWED_OPTS, **opts)
+        result = Git::Commands::MergeBase.new(@execution_context).call(*args, **opts)
+        result.stdout.lines.map(&:strip).reject(&:empty?)
+      end
+
+      # Iterate over files with merge conflicts, yielding conflict details for each
+      #
+      # For each unmerged file, the staged content for both sides of the conflict
+      # (stage 2 "ours" and stage 3 "theirs") is written to temporary files whose
+      # paths are yielded alongside the file path. The temporary files are deleted
+      # automatically when the block returns.
+      #
+      # @example Inspect conflicting files
+      #   repo.each_conflict do |file, your_version, their_version|
+      #     puts "Conflict in #{file}"
+      #     puts "Your version:"
+      #     puts File.read(your_version)
+      #     puts "Their version:"
+      #     puts File.read(their_version)
+      #   end
+      #
+      # @return [Array<String>] the list of unmerged file paths
+      #
+      # @raise [Git::FailedError] when `git diff --cached` exits with a non-zero status
+      #
+      # @yield [file, your_version, their_version] passes conflict details for
+      #   each unmerged file
+      #
+      # @yieldparam file [String] path to the conflicting file, relative to the
+      #   working tree
+      #
+      # @yieldparam your_version [String] path to a temporary file containing the
+      #   stage-2 (ours) content for the conflicting file
+      #
+      # @yieldparam their_version [String] path to a temporary file containing the
+      #   stage-3 (theirs) content for the conflicting file
+      #
+      # @yieldreturn [void]
+      #
+      def each_conflict
+        Private.unmerged_paths(@execution_context).each do |file_path|
+          Private.write_staged_file(@execution_context, file_path, 2) do |your_file|
+            Private.write_staged_file(@execution_context, file_path, 3) do |their_file|
+              yield(file_path, your_file.path, their_file.path)
+            end
+          end
+        end
+      end
+
+      # Option keys accepted by {#revert}
+      #
+      # Derived from the 4.x option map for `Git::Lib#revert`.
+      REVERT_ALLOWED_OPTS = %i[no_edit].freeze
+      private_constant :REVERT_ALLOWED_OPTS
+
+      # Revert one or more existing commits by creating new commits that undo
+      # the changes those commits introduced
+      #
+      # The working tree must be clean before calling this method. By default
+      # the editor is suppressed (`--no-edit`) so the commit message is taken
+      # from git's default revert message without prompting.
+      #
+      # @example Revert the most recent commit
+      #   repo.revert('HEAD')
+      #
+      # @example Revert a specific commit by SHA
+      #   repo.revert('abc1234')
+      #
+      # @example Revert a range of commits
+      #   repo.revert('HEAD~3..HEAD~1')
+      #
+      # @example Revert without suppressing the editor
+      #   repo.revert('HEAD', no_edit: false)
+      #
+      # @param commitish [String, nil] the commit, ref, or rev range to revert;
+      #   see `gitrevisions(7)` for accepted forms; defaults to `'HEAD'` when
+      #   `nil`
+      #
+      # @param opts [Hash] additional options forwarded to `git revert`
+      #
+      # @option opts [Boolean, nil] :no_edit (true) suppress the commit-message
+      #   editor (`--no-edit`); pass `false` to open the editor
+      #
+      # @return [String] git's stdout from the revert command
+      #
+      # @raise [ArgumentError] when unsupported options are provided
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def revert(commitish = nil, opts = {})
+        commitish = 'HEAD' if commitish.nil?
+        SharedPrivate.assert_valid_opts!(REVERT_ALLOWED_OPTS, **opts)
+        opts = { no_edit: true }.merge(opts)
+        Git::Commands::Revert::Start.new(@execution_context).call(commitish, **opts).stdout
+      end
+
+      # Private helpers local to {Git::Repository::Merging}
+      #
+      # @api private
+      module Private
+        # Tempfile name prefixes for staged content, keyed by git stage index
+        STAGE_PREFIXES = { 2 => 'YOUR-', 3 => 'THEIR-' }.freeze
+
+        module_function
+
+        # Returns the list of file paths with unresolved merge conflicts
+        #
+        # @param execution_context [Git::ExecutionContext] the execution context
+        #   used to run git commands
+        #
+        # @return [Array<String>] unmerged file paths
+        #
+        # @api private
+        #
+        def unmerged_paths(execution_context)
+          result = Git::Commands::Diff.new(execution_context).call(cached: true)
+          result.stdout.split("\n").filter_map do |line|
+            ::Regexp.last_match(1) if line =~ /^\* Unmerged path (.*)/
+          end
+        end
+
+        # Creates a Tempfile with the staged content for `file_path` at `stage`
+        # and yields the open IO object to the block
+        #
+        # @param execution_context [Git::ExecutionContext] the execution context
+        #   used to run git commands
+        #
+        # @param file_path [String] repository-relative path to the conflicting file
+        #
+        # @param stage [Integer] git stage index (2 = ours, 3 = theirs)
+        #
+        # @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)
+          Tempfile.create([STAGE_PREFIXES[stage], File.basename(file_path)]) do |f|
+            Git::Commands::Show.new(execution_context).call(":#{stage}:#{file_path}", out: f)
+            f.flush
+            yield f
+          end
+        end
+      end
+      private_constant :Private
+    end
+  end
+end