git 5.4.1 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a2e69ae222061dc013d589215448053164f54e1b17c4e071b30d8fbe8035bcf
-  data.tar.gz: b9615131c7573796ca6feed9becd6381b8f2aa142ce2e419c9669055f184f770
+  metadata.gz: fb847c9e15258e66f25f6856a2ceb170213e9ae310d061035ef23501e6e0cd72
+  data.tar.gz: eca3a73ec5bf9f979d4576375062ceaeb71a78b54f12660b3b4386c2920792e9
 SHA512:
-  metadata.gz: f3b1b79895b947c9b3209204e634b6069677f8e4054839b7744ee50d10bb09e66350d4e3041988718671c16bf75aca70ec35a50cfcd540cc52e69e3fc011450d
-  data.tar.gz: 559b0e41cefa277f70c5e52ec8970b59b895f8ec8e808f2d207c49ea26592c45efe8c9d2b1233e3a1d3ed7ab77aae3ffa99d1802f51a842fce48a8f9fe81d3f3
+  metadata.gz: 3842eadabba8c7bead2147b438ca51597ca0acc129b7d33b41f942750d29cb7e5910b1ca92e3f50cf7bc440afb9f5ed203a97f38b72c19b09025f4e7317849f2
+  data.tar.gz: 558adf7d3f23639b9143dcf3b9092739caba6415e066a8273f491f0589f3af06851dc15fd1776b2bad3e406d01429da76cce72c7e05f3c7ac57858bc3a771645

data/CHANGELOG.md

@@ -5,6 +5,37 @@
 
 # Change Log
 
