git 1.19.1 → 5.5.0

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 private
+    #
+    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,410 @@
+# 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 private
+    #
+    module Logging
+      # Allowed option keys for {#full_log_commits}
+      #
+      # @return [Array<Symbol>] the supported option keys
+      #
+      FULL_LOG_COMMITS_ALLOWED_OPTS = %i[
+        count all cherry since until grep author between object path_limiter skip merges perl_regexp
+      ].freeze
+      private_constant :FULL_LOG_COMMITS_ALLOWED_OPTS
+
+      # Returns commits within the given revision range
+      #
+      # @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, String), nil] :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>, nil] :path_limiter (nil)
+      #   only include commits that impact files from the specified path(s)
+      #
+      # @option opts [Integer, nil] :skip (nil) skip this many commits before output
+      #
+      # @option opts [Boolean, nil] :merges (nil) include only merge commits
+      #
+      # @option opts [Boolean, nil] :perl_regexp (nil) interpret the `:grep` and
+      #   `:author` patterns as Perl-compatible regular expressions (PCRE) instead of
+      #   git's default POSIX basic regular expressions
+      #
+      #   Requires a git built with PCRE support; git otherwise fails with
+      #   "cannot use Perl-compatible regexes...".
+      #
+      # @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
+      #
+      # @note On Git for Windows, git's default regex engine matches *bytes* rather
+      #   than characters, so a metacharacter such as `.` or a POSIX class such as
+      #   `[[:alpha:]]` never matches a whole multi-byte character in a `:grep` or
+      #   `:author` pattern. The match fails silently: git exits zero and the result
+      #   is empty. Pass `perl_regexp: true` to select PCRE, which does match
+      #   characters. PCRE is a different dialect than git's default, so this is a
+      #   deliberate choice by the caller rather than a transparent substitution.
+      #
+      # @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
+
+        # Log option keys forwarded to {Git::Commands::Log#call} under the same name
+        #
+        # The remaining options are renamed or reshaped by {#log_base_call_options}.
+        #
+        # @return [Array<Symbol>] the pass-through option keys
+        #
+        PASSTHROUGH_LOG_OPTS = %i[all cherry since until grep author perl_regexp].freeze
+
+        # Validates the :count log option
+        #
+        # @param opts [Hash] the log options
+        #
+        # @option opts [Integer, nil] :count (nil) the maximum number of commits to
+        #   return
+        #
+        # @return [void]
+        #
+        # @raise [ArgumentError] if the log count option is not an Integer
+        #
+        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
+
+        # Validates the :between log option
+        #
+        # @param opts [Hash] the log options
+        #
+        # @option opts [Array(String, String), nil] :between (nil) the two-commit
+        #   revision range to validate
+        #
+        # @return [void]
+        #
+        # @raise [ArgumentError] if the :between option is not an Array with exactly
+        #   two non-nil values
+        #
+        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
+
+        # Builds positional revision arguments for `git log`
+        #
+        # @param opts [Hash] the log options
+        #
+        # @option opts [Array(String, String), nil] :between (nil) a two-revision
+        #   range where index `0` is the start and index `1` is the end
+        #
+        # @option opts [String, nil] :object (nil) a single revision range expression
+        #
+        # @return [Array<String>] zero or one positional revision arguments
+        #
+        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
+
+        # Builds keyword options passed to {Git::Commands::Log#call}
+        #
+        # @param opts [Hash] the log options
+        #
+        # @param extra [Hash] additional keyword options merged into the call options
+        #
+        # @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, nil] :since (nil) include commits newer than this date
+        #   expression
+        #
+        # @option opts [String, nil] :until (nil) include commits older than this date
+        #   expression
+        #
+        # @option opts [String, nil] :grep (nil) only include commits whose message
+        #   matches this pattern
+        #
+        # @option opts [String, nil] :author (nil) only include commits whose author
+        #   matches this pattern
+        #
+        # @option opts [Boolean, nil] :perl_regexp (nil) interpret the `:grep` and
+        #   `:author` patterns as Perl-compatible regular expressions
+        #
+        # @option opts [Integer, nil] :count (nil) maximum number of commits to return
+        #
+        # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
+        #   only include commits that impact files from the specified path(s)
+        #
+        # @option extra [Integer, nil] :skip (nil) skip this many commits before output
+        #
+        # @option extra [Boolean, nil] :merges (nil) include only merge commits
+        #
+        # @return [Hash] keyword options for {Git::Commands::Log#call}
+        #
+        def log_base_call_options(opts, extra = {})
+          opts
+            .slice(*PASSTHROUGH_LOG_OPTS)
+            .merge(
+              max_count: opts[:count],
+              path: opts[:path_limiter] ? Array(opts[:path_limiter]) : nil
+            )
+            .merge(extra)
+            .compact
+        end
+
+        # Executes git log and parses the raw output
+        #
+        # @param execution_context [Git::ExecutionContext] the execution context
+        #
+        # @param revision_range_args [Array<String>] positional revision range arguments
+        #
+        # @param call_opts [Hash] keyword options for {Git::Commands::Log#call}
+        #
+        # @return [Array<Hash>] parsed commits from the command output
+        #
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        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
+
+        # Returns an empty result when the repository has no commits yet
+        #
+        # @return [Array<Hash>] parsed commits or an empty array for unborn repositories
+        #
+        # @raise [Git::FailedError] if git fails for a reason other than unborn history
+        #
+        # @yield [] runs the wrapped log command
+        #
+        # @yieldreturn [Array<Hash>] the parsed commits from the wrapped command
+        #
+        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
+          # Initializes a parser for raw git log output lines
+          #
+          # @param lines [Array<String>] raw output lines from `git log --pretty=raw`
+          #
+          # @return [void]
+          #
+          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
+
+          # Routes a raw line to message or metadata parsing
+          #
+          # @param line [String] the current raw log output line
+          #
+          # @return [void]
+          #
+          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
+
+          # Appends a commit message line to the current commit buffer
+          #
+          # @param line [String] an indented message line from raw output
+          #
+          # @return [void]
+          #
+          def process_message_line(line)
+            @current_commit['message'] << "#{line[4..]}\n"
+          end
+
+          # Parses metadata lines and multi-line metadata continuations
+          #
+          # @param line [String] a metadata line from raw output
+          #
+          # @return [void]
+          #
+          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
+
+          # Applies a metadata key/value pair to the current commit
+          #
+          # @param key [String] the metadata key from the raw log line
+          #
+          # @param value [String] the parsed metadata value
+          #
+          # @return [void]
+          #
+          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
+
+          # Starts a new commit record in the parser state
+          #
+          # @param sha [String] the commit SHA for the new record
+          #
+          # @return [void]
+          #
+          def start_new_commit(sha)
+            finalize_commit
+            @current_commit = { 'sha' => sha, 'message' => +'', 'parent' => [] }
+            @last_metadata_key = nil
+          end
+
+          # Appends the current commit to the parsed results when present
+          #
+          # @return [void]
+          #
+          def finalize_commit
+            @commits << @current_commit if @current_commit
+          end
+        end
+        private_constant :RawLogParser
+      end
+      private_constant :Private
+    end
+  end
+end