git 5.0.0.beta.1 → 5.0.0.beta.2

data/lib/git/repository/inspecting.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'git/commands/describe'
 require 'git/commands/fsck'
 require 'git/commands/show'
 require 'git/parsers/fsck'
@@ -16,6 +17,97 @@ module Git
     # @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
@@ -49,6 +141,13 @@ module Git
         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

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

data/lib/git/repository/merging.rb

@@ -145,6 +145,24 @@ module Git
         result.stdout.lines.map(&:strip).reject(&:empty?)
       end
 
+      # Return the paths of files with unresolved merge conflicts
+      #
+      # @example List conflicting files after a failed merge
+      #   paths = repo.unmerged
+      #   # => ["config/settings.rb", "lib/git/base.rb"]
+      #   paths.each { |path| puts "Conflict in #{path}" }
+      #
+      # @return [Array<String>] repository-relative paths of files with unresolved
+      #   merge conflicts; empty array when the working tree has no conflicts
+      #
+      # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 2)
+      #
+      # @see #each_conflict
+      #
+      def unmerged
+        Private.unmerged_paths(@execution_context)
+      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
@@ -163,7 +181,8 @@ module Git
       #
       # @return [Array<String>] the list of unmerged file paths
       #
-      # @raise [Git::FailedError] when `git diff --cached` exits with a non-zero status
+      # @raise [Git::FailedError] when `git diff --cached` exits outside the
+      #   allowed range (exit code > 2)
       #
       # @yield [file, your_version, their_version] passes conflict details for
       #   each unmerged file
@@ -189,6 +208,49 @@ module Git
         end
       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.conflicts do |file, your_version, their_version|
+      #     puts "Conflict in #{file}"
+      #     puts File.read(your_version)
+      #     puts File.read(their_version)
+      #   end
+      #
+      # @return [Array<String>] the list of unmerged file paths
+      #
+      # @raise [Git::FailedError] when `git diff --cached` exits outside the
+      #   allowed range (exit code > 2)
+      #
+      # @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]
+      #
+      # @deprecated Use {#each_conflict} instead
+      #
+      def conflicts(&)
+        Git::Deprecation.warn(
+          'Git::Repository#conflicts is deprecated and will be removed in a future version. ' \
+          'Use Git::Repository#each_conflict instead.'
+        )
+        each_conflict(&)
+      end
+
       # Option keys accepted by {#revert}
       #
       # Derived from the 4.x option map for `Git::Lib#revert`.

data/lib/git/repository/object_operations.rb

@@ -89,6 +89,18 @@ module Git
         end
       end
 
+      # Alias for {#cat_file_contents}; retained for backward compatibility
+      #
+      # @see #cat_file_contents
+      alias cat_file cat_file_contents
+
+      # Alias for {#cat_file_contents}
+      #
+      # @deprecated Use {#cat_file_contents} instead
+      #
+      # @see #cat_file_contents
+      alias object_contents cat_file_contents
+
       # Returns the size of a git object in bytes
       #
       # @example Get the size of a commit object
@@ -113,6 +125,13 @@ module Git
         Git::Commands::CatFile::Raw.new(@execution_context).call(object, s: true).stdout.chomp.to_i
       end
 
+      # Alias for {#cat_file_size}
+      #
+      # @deprecated Use {#cat_file_size} instead
+      #
+      # @see #cat_file_size
+      alias object_size cat_file_size
+
       # Returns the type of a git object
       #
       # @example Get the type of a commit reference
@@ -138,6 +157,13 @@ module Git
         Git::Commands::CatFile::Raw.new(@execution_context).call(object, t: true).stdout.chomp
       end
 
+      # Alias for {#cat_file_type}
+      #
+      # @deprecated Use {#cat_file_type} instead
+      #
+      # @see #cat_file_type
+      alias object_type cat_file_type
+
       # Returns parsed commit data for the given git object
       #
       # @example Get commit data for HEAD
@@ -174,6 +200,13 @@ module Git
         Git::Parsers::CatFile.parse_commit(result.stdout.split("\n"), object)
       end
 
+      # Alias for {#cat_file_commit}
+      #
+      # @deprecated Use {#cat_file_commit} instead
+      #
+      # @see #cat_file_commit
+      alias commit_data cat_file_commit
+
       # Returns parsed tag data for the given annotated tag object
       #
       # Does not work with lightweight tags. To list all annotated tags in a
@@ -223,6 +256,13 @@ module Git
         Git::Parsers::CatFile.parse_tag(tdata, object)
       end
 
+      # Alias for {#cat_file_tag}
+      #
+      # @deprecated Use {#cat_file_tag} instead
+      #
+      # @see #cat_file_tag
+      alias tag_data cat_file_tag
+
       # Resolve a revision specifier to its full object ID
       #
       # Passes the given revision specifier to `git rev-parse` and returns the