+## [5.6.0](https://github.com/ruby-git/ruby-git/compare/v5.5.0...v5.6.0) (2026-09-12)
+
+
+### Features
+
+* **repository:** Deprecate with_* context helper blocks that declare no parameter ([231b65c](https://github.com/ruby-git/ruby-git/commit/231b65c435e9b3d9cdbf8b113b3aba9313da5110)), closes [#1835](https://github.com/ruby-git/ruby-git/issues/1835)
+
+
+### Other Changes
+
+* **export:** Describe what a failed .git removal leaves behind ([bd08096](https://github.com/ruby-git/ruby-git/commit/bd080964e44a11594202726e3823a8cafad62bd5)), closes [#1823](https://github.com/ruby-git/ruby-git/issues/1823)
+
+## [5.5.0](https://github.com/ruby-git/ruby-git/compare/v5.4.1...v5.5.0) (2026-09-10)
+
+
+### Features
+
+* **export:** Warn when the :remote option is passed to Git.export ([55a9810](https://github.com/ruby-git/ruby-git/commit/55a9810b7681a510781e55b17026ec6e13dcbfa5)), closes [#1820](https://github.com/ruby-git/ruby-git/issues/1820)
+
+
+### Bug Fixes
+
+* **export:** Drop the redundant checkout that broke Git.export for tags ([5e8422d](https://github.com/ruby-git/ruby-git/commit/5e8422d2361bff43959a0bba2254118087907a2a)), closes [#1815](https://github.com/ruby-git/ruby-git/issues/1815)
+
+
+### Other Changes
+
+* **export:** Document the deprecated :remote option to Git.export ([3806d2b](https://github.com/ruby-git/ruby-git/commit/3806d2b5a6fdb167006097df83c783573024a521)), closes [#1820](https://github.com/ruby-git/ruby-git/issues/1820)
+* Name the 5.x maintenance branch alongside 4.x ([ad30718](https://github.com/ruby-git/ruby-git/commit/ad30718a61cb89c343c84c71feb1c94cf3995f28))
+* Run the CI, commitlint, release, and cache workflows for the 5.x branch ([7c3fd13](https://github.com/ruby-git/ruby-git/commit/7c3fd13994104c2c6b6564cc41d1e3c4e614255a))
+
 ## [5.4.1](https://github.com/ruby-git/ruby-git/compare/v5.4.0...v5.4.1) (2026-09-04)
 
 

data/CONTRIBUTING.md

@@ -128,7 +128,7 @@ bin/setup
 3. Run `npm install` (when npm is available) to install the Conventional Commit
    `commit-msg` hook used by this project (Husky + commitlint). A separate
    `pre-commit` hook is also installed that blocks direct commits to the
-   protected branches (`main`, `4.x`).
+   protected branches (`main`, `5.x`, `4.x`).
 4. Verify the toolchain by running `bundle exec rake --tasks`.
 
 `bin/setup` checks for [lychee](https://lychee.cli.rs) alongside Ruby, git, and
@@ -197,7 +197,7 @@ Once your pull request is ready for review, request a review from at least one
 
 During the review process, you may need to make additional commits; squash them.
 You will also need to rebase your branch onto the latest version of the target
-branch (e.g., `main` or `4.x`) before merging.
+branch (e.g., `main`, `5.x`, or `4.x`) before merging.
 
 At least one approval from a project maintainer is required before your pull request
 can be merged. The maintainer is responsible for ensuring that the pull request meets
@@ -219,11 +219,13 @@ first keeps the review cycle short.
 
 ## Branch strategy
 
-This project maintains two active branches:
+This project maintains `main` plus one maintenance branch for each supported previous
+major series:
 
 - **`main`**: All development. It releases the next version of the gem, including
-  the next major version.
-- **`4.x`**: The maintenance branch for the most recent previous major series. It
+  the next major version. Its next release is v6.0.0; every further v5.x release is
+  cut from `5.x`.
+- **`5.x`** and **`4.x`**: The maintenance branches for the v5.x and v4.x series. Each
   receives bug fixes and security fixes, and backward-compatible features at the
   maintainers' discretion.
 
@@ -233,8 +235,10 @@ each major series is supported.
 When submitting a pull request:
 
 - **New features and breaking changes**: Target the `main` branch
-- **Bug fixes**: Target `main`, and maintainers will backport to `4.x` if applicable
-- **Security fixes**: Target both branches or `4.x` if the issue only affects v4.x
+- **Bug fixes**: Target `main`, and maintainers will backport to the maintenance
+  branches if applicable
+- **Security fixes**: Target `main` and every affected maintenance branch, or only a
+  maintenance branch if the issue affects that series alone
 
 Removing a deprecated API follows the
 [deprecation policy](.github/skills/breaking-change-analysis/SKILL.md#step-4-deprecation-policy):
@@ -981,9 +985,9 @@ skill. Follow it when writing or reviewing specs under `spec/unit/`.
 
 #### Test coverage policy
 
-**Every pull request to `main` must keep `bundle exec rake spec:unit` at 100% line
-coverage and 100% branch coverage of `lib/`.** CI fails the build when it drops
-below either threshold.
+**Every pull request to `main` or `5.x` must keep `bundle exec rake spec:unit` at
+100% line coverage and 100% branch coverage of `lib/`.** CI fails the build when it
+drops below either threshold.
 
 This is enforceable without being onerous because unit coverage in this project is
 deterministic: `lib/` has no Ruby-version, Ruby-engine, or platform conditionals, and
@@ -1088,8 +1092,8 @@ $ LIST_UNCOVERED_DETAIL=true bundle exec rake spec:unit
 $ open coverage/index.html
 ```
 
-This policy applies to `main` only. The `4.x` maintenance branch predates it and is
-not held to these thresholds.
+This policy applies to `main` and `5.x`. The `4.x` maintenance branch predates it and
+is not held to these thresholds.
 
 #### Unit tests vs integration tests
 

data/README.md

@@ -447,12 +447,13 @@ are in [UPGRADING.md](UPGRADING.md#upgrading-to-v600). See
 ### Release support policy
 
 All development happens on `main`, which releases the next version of the gem,
-including the next major version.
+including the next major version. The next release from `main` is v6.0.0. Every
+further v5.x release is cut from `5.x`.
 
-The most recent previous major series is maintained on a branch named for that
-series, currently `4.x`. It receives bug fixes and security fixes, and
-backward-compatible features at the maintainers' discretion. Fixes land on `main`
-first and are backported, except a fix for a problem that exists only in the
+Each supported previous major series is maintained on a branch named for that
+series, currently `5.x` and `4.x`. These branches receive bug fixes and security
+fixes, and backward-compatible features at the maintainers' discretion. Fixes land on
+`main` first and are backported, except a fix for a problem that exists only in a
 maintenance branch, which targets that branch directly.
 
 Support for a major series ends when the second major after it is released. v4.x is

data/UPGRADING.md

@@ -34,6 +34,8 @@ to update your code when upgrading from the preceding major version.
     - [`Git.clone` option renames](#gitclone-option-renames)
     - [`Git::Log` Enumerable interface deprecated](#gitlog-enumerable-interface-deprecated)
     - [`Git::Object::Commit#set_commit` deprecated](#gitobjectcommitset_commit-deprecated)
+    - [`Git.export` `:remote` option deprecated](#gitexport-remote-option-deprecated)
+    - [Context helper blocks that declare no parameter deprecated](#context-helper-blocks-that-declare-no-parameter-deprecated)
 
 ## Upgrading to v6.0.0
 
@@ -1117,4 +1119,57 @@ effect.
 |-----------------------------------------------------|-------------|
 | `commit.set_commit(data)` | `commit.from_data(data)` |
 
+#### `Git.export` `:remote` option deprecated
+
+`Git.export` has always dropped a `:remote` option before calling `Git.clone`
+without telling the caller. Passing it now emits a deprecation warning. The option
+is still dropped, so the export itself is unchanged, and it will be removed in a
+future major release. Once it is removed, passing `:remote` raises `ArgumentError`
+like any other unsupported option (see [Unsupported options raise
+`ArgumentError`](#unsupported-options-raise-argumenterror)).
+
+There is no replacement option. `:remote` renamed the clone's remote, and
+`Git.export` deletes the `.git` directory before returning, so the name was never
+observable in the result. Delete the option from the call.
+
+| Deprecated call (works in v5.x, removed in a future major release) | Replacement |
+|--------------------------------------------------------------------|-------------|
+| `Git.export(url, dir, remote: name)` | `Git.export(url, dir)` |
+
+#### Context helper blocks that declare no parameter deprecated
+
+`Git::Repository#with_index`, `#with_temp_index`, `#with_working`, and
+`#with_temp_working` yield `self` in v5.x, so a block could ignore the yielded
+value and call methods on the receiver. Calling one of these helpers with a block
+that declares no positional parameter (`do ... end`, `{ }`, `{ || }`, or a block
+with only keyword or block parameters) now emits a deprecation warning. The
+behavior is otherwise unchanged: the helpers still yield `self`, and a call with
+no block still raises `LocalJumpError`.
+
+In v6.0.0 these helpers yield a separate repository bound to the other index or
+working tree instead of rebinding the receiver, and they raise `ArgumentError` for
+a block that declares no positional parameter. A call with no block also raises
+`ArgumentError` in v6.0.0 instead of `LocalJumpError`. Declare a block parameter
+and call methods on it. The parameter is required even when the block never uses
+the repository, for example a `with_temp_working` block that only writes files
+(`do |_scratch|`). Blocks that already declare a positional parameter (`|repo|`,
+`|_|`, `|repo = nil|`, `|*args|`, or a symbol-to-proc such as `&:write_tree`) do
+not warn. Both versions read the block's parameter list rather than its arity, so
+the v5.x warning and the v6.0.0 error agree on every block form.
+
+The warning detects only the block's parameter list. Adding an unused parameter
+(`|_|`) silences it but does not fix a block that still calls methods on the outer
+repository; that block does not warn and acts on the wrong repository in v6.0.0,
+so review those blocks by hand.
+
+| Deprecated call (works in v5.x, raises in v6.0.0) | Replacement |
+|---------------------------------------------------|-------------|
+| `g.with_index(path) { g.read_tree('HEAD') }` | `g.with_index(path) { \|r\| r.read_tree('HEAD') }` |
+| `g.with_temp_index { g.read_tree('HEAD') }` | `g.with_temp_index { \|r\| r.read_tree('HEAD') }` |
+| `g.with_working(dir) { g.add('.') }` | `g.with_working(dir) { \|r\| r.add('.') }` |
+| `g.with_temp_working { g.add('.') }` | `g.with_temp_working { \|r\| r.add('.') }` |
+
+`chdir` is not part of this deprecation. It yields the directory path in both
+versions.
+
 ---

data/lib/git/repository/context_helpers.rb

@@ -18,6 +18,10 @@ module Git
     # @api private
     #
     module ContextHelpers
+      # Parameter types from `Proc#parameters` that receive a positional argument
+      CONTEXT_HELPERS_POSITIONAL_PARAMETERS = %i[req opt rest].freeze
+      private_constant :CONTEXT_HELPERS_POSITIONAL_PARAMETERS
+
       # Changes the current working directory to the repository working directory
       # for the duration of the block
       #
@@ -51,9 +55,13 @@ module Git
       # yields `self`, then unconditionally restores the original execution
       # context — even if the block raises an exception.
       #
+      # Deprecated form: a block that declares no positional parameter emits a
+      # deprecation warning, because v6.0.0 yields a separate repository
+      # instead of `self`.
+      #
       # @example Read a tree into a custom index
-      #   repo.with_index('/tmp/custom.index') do
-      #     repo.read_tree('HEAD')
+      #   repo.with_index('/tmp/custom.index') do |r|
+      #     r.read_tree('HEAD')
       #   end
       #
       # @param new_index [String, Pathname] path to the replacement index file
@@ -66,7 +74,8 @@ module Git
       #
       # @yieldreturn [Object] returned as the method's return value
       #
-      def with_index(new_index) # :yields: self
+      def with_index(new_index, &block) # :yields: self
+        context_helpers_warn_if_block_declares_no_parameter(:with_index, block)
         old_context = @execution_context
         set_index(new_index, must_exist: false)
         yield self
@@ -84,10 +93,14 @@ module Git
       # are removed unconditionally after the block exits, even if the block
       # raises an exception.
       #
+      # Deprecated form: a block that declares no positional parameter emits a
+      # deprecation warning, because v6.0.0 yields a separate repository
+      # instead of `self`.
+      #
       # @example Stage changes using a temporary index
-      #   repo.with_temp_index do
-      #     repo.read_tree('HEAD')
-      #     repo.write_tree
+      #   repo.with_temp_index do |r|
+      #     r.read_tree('HEAD')
+      #     r.write_tree
       #   end
       #
       # @return [Object] the value returned by the block
@@ -98,13 +111,17 @@ module Git
       #
       # @yieldreturn [Object] returned as the method's return value
       #
-      def with_temp_index(&) # :yields: self
+      def with_temp_index(&block) # :yields: self
+        context_helpers_warn_if_block_declares_no_parameter(:with_temp_index, block)
         # Use a unique temp directory so the index file path is collision-free
         # and does not exist until git writes it. An existing empty file would
         # be treated as a corrupt index by git.
         temp_dir = Dir.mktmpdir('git-temp-index-')
         begin
-          with_index(File.join(temp_dir, 'index'), &)
+          # The inner block declares a parameter so with_index does not warn a
+          # second time under its own name; forwarding &block would.
+          # rubocop:disable-next Style/ExplicitBlockArgument
+          with_index(File.join(temp_dir, 'index')) { |repo| yield repo }
         ensure
           FileUtils.remove_entry(temp_dir, true)
         end
@@ -118,10 +135,14 @@ module Git
       # `self`, then unconditionally restores the original execution context —
       # even if the block raises an exception.
       #
+      # Deprecated form: a block that declares no positional parameter emits a
+      # deprecation warning, because v6.0.0 yields a separate repository
+      # instead of `self`.
+      #
       # @example Commit changes from a different worktree path
-      #   repo.with_working('/path/to/worktree') do
-      #     repo.add('.')
-      #     repo.commit('chore: automated update')
+      #   repo.with_working('/path/to/worktree') do |r|
+      #     r.add('.')
+      #     r.commit('chore: automated update')
       #   end
       #
       # @param work_dir [String, Pathname] path to the replacement working
@@ -138,7 +159,8 @@ module Git
       #
       # @yieldreturn [Object] returned as the method's return value
       #
-      def with_working(work_dir) # :yields: self
+      def with_working(work_dir, &block) # :yields: self
+        context_helpers_warn_if_block_declares_no_parameter(:with_working, block)
         old_context = @execution_context
         set_working(work_dir)
         Dir.chdir(dir.to_s) { yield self }
@@ -153,9 +175,14 @@ module Git
       # The temporary directory is removed unconditionally after the block
       # exits, even if the block raises an exception.
       #
+      # Deprecated form: a block that declares no positional parameter emits a
+      # deprecation warning, because v6.0.0 yields a separate repository
+      # instead of `self`.
+      #
       # @example Write files in an isolated temporary working directory
-      #   repo.with_temp_working do
+      #   repo.with_temp_working do |r|
       #     File.write('scratch.txt', 'temporary content')
+      #     r.add('scratch.txt')
       #   end
       #
       # @return [Object] the value returned by the block
@@ -168,7 +195,11 @@ module Git
       # @yieldreturn [Object] returned as the method's return value
       #
       def with_temp_working(&block) # :yields: self
-        Dir.mktmpdir('temp-workdir') { |temp_dir| with_working(temp_dir, &block) }
+        context_helpers_warn_if_block_declares_no_parameter(:with_temp_working, block)
+        # The inner block declares a parameter so with_working does not warn a
+        # second time under its own name; forwarding &block would.
+        # rubocop:disable-next Style/ExplicitBlockArgument
+        Dir.mktmpdir('temp-workdir') { |temp_dir| with_working(temp_dir) { |repo| yield repo } }
       end
 
       # Sets the git index to `index_file` and rebuilds the execution context
@@ -231,6 +262,42 @@ module Git
 
       private
 
+      # Emits a deprecation warning when `block` declares no positional parameter
+      #
+      # In v6.0.0 the `with_*` helpers yield a separate repository instead of
+      # rebinding the receiver, so a block that calls methods on the receiver
+      # (the v5.x form) acts on the wrong repository there. v6.0.0 raises
+      # `ArgumentError` for that form using this same rule: the block must
+      # declare a required, optional, or splat positional parameter. The rule
+      # reads `Proc#parameters` rather than arity because an optional parameter
+      # gives a proc an arity of zero although it receives the repository,
+      # while keyword and block parameters cannot receive it.
+      #
+      # A missing block is not checked here; the helper's `yield` raises
+      # `LocalJumpError` as before.
+      #
+      # The warning reports the helper's caller, not this helper's caller, so
+      # the location points at the block that needs changing.
+      #
+      # @param helper [Symbol] the public helper name used in the warning
+      #
+      # @param block [Proc, nil] the block passed to the helper
+      #
+      # @return [void]
+      #
+      def context_helpers_warn_if_block_declares_no_parameter(helper, block)
+        return if block.nil?
+        return if block.parameters.any? { |type, _name| CONTEXT_HELPERS_POSITIONAL_PARAMETERS.include?(type) }
+
+        Git::Deprecation.warn(
+          "Calling Git::Repository##{helper} with a block that declares no positional " \
+          'parameter is deprecated and will be removed in v6.0.0, where the helper ' \
+          'yields a separate repository instead of self. Declare a block parameter and ' \
+          "call methods on it instead: #{helper} { |repo| repo.some_method }",
+          caller_locations(2)
+        )
+      end
+
       # Resolves deprecated `check` argument semantics with `must_exist:`
       #
       # @param check [Boolean, nil] deprecated positional existence-check value

data/lib/git/version.rb

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

data/lib/git.rb

@@ -327,25 +327,45 @@ module Git
   # Exports the current HEAD (or the specific branch given in <tt>options[:branch]</tt>)
   # into the given `directory`. It then removes all traces of git from the directory.
   #
-  # Takes the same options as {Git.clone} except that `:remote` is silently ignored
-  # and `:depth` defaults to 1.
+  # Removing `.git` is not atomic. If it fails, the exported files are complete and
+  # usable, but the directory keeps whatever part of `.git` could not be deleted.
+  # Nothing is cleaned up, because the exported files are the deliverable and the
+  # leftover has to be removed by hand once the cause of the failure is fixed.
+  #
+  # Takes the same options as {Git.clone} except that `:depth` defaults to 1 and
+  # `:remote` is ignored with a deprecation warning.
   #
   # @param repository_url [String, URI, Pathname] the repository to export from
   #
   # @param directory [String, Pathname, nil] the directory to export into; defaults to the
   #   repository basename
   #
-  # @param options [Hash] options forwarded to {Git.clone} (`:remote` is ignored;
-  #   `:depth` defaults to 1)
+  # @param options [Hash] options forwarded to {Git.clone} (`:depth` defaults to 1)
+  #
+  # @option options [String] :remote deprecated and ignored; delete it from the call.
+  #   Passing it emits a deprecation warning and it will be removed in a future
+  #   major release.
   #
-  # @option options [String] :branch the branch or tag to export instead of HEAD
+  # @option options [String] :branch the branch or tag to export instead of HEAD.
+  #   Give the short name (`main`, `v1.0.0`); a full ref path such as
+  #   `refs/tags/v1.0.0` or a commit SHA is not accepted. Use `:revision` to
+  #   export a SHA.
   #
   # @return [void]
   #
+  # @raise [SystemCallError] if the `.git` directory cannot be removed. The exported
+  #   files are left in place, and the directory keeps whatever part of `.git` could
+  #   not be deleted.
+  #
   def self.export(repository_url, directory = nil, options = {})
-    options.delete(:remote)
+    if options.key?(:remote)
+      Git::Deprecation.warn(
+        'The :remote option to Git.export is ignored, is deprecated, and will be removed in a future ' \
+        'major release. Delete it from the call.'
+      )
+      options.delete(:remote)
+    end
     repo = clone(repository_url, directory, { depth: 1 }.merge(options))
-    repo.checkout("origin/#{options[:branch]}") if options[:branch]
     FileUtils.rm_r File.join(repo.dir.to_s, '.git')
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 5.4.1
+  version: 5.6.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.4.1/file/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/git/5.4.1
+  changelog_uri: https://rubydoc.info/gems/git/5.6.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/git/5.6.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: