Bundler 2.4.20 understands .ruby-version files

Version duplication

A minor annoyance of developing and deploying Ruby applications is having to declare and maintain a project’s Ruby version in two separate places.

3.2.2

source "https://rubygems.org"
ruby "3.2.2"

gem "rails"

A better way

Starting with the release of Bundler 2.4.19 (and subsequently refined with a bug fix and asdf support in 2.4.20), your Gemfile can use the new ruby file: syntax.

source "https://rubygems.org"
ruby file: ".ruby-version"

gem "rails"

How to upgrade

Taking advantage of this new Bundler feature requires a few easy steps.

1. Install the latest version of Bundler

gem install bundler

2. Update your project to use the new version

bundle commands will use the version of Bundler that is encoded into your Gemfile.lock. In order to use the new Bundler version, you’ll need to run this command to update the lock file.

bundle update --bundler

3. Edit your Gemfile

You can now edit your Gemfile to take advantage of the new syntax!

ruby file: ".ruby-version" # or ".tool-versions"

Caveats

Some deployment platforms dictate the version of Bundler that can be used. For example, as of September 2023, Heroku only allows Bundler 2.3.25 (nearly a year old!), which can’t parse the new Gemfile ruby file: syntax introduced in 2.4.19.

To avoid failed deployments, check the supported Bundler version on Heroku’s Ruby support page before adopting the new syntax.

References

• Pull request that introduced the ruby file: syntax: rubygems#6876
• Bundler 2.4.19 release notes
• After 2.4.19 was released, a small bug in the ruby file: implementation was subsequently identified and fixed: rubygems#6892
• Support for asdf’s .tool-versions was later added as well: rubygems#6898
• Bundler 2.4.20 release notes