What Bundler does

A thread the Rails CLI course left open

The Rails CLI: rails new course ended its setup lesson with this: "Gemfile and Gemfile.lock already exist when bin/setup runs bundle install. The lock file records the exact resolved gem versions. How that works, and how to manage gems on purpose, is for Bundler & Gemfile." This is that course.

Two numbers that show the problem

$ bundle check
The Gemfile's dependencies are satisfied

$ bundle install
Bundle complete! 42 Gemfile dependencies, 160 gems now installed.

Both ran against this project. The Gemfile declares 42 gems by name, and 160 get installed. The gap exists because almost every gem depends on other gems. rails alone pulls in actionpack, activerecord, activesupport and more, each with its own version requirements, and all of them have to agree.

Both numbers move whenever the Gemfile changes, so yours will differ. The shape stays the same: the second number is much larger than the first, and the difference is everything Bundler resolved without being asked.

Resolving the constraints

Bundler's job is to find one version of each of those gems that satisfies every constraint at once: this project's Gemfile and every gem's own requirements. Picking a version of one gem that conflicts with what another needs would break the app when it loads. So Bundler solves the constraints instead of installing whatever is newest.

Locking the answer

Once Bundler finds an answer, it writes every gem and its exact version into Gemfile.lock. That file makes sure the same versions are used again, on any machine, instead of Bundler solving from scratch and maybe landing somewhere else. Lesson 3 covers it.

What this course covers

1. Gemfile: what a developer declares, and what the ~> and >= constraints mean.
2. Gemfile.lock: the resolved snapshot Bundler writes and nobody edits by hand.
3. bundle install: what it does when Gemfile.lock already matches, and when it doesn't.
4. bundle exec: why a plain Ruby script needs it and bin/rails doesn't.
5. Checking these claims against this project's Gemfile.
6. A wrap-up, and what comes next.

By the end, the bundle install step in bin/setup is a step you can explain.