git 5.6.0 → 5.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb847c9e15258e66f25f6856a2ceb170213e9ae310d061035ef23501e6e0cd72
-  data.tar.gz: eca3a73ec5bf9f979d4576375062ceaeb71a78b54f12660b3b4386c2920792e9
+  metadata.gz: 7c23ed7b58cd8f2297c9291b8a0e1686f294abe6c82bbf8673c3651b65cc635d
+  data.tar.gz: dd17a339711522080bdb94827173ce404cc918a434f829c26b73d416bd90e742
 SHA512:
-  metadata.gz: 3842eadabba8c7bead2147b438ca51597ca0acc129b7d33b41f942750d29cb7e5910b1ca92e3f50cf7bc440afb9f5ed203a97f38b72c19b09025f4e7317849f2
-  data.tar.gz: 558adf7d3f23639b9143dcf3b9092739caba6415e066a8273f491f0589f3af06851dc15fd1776b2bad3e406d01429da76cce72c7e05f3c7ac57858bc3a771645
+  metadata.gz: 027eb2ff2a491e56a5d9f42a6b6758fa8b54465c0b0c8f990071aa0d84cdae40f489428353bd777f4638f73958e74fe8f9b62254cb50d1f4ba01ccef17039ac2
+  data.tar.gz: a69634e5053eb693c08869740abc71ce69cab965a366593040107b158b64bb83ad42521aedc952ce069031ea1ced7de5a58d127cf091651f479632b057301485

data/CHANGELOG.md

@@ -5,6 +5,25 @@
 
 # Change Log
 