@@ -252,6 +292,8 @@ module Git
         Git::Commands::RevParse.new(@execution_context).call(objectish, '--', revs_only: true).stdout
       end
 
+      alias revparse rev_parse
+
       # Returns the SHA of a named tag
       #
       # Returns an empty string when the tag does not exist.
@@ -353,6 +395,13 @@ module Git
         Git::Commands::NameRev.new(@execution_context).call(commit_ish).stdout.split[1]
       end
 
+      # Alias for {#name_rev}
+      #
+      # @deprecated Use {#name_rev} instead
+      #
+      # @see #name_rev
+      alias namerev name_rev
+
       # Option keys accepted by {#ls_tree}
       LS_TREE_ALLOWED_OPTS = %i[recursive path].freeze
       private_constant :LS_TREE_ALLOWED_OPTS
@@ -704,25 +753,25 @@ module Git
         Git::Parsers::Tag.parse_list(result.stdout).map { |info| tag(info.name) }
       end
 
-      # Option keys accepted by {#add_tag}
-      ADD_TAG_ALLOWED_OPTS = %i[
+      # Option keys accepted by {#tag_add}
+      TAG_ADD_ALLOWED_OPTS = %i[
         annotate a sign s no_sign local_user u force f message m file F
         edit e no_edit trailer cleanup create_reflog
       ].freeze
-      private_constant :ADD_TAG_ALLOWED_OPTS
+      private_constant :TAG_ADD_ALLOWED_OPTS
 
       # Create a new tag
       #
-      # @overload add_tag(name, options = {})
+      # @overload tag_add(name, options = {})
       #
       #   @example Create a lightweight tag on HEAD
-      #     repo.add_tag('v1.0.0')
+      #     repo.tag_add('v1.0.0')
       #
       #   @example Create an annotated tag on HEAD
-      #     repo.add_tag('v1.0.0', annotate: true, message: 'Release 1.0.0')
+      #     repo.tag_add('v1.0.0', annotate: true, message: 'Release 1.0.0')
       #
       #   @example Replace an existing tag on HEAD
-      #     repo.add_tag('v1.0.0', force: true)
+      #     repo.tag_add('v1.0.0', force: true)
       #
       #   @param name [String] the name of the tag to create
       #
@@ -779,13 +828,13 @@ module Git
       #
       #   @return [Git::Object::Tag] the newly created tag
       #
-      # @overload add_tag(name, target, options = {})
+      # @overload tag_add(name, target, options = {})
       #
       #   @example Create a lightweight tag on a specific commit
-      #     repo.add_tag('v1.0.0', 'abc123')
+      #     repo.tag_add('v1.0.0', 'abc123')
       #
       #   @example Create an annotated tag on a specific commit
-      #     repo.add_tag('v1.0.0', 'abc123', annotate: true, message: 'Release 1.0.0')
+      #     repo.tag_add('v1.0.0', 'abc123', annotate: true, message: 'Release 1.0.0')
       #
       #   @param name [String] the name of the tag to create
       #
@@ -796,20 +845,18 @@ module Git
       #
       #   @return [Git::Object::Tag] the newly created tag
       #
-      # @overload add_tag(name, delete: true)
+      # @overload tag_add(name, delete_options)
       #
-      #   @deprecated Use {#delete_tag} instead.
+      #   @deprecated Use {#tag_delete} instead.
       #
       #   @example Delete a tag (deprecated)
-      #     repo.add_tag('v1.0.0', d: true)
+      #     repo.tag_add('v1.0.0', d: true)
       #
       #   @param name [String] the name of the tag to delete
       #
-      #   @option options [Boolean, nil] :d (nil) delete the named tag
-      #     (alias: `:delete`); deprecated — use {#delete_tag} instead
-      #
-      #   @option options [Boolean, nil] :delete (nil) delete the named tag
-      #     (alias: `:d`); deprecated — use {#delete_tag} instead
+      #   @param delete_options [{ d: true }, { delete: true }] deletion options;
+      #     only `:d` or `:delete` (set to `true`) is accepted — no other keys
+      #     and no `target` argument may be combined with this form
       #
       #   @return [String] git's stdout from the delete
       #
@@ -825,23 +872,58 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      def add_tag(name, *options)
-        opts = options.last.is_a?(Hash) ? options.pop : {}
-        target = options.first
+      def tag_add(name, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        target = args.first
 
-        return Private.add_tag_delete_deprecated(self, name, target, opts) if opts[:d] || opts[:delete]
+        return Private.tag_add_delete_deprecated(self, name, target, options) if options[:d] || options[:delete]
 
-        opts = opts.except(:d, :delete)
-        SharedPrivate.assert_valid_opts!(ADD_TAG_ALLOWED_OPTS, **opts)
-        Private.validate_tag_options!(opts)
-        Git::Commands::Tag::Create.new(@execution_context).call(name, target, **opts)
+        options = options.except(:d, :delete)
+        SharedPrivate.assert_valid_opts!(TAG_ADD_ALLOWED_OPTS, **options)
+        Private.validate_tag_options!(options)
+        Git::Commands::Tag::Create.new(@execution_context).call(name, target, **options)
         tag(name)
       end
 
+      # @deprecated Use {#tag_add} instead.
+      #
+      # @overload add_tag(name, options = {})
+      #
+      #   @param name [String] the name of the tag to create
+      #
+      #   @param options [Hash] options for creating the tag
+      #
+      #   @return [Git::Object::Tag] the newly created tag
+      #
+      # @overload add_tag(name, target, options = {})
+      #
+      #   @param name [String] the name of the tag to create
+      #
+      #   @param target [String] the object to tag (commit SHA, branch name, etc.)
+      #
+      #   @param options [Hash] options for creating the tag
+      #
+      #   @return [Git::Object::Tag] the newly created tag
+      #
+      # @raise [ArgumentError] if unsupported options are provided
+      #
+      # @raise [ArgumentError] if an annotated or signed tag is requested without
+      #   a message
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      def add_tag(name, *options)
+        Git::Deprecation.warn(
+          'Git::Repository#add_tag is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#tag_add instead.'
+        )
+        tag_add(name, *options)
+      end
+
       # Delete a tag
       #
       # @example Delete a tag
-      #   repo.delete_tag('v1.0.0')
+      #   repo.tag_delete('v1.0.0')
       #
       # @param name [String] the name of the tag to delete
       #
@@ -849,13 +931,29 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      def delete_tag(name)
+      def tag_delete(name)
         result = Git::Commands::Tag::Delete.new(@execution_context).call(name)
         raise Git::FailedError, result if result.status.exitstatus.positive?
 
         result.stdout
       end
 
+      # @deprecated Use {#tag_delete} instead.
+      #
+      # @param name [String] the name of the tag to delete
+      #
+      # @return [String] git's stdout from the delete
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      def delete_tag(name)
+        Git::Deprecation.warn(
+          'Git::Repository#delete_tag is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#tag_delete instead.'
+        )
+        tag_delete(name)
+      end
+
       # Private helpers
       #
       # @api private
@@ -882,9 +980,9 @@ module Git
           raise ArgumentError, 'Cannot create an annotated or signed tag without a message.'
         end
 
-        # Handle the deprecated :d/:delete option on add_tag
+        # Handle the deprecated :d/:delete option on tag_add
         #
-        # Issues a deprecation warning and delegates to delete_tag. Raises
+        # Issues a deprecation warning and delegates to tag_delete. Raises
         # ArgumentError if a target or incompatible options are also supplied.
         #
         # @param facade [ObjectOperations] the calling facade instance
@@ -892,21 +990,21 @@ module Git
         # @param target [String, nil] target argument (must be nil)
         # @param opts [Hash] options hash (must contain only :d/:delete)
         #
-        # @return [String] stdout from delete_tag
+        # @return [String] stdout from tag_delete
         #
         # @api private
         #
-        def add_tag_delete_deprecated(facade, name, target, opts)
+        def tag_add_delete_deprecated(facade, name, target, opts)
           Git::Deprecation.warn(
-            'Passing :d or :delete to add_tag is deprecated and will be ' \
-            'removed in a future version. Use delete_tag instead.'
+            'Passing :d or :delete to tag_add is deprecated and will be removed in v6.0.0. ' \
+            'Use tag_delete instead.'
           )
           raise ArgumentError, 'Cannot pass a target when using the :d/:delete option.' if target
 
           extra = opts.keys - %i[d delete]
           raise ArgumentError, "Cannot combine :d/:delete with other options: #{extra.join(', ')}" unless extra.empty?
 
-          facade.delete_tag(name)
+          facade.tag_delete(name)
         end
 
         def show_ref_tag_sha(execution_context, tag_name)

data/lib/git/repository/path_resolver.rb

@@ -70,7 +70,7 @@ module Git
       # @param binary_path [String, :use_global_config] path to the git binary
       #
       #   Controls which git binary is invoked during root detection. Defaults to
-      #   `:use_global_config`, which resolves to `Git::Base.config.binary_path`.
+      #   `:use_global_config`, which resolves to `Git.config.binary_path`.
       #
       # @param git_ssh [String, nil, :use_global_config] the SSH wrapper path
       #