Pebellslearn by building
0%
RoadmapsMatrixCoursesSandboxSign in
Introduction and Setup  ›  Capstone Project

Version Managers

Managers 15 minA version manager such as rbenv, chruby, asdf or RVM keeps several Ruby versions installed and picks one per project from a .ruby-version file.

Version Managers

Bean Cart's sales script runs on Ruby 3.3. Then a friend asks for help with their shop's older app, which only works on Ruby 3.1. Uninstalling and reinstalling Ruby every time you switch folders would be miserable. A version manager lets both live on one machine and picks the right one for you.

The rule

A version manager keeps many Rubies; the project folder picks one.

A version manager installs Ruby versions into your home directory and switches between them. The popular ones:

  • rbenv: small and focused. Pairs with ruby-build to install versions.
  • chruby: even smaller; pairs with ruby-install.
  • asdf (and its newer relative, mise): manage Ruby alongside Node, Python and other languages with one tool.
  • RVM: the oldest, with the most features, including its own named sets of gems. It changes more of your shell's behaviour than the others.

They all honour one small, shared convention: a file named .ruby-version in a project folder, containing just a version number.

rbenv install 3.3.5      # download and build Ruby 3.3.5
cd bean_cart
rbenv local 3.3.5        # writes .ruby-version containing 3.3.5
cat .ruby-version        # 3.3.5
ruby -v                  # ruby 3.3.5 ...

There is also a global default used when no .ruby-version file is found, set with rbenv global 3.3.5 (or the equivalent in your tool). The local file wins over the global default.

Commit .ruby-version to the project's repository. Then everyone who clones it, and many hosting services, will use the same Ruby you did.

The shortcut

To predict which Ruby will run, walk up from your current folder looking for .ruby-version. The first one you find decides. If there is none all the way up, the global default decides.

Which Ruby runs where?Step 1 of 4

  1. The setup

    ~/code/bean_cart/.ruby-version says 3.3.5. ~/code/old_shop/.ruby-version says 3.1.6. The global default is 3.2.4.

The trap: a .ruby-version asking for a version you have not installed. The manager will complain rather than quietly use another one. Install that version, and the message goes away.

Drills

Answer fast — trust the rule.

quick drill

What does a .ruby-version file contain?

quick drill

Which command writes a .ruby-version file into the current folder with rbenv?

quick drill

You are in ~/code/bean_cart/lib/reports. Only ~/code/bean_cart has a .ruby-version (3.3.5), and the global default is 3.2.4. Which Ruby runs?

quick drill

Which tool manages Ruby alongside Node and Python versions with one command set?

quick drill

Why commit .ruby-version to a project's repository?

Remember

  • A version manager keeps many Rubies; the project folder picks one with .ruby-version.
  • Walk up from where you are: the first .ruby-version wins, otherwise the global default.
  • Trap: a .ruby-version naming a version you have not installed yet.

Practice — level up

0/1 solved

Write your answer, then compare it with a rubric and a model answer.

ExplainTwo projects, two Rubies

You maintain one project that needs Ruby 3.3 and another that needs Ruby 3.1. Explain how a version manager handles this and how it decides which Ruby runs in a given folder.