git 4.3.2 → 5.0.0.beta.2

data/lib/git/repository/inspecting.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require 'git/commands/describe'
+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
+      # Give a human-readable name to a commit based on the most recent reachable tag
+      #
+      # Runs `git describe` to find the nearest tag reachable from `committish` and
+      # formats a version string. When the tag points directly at the commit, only the
+      # tag name is shown. Otherwise, the tag name is suffixed with the number of
+      # additional commits and the abbreviated commit SHA (e.g. `v1.0.0-3-gabcdef1`).
+      #
+      # @example Describe HEAD
+      #   repo.describe #=> "v1.0.0"
+      #
+      # @example Describe a specific commit
+      #   repo.describe('abc123') #=> "v1.0.0-3-gabcdef1"
+      #
+      # @example Describe using any tag (not just annotated tags)
+      #   repo.describe(nil, tags: true) #=> "v1.0.0-lightweight"
+      #
+      # @example Require an exact tag match
+      #   repo.describe(nil, exact_match: true)
+      #
+      # @example Use the legacy hyphenated key (still accepted)
+      #   repo.describe(nil, :'exact-match' => true)
+      #
+      # @param committish [String, nil] the commit-ish to describe; defaults to HEAD
+      #   when `nil`
+      #
+      # @param opts [Hash] options forwarded to `git describe`
+      #
+      # @option opts [Boolean, nil] :all (nil) use any ref in `refs/`, not just tags
+      #
+      # @option opts [Boolean, nil] :tags (nil) use lightweight tags as well as
+      #   annotated ones
+      #
+      # @option opts [Boolean, nil] :contains (nil) describe the tag that contains the
+      #   commit, rather than the nearest reachable one
+      #
+      # @option opts [Boolean, String, nil] :abbrev (nil) number of hex digits for the
+      #   abbreviated object name; `true` uses git's default length
+      #
+      # @option opts [Boolean, String, nil] :dirty (nil) append a dirty-state mark to
+      #   the description; `true` appends `-dirty`, a String appends that string
+      #
+      # @option opts [Boolean, String, nil] :broken (nil) like `:dirty` but treats
+      #   broken repository links as dirty
+      #
+      # @option opts [Integer, String, nil] :candidates (nil) number of candidate tags
+      #   to consider; increasing above 10 may yield a more accurate result
+      #
+      # @option opts [Boolean, nil] :exact_match (nil) only succeed when the commit is
+      #   pointed to by a tag directly (no suffix)
+      #
+      #   The legacy hyphenated key `:"exact-match"` is also accepted and is
+      #   automatically translated to `:exact_match`.
+      #
+      # @option opts [Boolean, nil] :debug (nil) verbosely display the search strategy
+      #
+      # @option opts [Boolean, nil] :long (nil) always output the long format even when
+      #   the commit matches a tag exactly
+      #
+      # @option opts [String, Array<String>, nil] :match (nil) only consider tags
+      #   matching the given `glob(7)` pattern; pass an array for multiple patterns
+      #
+      # @option opts [String, Array<String>, nil] :exclude (nil) do not consider tags
+      #   matching the given `glob(7)` pattern; pass an array for multiple patterns
+      #
+      # @option opts [Boolean, nil] :always (nil) show the abbreviated commit SHA as
+      #   fallback when the commit cannot be described
+      #
+      # @option opts [Boolean, nil] :first_parent (nil) follow only the first parent of
+      #   merge commits when searching for the nearest tag
+      #
+      # @return [String] the human-readable description of the commit, with trailing
+      #   newlines preserved
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      # @raise [ArgumentError] when `committish` looks like a command-line flag (starts
+      #   with `-`), or when `opts` contains any key not in the documented option list
+      #
+      def describe(committish = nil, opts = {})
+        raise ArgumentError, "Invalid commit-ish object: '#{committish}'" if committish&.start_with?('-')
+
+        opts = opts.dup
+        if opts.key?(:'exact-match')
+          opts[:exact_match] ||= opts[:'exact-match']
+          opts.delete(:'exact-match')
+        end
+        SharedPrivate.assert_valid_opts!(DESCRIBE_ALLOWED_OPTS, **opts)
+        commit_ishes = Array(committish).compact
+        Git::Commands::Describe.new(@execution_context).call(*commit_ishes, **opts).stdout
+      end
+
+      # 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 {#describe}
+      DESCRIBE_ALLOWED_OPTS = %i[
+        all tags contains abbrev dirty broken candidates
+        exact_match debug long match exclude always first_parent
+      ].freeze
+      private_constant :DESCRIBE_ALLOWED_OPTS
+
+      # 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/maintenance.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'git/commands/gc'
+require 'git/commands/repack'
+
+module Git
+  class Repository
+    # Facade methods for repository maintenance and optimization operations
+    #
+    # These methods pack objects, compress history, prune unreachable objects, and
+    # otherwise keep the repository in good health.
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api public
+    #
+    module Maintenance
+      # Repack loose objects into pack files
+      #
+      # Packs all unpacked objects and removes redundant pack files. This is
+      # equivalent to running `git repack -a -d`, which packs all objects into a
+      # single pack and deletes any packs that become redundant.
+      #
+      # This method uses the fixed options `a: true, d: true` (matching the 4.x
+      # behavior). No additional options are exposed.
+      #
+      # @example Repack the repository
+      #   repo.repack
+      #
+      # @return [String] the stdout from `git repack`. Git writes all progress
+      #   and summary output to stderr, so the returned string is typically empty.
+      #   Returns `String` to match the 4.x public contract (`Git::Lib#command`
+      #   returned `result.stdout`).
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def repack
+        Git::Commands::Repack.new(@execution_context).call(a: true, d: true).stdout
+      end
+
+      # Run garbage collection to optimize and clean up the repository
+      #
+      # Runs `git gc` to perform housekeeping tasks including object compression,
+      # pruning of unreachable objects, and ref packing. This is equivalent to
+      # running `git gc --prune --aggressive --auto`.
+      #
+      # This method uses the fixed options `prune: true, aggressive: true, auto: true`
+      # (matching the 4.x behavior). No additional options are exposed.
+      #
+      # @example Run garbage collection
+      #   repo.gc
+      #
+      # @return [String] the stdout from `git gc`. Git writes all progress
+      #   and summary output to stderr, so the returned string is typically empty.
+      #   Returns `String` to match the 4.x public contract (`Git::Lib#command`
+      #   returned `result.stdout`).
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def gc
+        Git::Commands::Gc.new(@execution_context).call(prune: true, aggressive: true, auto: true).stdout
+      end
+    end
+  end
+end