125 Gems, Bundler and Ruby versions [0.75d]

makandra is responsible for maintaining about 75 Ruby projects. These projects use a large number of different versions for Ruby, Rails and many gems. To be able to switch between projects easily, we must control every dependency our applications has.

Important

Work on this lesson in teacher mode.

Learning goals

• You can explain what a gem is and where installed gems live, and you can read a gem's source locally (e.g. with bundle open) or on GitHub.
• You can explain why we need a dependency manager like Bundler: resolving dependencies and giving every machine the same versions.
• You can explain the roles of Gemfile and Gemfile.lock, and why the lock file is committed.
• You can install, update and pin gems with Bundler, including updating a single gem conservatively and writing version constraints the way we do.
• You can explain what bundle exec does and when it is needed.
• You can explain why a project pins its Ruby version, and switch Ruby versions per project with a version manager (rbenv today; mise is the alternative that also covers Node).
• You can find and evaluate gems for a problem, e.g. on rubygems.org or Ruby Toolbox.

Note

JavaScript has the same problems — dependencies, lock files, runtime versions — and very similar solutions (yarn, nvm or mise). We explore them in a later card, once you have met JavaScript.

Resources

Read what's new to you, skim what's familiar, skip what you already master. Stop when you can meet the learning goals.

Your agent can also generate an overview, a tutorial or an explanation for anything here, tailored to what you already know. Just ask.

Gems and Bundler

• 📄 RubyGems guides: What is a gem? Show archive.org snapshot and RubyGems basics Show archive.org snapshot
• 📄 RubyGems guides: Managing dependencies with Bundler Show archive.org snapshot — why Bundler exists, Gemfile vs. Gemfile.lock, bundle exec
• 📄 RubyGems guides: Gemfile reference Show archive.org snapshot and Versioning Show archive.org snapshot — version constraints like ~>, groups, ruby file: ".ruby-version", and what version numbers mean
• 📄 Best practice: how to manage versions in a Gemfile — our card
• 📄 How to update a single gem conservatively — a major Bundler caveat, our card
• 📄 Understanding Bundler — to bundle exec or not? Show archive.org snapshot — the same story told as a narrative, if you prefer that to a reference

Ruby versions

• 📄 rbenv README Show archive.org snapshot — how shims and .ruby-version work; our short introduction
• 📄 mise: Getting started Show archive.org snapshot and Ruby Show archive.org snapshot — the one-tool alternative for Ruby and Node; note that reading .ruby-version files must be switched on
• 📄 Mise vs. rbenv Show archive.org snapshot — balanced comparison (2025)
• ▶️ Bundler's Ruby version file option Show archive.org snapshot — GoRails, free episode

Finding gems

• 📄 RubyGems.org Show archive.org snapshot — the registry: dependencies and version history of every gem
• 📄 Ruby Toolbox Show archive.org snapshot — popular gems by category

Exercises

Working with rbenv

• Use rbenv to install an older but still maintained Ruby version, like 3.3.
• In the last lesson you moved your address book into a repository of its own. You work in that repository for both exercises on this card.
• Freeze that program's Ruby version to the one you just installed by adding an .ruby-version file.
• Open a new terminal and check your default Ruby version (ruby -v)
• Now cd into the directory for the address book app. Observe how rbenv has automatically switched to the Ruby version from your .ruby-version.
• Commit and push your changes.
• Ask your agent how the same workflow looks with mise Show archive.org snapshot , the tool we may switch to.

Tip

RubyMine seems to only parse the .ruby-version file when you're opening a project for the first time. When you're changing the .ruby-version of an existing project, RubyMine may not automatically detect that you want to use another version.

If this is the case, go to File / Settings / Languages & Frameworks / Ruby SDK & Gems and select the new Ruby version.

Working with Bundler

• Add a Gemfile to your address book repository and let bundler create a Gemfile.lock. It won't have any dependencies at first.
• Commit the Gemfile and Gemfile.lock.
• Use Bundler to install the Faker Show archive.org snapshot gem in the exact version 3.2.0.
• Observe the changes Bundler made to your Gemfile.lock. Compare these changes to faker's dependencies on rubygems.org Show archive.org snapshot .
• In your program, use Faker to create 100 contacts with fake data.
• Commit your changes.
• Upgrade Faker conservatively (bundle update --conservative faker) and compare with what a plain bundle update faker would have done (see "How to update a single gem conservatively" in the resources).
• Observe the changes Bundler made to your Gemfile.lock during the upgrade.
• Commit and push your changes.