+## [5.7.0](https://github.com/ruby-git/ruby-git/compare/v5.6.1...v5.7.0) (2026-10-28)
+
+
+### Features
+
+* **repository:** Deprecate the eight renamed facade aliases with warnings that name v6.0.0 ([8339117](https://github.com/ruby-git/ruby-git/commit/8339117e9fff5a1acadea73b4ccd385a5b0f1497)), closes [#1923](https://github.com/ruby-git/ruby-git/issues/1923) [#1924](https://github.com/ruby-git/ruby-git/issues/1924)
+
+## [5.6.1](https://github.com/ruby-git/ruby-git/compare/v5.6.0...v5.6.1) (2026-09-16)
+
+
+### Other Changes
+
+* **errors:** Document that filesystem and gzip errors can escape unconverted ([0b171e4](https://github.com/ruby-git/ruby-git/commit/0b171e42713a884354a84138696102f8e3cd83e5)), closes [#1809](https://github.com/ruby-git/ruby-git/issues/1809)
+* **remote:** Correct the argument forms in the Git::Remote and Git::Branch entries ([cea622a](https://github.com/ruby-git/ruby-git/commit/cea622a14cce54a90c2203953a457b13b298aa22)), closes [#1852](https://github.com/ruby-git/ruby-git/issues/1852)
+* **tag:** Note that tag_create raises UnexpectedResultError in v6.0.0 ([050aa44](https://github.com/ruby-git/ruby-git/commit/050aa443136156d7ecab47ad6fb44f436d9c2b7f)), closes [#1856](https://github.com/ruby-git/ruby-git/issues/1856)
+* **worktree:** Look the new worktree up with File.identical? in the v5.x note ([0c941ec](https://github.com/ruby-git/ruby-git/commit/0c941ec34204ef5c3aeb6cf1de9e61f33212a0d9))
+* **worktree:** Look the new worktree up with File.identical? in the YARD note ([8eb10ec](https://github.com/ruby-git/ruby-git/commit/8eb10eccb50ff14911e09033cfeec33666ce5c6a)), closes [#1845](https://github.com/ruby-git/ruby-git/issues/1845)
+* **worktree:** Note that worktree_add returns Git::WorktreeInfo in v6.0.0 ([24af07e](https://github.com/ruby-git/ruby-git/commit/24af07e24199303727d823804063732fcaa98c98)), closes [#1845](https://github.com/ruby-git/ruby-git/issues/1845)
+
 ## [5.6.0](https://github.com/ruby-git/ruby-git/compare/v5.5.0...v5.6.0) (2026-09-12)
 
 

data/README.md

@@ -201,11 +201,41 @@ the full API of its result.
 
 ## Errors raised by this gem
 
-The git gem raises only `ArgumentError` or errors that subclass `Git::Error`. It
-does not explicitly raise any other types of errors.
-
-Rescue `Git::Error` to catch any runtime error raised by this gem, unless you need
-more specific error handling.
+Errors the git gem raises deliberately are either `ArgumentError` or a subclass of
+`Git::Error`, with one exception: with the `raise` behavior described under
+[Deprecations](#deprecations), a deprecated call raises
+`ActiveSupport::DeprecationException`, which is intentionally not a `Git::Error` so a
+broad rescue cannot hide a deprecation your code opted to treat as fatal. The errors
+described below come from Ruby's standard library and are not converted.
+
+The gem's own filesystem operations, such as reading a `.git` pointer file,
+creating a temporary file, or changing directory, do not convert operating system
+errors. These can be raised as a bare `SystemCallError` (for example `Errno::ENOENT`
+or `Errno::EACCES`) rather than `Git::Error`. Gzip compression in `archive` can
+likewise raise a `Zlib::Error`. Rescue `SystemCallError` and `Zlib::Error` alongside
+`Git::Error` if your code needs to handle them.
+
+The affected methods are `Git.open` when the `.git` file is a gitdir pointer or the
+path is relative, `Git.init`, `Git.bare`, and `Git.clone` when the path is relative,
+`Git.export`, and these `Git::Repository` methods: `#chdir`, `#with_index`,
+`#with_working`, `#with_temp_index`, `#with_temp_working`, `#set_index`,
+`#set_working`, `#cat_file_contents` in block form, `#each_conflict`, `#conflicts`,
+`#archive` (including the gzip step), `#repo_size`, and `#tag_sha` when it reads a
+loose ref.
+
+Any method that captures git output can also raise
+`Encoding::ConverterNotFoundError` when the output contains a line whose detected
+encoding, such as UTF-7, has no Ruby converter.
+
+Starting with v6.0.0, the filesystem and gzip errors are raised as `Git::Error`
+with the original error available through `cause`, except that `#tag_sha` falls
+back to `git show-ref` instead of raising. Lines with no Ruby converter are
+scrubbed instead of raising.
+
+Rescue `Git::Error` to catch the runtime errors this gem raises itself, and add
+`SystemCallError`, `Zlib::Error`, and `Encoding::ConverterNotFoundError` where the
+paragraphs above say they can escape. Rescue a more specific subclass when you need
+finer-grained handling.
 
 ```ruby
 begin

data/UPGRADING.md

@@ -17,6 +17,7 @@ to update your code when upgrading from the preceding major version.
   - [Deprecated methods](#deprecated-methods)
     - [Facade method renames](#facade-method-renames)
     - [`Git::Repository` method renames](#gitrepository-method-renames)
+    - [`Git::Repository` alias renames](#gitrepository-alias-renames)
     - [`Git::Repository` option renames](#gitrepository-option-renames)
     - [v4.x-style configuration methods](#v4x-style-configuration-methods)
     - [`Git` module mixin deprecations](#git-module-mixin-deprecations)
@@ -395,6 +396,28 @@ replacement returns, except `branches_all`.
 | `g.is_branch?(name)` | `g.branch?(name)` |
 | `g.branches_all` | `g.branch_list` — returns `Array<Git::BranchInfo>`; see the return shape change above |
 
+#### `Git::Repository` alias renames
+
+Eight `Git::Repository` methods have a second, older name carried over from v4.x.
+Earlier v5.x releases kept the older names as aliases with no warning. Later
+v5.x releases emit a deprecation warning for each one. Each old name takes the
+same arguments and returns exactly what its replacement returns.
+
+> **`diff_name_status`:** a `:path` option emits its own deprecation warning
+> after the method-name warning. Pass `:path_limiter` instead, as described
+> under "`Git::Repository` option renames" below.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `g.object_contents(object)` | `g.cat_file_contents(object)` |
+| `g.object_size(object)` | `g.cat_file_size(object)` |
+| `g.object_type(object)` | `g.cat_file_type(object)` |
+| `g.commit_data(object)` | `g.cat_file_commit(object)` |
+| `g.tag_data(object)` | `g.cat_file_tag(object)` |
+| `g.revparse(objectish)` | `g.rev_parse(objectish)` |
+| `g.namerev(commit_ish)` | `g.name_rev(commit_ish)` |
+| `g.diff_name_status(from, to, opts)` | `g.diff_path_status(from, to, opts)` |
+
 #### `Git::Repository` option renames
 
 Five methods accept a v4.x option or positional argument under its old name.
@@ -637,7 +660,8 @@ with N remotes produces N + 1 warnings per call.
 > the last one configured, so use `r.url.last` to reproduce that exact value.
 > Likewise, `Git::Remote#fetch_opts` returned only the last configured fetch
 > refspec, while `fetch` holds all of them. Operations that lived on
-> `Git::Remote` are called on the repository with the remote name instead.
+> `Git::Remote` are called on the repository instead; the table below shows
+> the argument each one takes.
 >
 > **Order change:** `remotes` lists remotes in the order `git remote` prints
 > them, while `remote_list` keeps the order in which remotes first appear in the
@@ -656,8 +680,8 @@ with N remotes produces N + 1 warnings per call.
 | `remote.fetch(opts)` | `g.fetch(remote.name, opts)` — same options hash |
 | `remote.merge` | `g.merge("#{remote.name}/#{g.current_branch}")` |
 | `remote.merge(branch)` | `g.merge("#{remote.name}/#{branch}")` |
-| `remote.branch` | `g.branch_list("#{remote.name}/#{g.current_branch}").first` — returns a `Git::BranchInfo` |
-| `remote.branch(name)` | `g.branch_list("#{remote.name}/#{name}").first` — returns a `Git::BranchInfo` |
+| `remote.branch` | `g.branch_list("#{remote.name}/#{g.current_branch}").find(&:remote?)` — returns a `Git::BranchInfo` |
+| `remote.branch(name)` | `g.branch_list("#{remote.name}/#{name}").find(&:remote?)` — returns a `Git::BranchInfo` |
 | `remote.remove` | `g.remote_remove(remote.name)` |
 
 #### `Git::Remote` deprecated
@@ -665,13 +689,13 @@ with N remotes produces N + 1 warnings per call.
 `Git::Remote`, `Git::Repository#remote`, and `Git::Repository#config_remote` are
 deprecated and are removed in v6.0.0. Read a remote's configuration through
 `Git::Repository#remote_list`, which returns one `Git::RemoteInfo` value object per
-remote, and call the repository-level operations (`fetch`, `merge`, `branch_list`,
-`remote_remove`) with the remote name. Return values are unchanged. Constructing a
-`Git::Remote` directly emits one deprecation warning, and so does calling
-`g.config_remote`. Calling `g.remote` emits two: one for `Git::Repository#remote`
-and one for the `Git::Remote` it constructs. Likewise `g.remotes` emits one warning
-for itself plus one per `Git::Remote` it returns (N + 1 for N remotes). The extra
-warnings from `g.remote` and `g.remotes` are expected, not a bug.
+remote; the table below shows the replacement for each operation. Return values
+are unchanged. Constructing a `Git::Remote` directly emits one deprecation warning,
+and so does calling `g.config_remote`. Calling `g.remote` emits two: one for
+`Git::Repository#remote` and one for the `Git::Remote` it constructs. Likewise
+`g.remotes` emits one warning for itself plus one per `Git::Remote` it returns
+(N + 1 for N remotes). The extra warnings from `g.remote` and `g.remotes` are
+expected, not a bug.
 
 > **Return type changes:** `Git::RemoteInfo#url` and `Git::RemoteInfo#fetch` are
 > frozen `Array<String>` because a remote may carry more than one URL or fetch
@@ -686,8 +710,9 @@ warnings from `g.remote` and `g.remotes` are expected, not a bug.
 > Code that reads custom keys should filter `g.config_list` instead (see the
 > table); that yields the same `Hash{String => String}` as `config_remote`.
 > `Git::Remote#branch` returned a `Git::Branch`. Its replacement,
-> `g.branch_list("#{name}/#{branch}").first`, returns a `Git::BranchInfo` value
-> object, or `nil` when the remote-tracking branch does not exist.
+> `g.branch_list("#{name}/#{branch}").find(&:remote?)`, returns a
+> `Git::BranchInfo` value object, or `nil` when the remote-tracking branch does
+> not exist.
 
 In the table, `name` is the remote name (`g.remote` defaults it to `'origin'`).
 
@@ -704,8 +729,8 @@ In the table, `name` is the remote name (`g.remote` defaults it to `'origin'`).
 | `remote.fetch(opts)` | `g.fetch(name, opts)` — same option keys |
 | `remote.merge` | `g.merge("#{name}/#{g.current_branch}")` |
 | `remote.merge(branch)` | `g.merge("#{name}/#{branch}")` |
-| `remote.branch` | `g.branch_list("#{name}/#{g.current_branch}").first` — returns a `Git::BranchInfo` |
-| `remote.branch(branch)` | `g.branch_list("#{name}/#{branch}").first` — returns a `Git::BranchInfo` |
+| `remote.branch` | `g.branch_list("#{name}/#{g.current_branch}").find(&:remote?)` — returns a `Git::BranchInfo` |
+| `remote.branch(branch)` | `g.branch_list("#{name}/#{branch}").find(&:remote?)` — returns a `Git::BranchInfo` |
 | `remote.remove` | `g.remote_remove(name)` |
 
 #### `Git::Commands::CatFile::Raw` `allow_unknown_type` option deprecated
@@ -735,10 +760,12 @@ that constructs the command class directly is affected.
 data through `Git::Repository#branch_list`, which returns one `Git::BranchInfo`
 value object per local and remote-tracking branch, and call the repository-level
 operations (`checkout`, `branch_new`, `branch_delete`, `merge`, `merge_into`,
-`in_branch`, and so on) with the branch name. Calling `g.branch` or `g.branches`,
-constructing a `Git::Branches`, and calling any operation on a `Git::Branch` each
-emit a deprecation warning; their return values are unchanged. The `full`,
-`name`, `remote`, `to_s`, and `to_a` readers on `Git::Branch` do not warn.
+`in_branch`, and so on) with the branch name. For a remote-tracking branch the
+argument differs by operation; the table below shows the form each one takes.
+Calling `g.branch` or `g.branches`, constructing a `Git::Branches`, and calling
+any operation on a `Git::Branch` each emit a deprecation warning; their return
+values are unchanged. The `full`, `name`, `remote`, `to_s`, and `to_a` readers
+on `Git::Branch` do not warn.
 
 > **Return shape change:** `Git::Branch` exposes `full` (`main` or
 > `remotes/origin/main`), `name`, and `remote` (a `Git::Remote`, or `nil`).
@@ -863,6 +890,13 @@ warn.
 > **Missing tags:** `g.tag(name)` raises `Git::UnexpectedResultError` when no tag
 > has that name. `g.tag_list(name).first` returns `nil`.
 >
+> **`tag_create` when the new tag is missing in v6.0.0:** on v5.x, `g.tag_create`
+> returns `nil` when the tag it has just created is missing from the tag list
+> (for example, another process deleted it before the lookup). In v6.0.0 it
+> raises `Git::UnexpectedResultError` instead, so its return value is always a
+> `Git::TagInfo`. A `nil` check on the result keeps working today and becomes
+> unreachable in v6.0.0.
+>
 > **Deleting through `tag_add`:** `g.tag_add(name, d: true)`, which was already
 > deprecated, deletes the tag and emits a second warning pointing at
 > `g.tag_delete`. `g.tag_create` rejects `:d` and `:delete` with `ArgumentError`.
@@ -1009,7 +1043,7 @@ and are removed in v6.0.0. Read worktree data through
 object per worktree, and call the repository-level operations (`worktree_add`,
 `worktree_remove`, `worktree_move`, `worktree_lock`, `worktree_unlock`,
 `worktree_repair`, and `worktree_prune`) with the worktree path or its
-`Git::WorktreeInfo`. Return values are unchanged. Calling `g.worktree`,
+`Git::WorktreeInfo`. Return values are unchanged on v5.x. Calling `g.worktree`,
 `g.worktrees`, or `g.worktrees_all`, constructing a `Git::Worktrees`, and calling
 `gcommit`, `add`, or `remove` on a `Git::Worktree` each emit a deprecation
 warning; the `dir`, `full`, `to_s`, and `to_a` readers on `Git::Worktree` do not.
@@ -1035,6 +1069,14 @@ it constructs, and `g.worktree(dir).add` emits one for `g.worktree` and one for
 > **`full` and `to_s`:** `Git::Worktree#full` and `#to_s` append the commitish
 > given at construction to the path, so entries from `g.worktrees` read
 > `"/path/to/wt <sha>"`. `Git::WorktreeInfo#to_s` is the path alone.
+>
+> **`worktree_add` return type in v6.0.0:** on v5.x, `worktree_add` returns the
+> `git worktree add` output (`"HEAD is now at …"`). In v6.0.0 it returns the new
+> `Git::WorktreeInfo` instead. To get the entry today, look it up after the add:
+> `g.worktree_list.find { |w| File.identical?(w.path, dir) }`. Compare with
+> `File.identical?`, not string equality: git stores worktree paths with
+> symlinks resolved, so `/tmp/...` on macOS is listed as `/private/tmp/...`,
+> and on case-insensitive filesystems the listed casing may differ from `dir`.
 
 In the table, `dir` is the worktree path, `wt` is a `Git::Worktree`, and `info`
 is the `Git::WorktreeInfo` that replaces it.

data/lib/git/diff_path_status.rb

@@ -77,7 +77,7 @@ module Git
     # @return [Hash{String => String}] a mapping of file paths to status codes
     #
     def fetch_path_status
-      @fetch_path_status ||= @base.diff_name_status(@from, @to, path_limiter: @path_limiter).to_h
+      @fetch_path_status ||= @base.diff_path_status(@from, @to, path_limiter: @path_limiter).to_h
     end
 
     # Sets up legacy (base, from, to, path_limiter) instance state

data/lib/git/errors.rb

@@ -5,8 +5,20 @@ module Git
 
   # Base class for all custom git module errors
   #
-  # The git gem will only raise an `ArgumentError` or an error that is a subclass of
-  # `Git::Error`. It does not explicitly raise any other types of errors.
+  # Errors the git gem raises deliberately are either `ArgumentError` or a subclass
+  # of `Git::Error`. The exceptions described below come from Ruby's standard
+  # library and are not converted.
+  #
+  # The gem's own filesystem operations, such as reading a `.git` pointer file,
+  # creating a temporary file, or changing directory, do not convert operating
+  # system errors. These can be raised as a bare `SystemCallError` (for example
+  # `Errno::ENOENT` or `Errno::EACCES`) rather than `Git::Error`. Gzip compression
+  # in `archive` can likewise raise a `Zlib::Error`. Rescue `SystemCallError` and
+  # `Zlib::Error` alongside `Git::Error` if your code needs to handle them. Any
+  # method that captures git output can also raise
+  # `Encoding::ConverterNotFoundError` when a line's detected encoding has no Ruby
+  # converter. See the "Errors raised by this gem" section of the README for the
+  # affected methods.
   #
   # It is recommended to rescue `Git::Error` to catch any runtime error raised by
   # this gem unless you need more specific error handling.

data/lib/git/repository/diffing.rb

@@ -373,14 +373,42 @@ module Git
         Git::DiffPathStatus.new(Private.extract_name_status_from_raw(result.stdout))
       end
 
-      # Alias for {#diff_path_status}; provided for backward compatibility
+      # Reports each changed path with its status (deprecated name for {#diff_path_status})
+      #
+      # @example Report path statuses between HEAD and the working tree
+      #   repo.diff_name_status.to_h #=> { "lib/foo.rb" => "M" }
+      #
+      # @param from [String, nil] the first commit or object to compare
+      #
+      # @param to [String, nil] the second commit or object to compare
+      #
+      # @param opts [Hash] the options accepted by {#diff_path_status}
+      #
+      # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
+      #   limit the status report to the given path(s)
+      #
+      # @option opts [String, Pathname, Array<String, Pathname>, nil] :path (nil)
+      #   **deprecated** — use `:path_limiter` instead
       #
       # @return [Git::DiffPathStatus] the name-status report for the comparison
       #
-      # @deprecated Use {#diff_path_status} instead
+      # @raise [ArgumentError] if unsupported options are provided
+      #
+      # @raise [ArgumentError] if `from` is `nil` but `to` is not OR if `from` or `to` starts with `"-"`
+      #
+      # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 2)
+      #
+      # @deprecated Use {#diff_path_status} instead. Will be removed in v6.0.0.
       #
       # @see #diff_path_status
-      alias diff_name_status diff_path_status
+      #
+      def diff_name_status(from = 'HEAD', to = nil, opts = {})
+        Git::Deprecation.warn(
+          'Git::Repository#diff_name_status is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#diff_path_status instead.'
+        )
+        diff_path_status(from, to, opts)
+      end
 
       # Compares the index and the working directory
       #

data/lib/git/repository/object_operations.rb

@@ -89,17 +89,57 @@ module Git
         end
       end
 
-      # Alias for {#cat_file_contents}; retained for backward compatibility
+      # Alias for {#cat_file_contents}; kept as a legacy name and not scheduled
+      # for removal
       #
       # @see #cat_file_contents
       alias cat_file cat_file_contents
 
-      # Alias for {#cat_file_contents}
+      # Returns the raw contents of a git object (deprecated name for {#cat_file_contents})
       #
-      # @deprecated Use {#cat_file_contents} instead
+      # @overload object_contents(object)
+      #   Returns the object's raw content as a string
+      #
+      #   @example Read a blob's contents
+      #     repo.object_contents('HEAD:README.md') #=> "# My Project\n"
+      #
+      #   @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
+      #
+      #   @return [String] the raw content of the object
+      #
+      # @overload object_contents(object, &block)
+      #   Streams the object's raw content to a temporary file and yields it
+      #
+      #   @example Read a large blob without buffering it in memory
+      #     repo.object_contents('HEAD:large_file.bin') { |f| process(f) }
+      #
+      #   @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
+      #
+      #   @yield [file] the temporary file containing the streamed content,
+      #     positioned at the start
+      #
+      #   @yieldparam file [File] readable `IO` object positioned at the beginning
+      #     of the content
+      #
+      #   @yieldreturn [Object] the value to return from this method
+      #
+      #   @return [Object] the value returned by the block
+      #
+      # @raise [ArgumentError] if `object` starts with a hyphen
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @deprecated Use {#cat_file_contents} instead. Will be removed in v6.0.0.
       #
       # @see #cat_file_contents
-      alias object_contents cat_file_contents
+      #
+      def object_contents(object, &)
+        Git::Deprecation.warn(
+          'Git::Repository#object_contents is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#cat_file_contents instead.'
+        )
+        cat_file_contents(object, &)
+      end
 
       # Returns the size of a git object in bytes
       #
@@ -125,12 +165,30 @@ module Git
         Git::Commands::CatFile::Raw.new(@execution_context).call(object, s: true).stdout.chomp.to_i
       end
 
-      # Alias for {#cat_file_size}
+      # Returns the size of a git object in bytes (deprecated name for {#cat_file_size})
+      #
+      # @example Get the size of a commit object
+      #   repo.object_size('HEAD') #=> 265
+      #
+      # @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
+      #
+      # @return [Integer] the size of the object in bytes
+      #
+      # @raise [ArgumentError] if `object` starts with a hyphen
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      # @deprecated Use {#cat_file_size} instead
+      # @deprecated Use {#cat_file_size} instead. Will be removed in v6.0.0.
       #
       # @see #cat_file_size
-      alias object_size cat_file_size
+      #
+      def object_size(object)
+        Git::Deprecation.warn(
+          'Git::Repository#object_size is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#cat_file_size instead.'
+        )
+        cat_file_size(object)
+      end
 
       # Returns the type of a git object
       #
@@ -157,12 +215,30 @@ module Git
         Git::Commands::CatFile::Raw.new(@execution_context).call(object, t: true).stdout.chomp
       end
 
-      # Alias for {#cat_file_type}
+      # Returns the type of a git object (deprecated name for {#cat_file_type})
+      #
+      # @example Get the type of HEAD
+      #   repo.object_type('HEAD') #=> "commit"
+      #
+      # @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
+      #
+      # @return [String] the object type: `"blob"`, `"tree"`, `"commit"`, or `"tag"`
+      #
+      # @raise [ArgumentError] if `object` starts with a hyphen
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      # @deprecated Use {#cat_file_type} instead
+      # @deprecated Use {#cat_file_type} instead. Will be removed in v6.0.0.
       #
       # @see #cat_file_type
-      alias object_type cat_file_type
+      #
+      def object_type(object)
+        Git::Deprecation.warn(
+          'Git::Repository#object_type is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#cat_file_type instead.'
+        )
+        cat_file_type(object)
+      end
 
       # Returns parsed commit data for the given git object
       #
@@ -200,12 +276,28 @@ module Git
         Git::Parsers::CatFile.parse_commit(result.stdout.split("\n"), object)
       end
 
-      # Alias for {#cat_file_commit}
+      # Returns parsed commit data for a git object (deprecated name for {#cat_file_commit})
+      #
+      # @example Get commit data for HEAD
+      #   repo.commit_data('HEAD')
+      #
+      # @param object [String] the commit name (SHA, ref, `HEAD`, etc.)
       #
-      # @deprecated Use {#cat_file_commit} instead
+      # @return [Hash] the parsed commit data; see {#cat_file_commit} for the keys
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @deprecated Use {#cat_file_commit} instead. Will be removed in v6.0.0.
       #
       # @see #cat_file_commit
-      alias commit_data cat_file_commit
+      #
+      def commit_data(object)
+        Git::Deprecation.warn(
+          'Git::Repository#commit_data is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#cat_file_commit instead.'
+        )
+        cat_file_commit(object)
+      end
 
       # Returns parsed tag data for the given annotated tag object
       #
@@ -256,12 +348,30 @@ module Git
         Git::Parsers::CatFile.parse_tag(tdata, object)
       end
 
-      # Alias for {#cat_file_tag}
+      # Returns parsed tag data for an annotated tag (deprecated name for {#cat_file_tag})
+      #
+      # @example Get tag data for an annotated tag
+      #   repo.tag_data('v1.0.0')
+      #
+      # @param object [String] the tag name or SHA of the annotated tag object
       #
-      # @deprecated Use {#cat_file_tag} instead
+      # @return [Hash] the parsed tag data; see {#cat_file_tag} for the keys
+      #
+      # @raise [ArgumentError] if `object` starts with a hyphen
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @deprecated Use {#cat_file_tag} instead. Will be removed in v6.0.0.
       #
       # @see #cat_file_tag
-      alias tag_data cat_file_tag
+      #
+      def tag_data(object)
+        Git::Deprecation.warn(
+          'Git::Repository#tag_data is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#cat_file_tag instead.'
+        )
+        cat_file_tag(object)
+      end
 
       # Resolve a revision specifier to its full object ID
       #
@@ -292,7 +402,29 @@ module Git
         Git::Commands::RevParse.new(@execution_context).call(objectish, '--', revs_only: true).stdout
       end
 
-      alias revparse rev_parse
+      # Resolves a revision specifier to its full object ID (deprecated name for {#rev_parse})
+      #
+      # @example Resolve HEAD to its SHA
+      #   repo.revparse('HEAD') #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
+      #
+      # @param objectish [String] the revision specifier to resolve (branch name,
+      #   tag, abbreviated SHA, refspec, etc.)
+      #
+      # @return [String] the full object ID of the resolved object
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @deprecated Use {#rev_parse} instead. Will be removed in v6.0.0.
+      #
+      # @see #rev_parse
+      #
+      def revparse(objectish)
+        Git::Deprecation.warn(
+          'Git::Repository#revparse is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#rev_parse instead.'
+        )
+        rev_parse(objectish)
+      end
 
       # Returns the SHA of a named tag
       #
@@ -395,12 +527,30 @@ module Git
         Git::Commands::NameRev.new(@execution_context).call(commit_ish).stdout.split[1]
       end
 
-      # Alias for {#name_rev}
+      # Finds a symbolic name for a commit (deprecated name for {#name_rev})
+      #
+      # @example Name the current commit
+      #   repo.namerev('HEAD') #=> "main"
+      #
+      # @param commit_ish [String] the commit to name (SHA, ref, `HEAD`, etc.)
+      #
+      # @return [String, nil] the symbolic name, or `nil` if git finds none
       #
-      # @deprecated Use {#name_rev} instead
+      # @raise [ArgumentError] if commit_ish starts with a hyphen
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @deprecated Use {#name_rev} instead. Will be removed in v6.0.0.
       #
       # @see #name_rev
-      alias namerev name_rev
+      #
+      def namerev(commit_ish)
+        Git::Deprecation.warn(
+          'Git::Repository#namerev is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#name_rev instead.'
+        )
+        name_rev(commit_ish)
+      end
 
       # Option keys accepted by {#ls_tree}
       LS_TREE_ALLOWED_OPTS = %i[recursive path].freeze
@@ -928,7 +1078,9 @@ module Git
       #   @option options [Boolean, nil] :create_reflog (nil) create a reflog for
       #     the tag
       #
-      #   @return [Git::TagInfo] the newly created tag
+      #   @return [Git::TagInfo, nil] the newly created tag, or `nil` when the tag
+      #     is missing from the tag list after the create (for example, another
+      #     process deleted it before the lookup)
       #
       # @overload tag_create(name, target, options = {})
       #
@@ -945,7 +1097,9 @@ module Git
       #   @param options [Hash] options for creating the tag (same keys as the
       #     first overload)
       #
-      #   @return [Git::TagInfo] the newly created tag
+      #   @return [Git::TagInfo, nil] the newly created tag, or `nil` when the tag
+      #     is missing from the tag list after the create (for example, another
+      #     process deleted it before the lookup)
       #
       # @raise [ArgumentError] if unsupported options are provided, including the
       #   `:d` and `:delete` keys that {#tag_add} accepts; use {#tag_delete} to
@@ -960,6 +1114,12 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @note In v6.0.0 this method raises {Git::UnexpectedResultError} instead of
+      #   returning `nil` when the tag it has just created is missing from the tag
+      #   list, so its return value is always a {Git::TagInfo}. Code that checks
+      #   the result for `nil` today can be left as is; the check becomes
+      #   unreachable in v6.0.0.
+      #
       # @see https://git-scm.com/docs/git-tag git-tag
       #
       def tag_create(name, *args)

data/lib/git/repository/worktree_operations.rb

@@ -99,6 +99,14 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @note In v6.0.0 this method returns the new {Git::WorktreeInfo} instead of
+      #   the command output. To get the entry today, look it up after the add:
+      #   `worktree_list.find { |w| File.identical?(w.path, dir) }`.
+      #   Compare with `File.identical?`, not string equality: git stores
+      #   worktree paths with symlinks resolved, so `/tmp/...` on macOS is
+      #   listed as `/private/tmp/...`, and on case-insensitive filesystems the
+      #   listed casing may differ from `dir`.
+      #
       # @see https://git-scm.com/docs/git-worktree git-worktree documentation
       #
       def worktree_add(dir, commitish = nil)

data/lib/git/version.rb

@@ -4,7 +4,7 @@ module Git
   # The current gem version
   #
   # @return [String] the current gem version
-  VERSION = '5.6.0'
+  VERSION = '5.7.0'
 
   # Represents a git version with major, minor, and patch components
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 5.6.0
+  version: 5.7.0
 platform: ruby
 authors:
 - Scott Chacon and others
@@ -548,8 +548,8 @@ licenses:
 metadata:
   homepage_uri: http://github.com/ruby-git/ruby-git
   source_code_uri: http://github.com/ruby-git/ruby-git
-  changelog_uri: https://rubydoc.info/gems/git/5.6.0/file/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/git/5.6.0
+  changelog_uri: https://rubydoc.info/gems/git/5.7.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/git/5.7.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -566,7 +566,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - git 2.28.0 or greater
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: An API to create, read, and manipulate Git repositories
 test_files: []