In what order does rbenv decide which Ruby version is active, and how do rbenv shell, local and global map onto that order?

## The four sources, in order Every time a shim runs, rbenv answers one question: **which version name applies right now?** The answer comes from the first of four sources that yields a name: 1. **`RBENV_VERSION`** environment variable. `rbenv shell <version>` sets it; you can also export it yourself. 2. The nearest **`.ruby-version`** file, searched from the current directory upward to the filesystem root. `rbenv local <version>` writes one. 3. The **global version file** `~/.rbenv/version` (strictly `$RBENV_ROOT/version`). `rbenv global <version>` writes it. 4. Nothing found: the name is **`system`**, the Ruby found on `PATH` without rbenv's shims. | Command | Where it records the choice | Scope | Precedence | |---|---|---|---| | `rbenv shell 4.0.7` | `RBENV_VERSION` in the current shell | One shell session | Highest | | `rbenv local 4.0.7` | `./.ruby-version` | A directory tree | Middle | | `rbenv global 4.0.7` | `~/.rbenv/version` | Whole user account | Lowest before `system` | So an exported `RBENV_VERSION` beats a project's `.ruby-version`, and a `.ruby-version` beats the global default. ## How the .ruby-version search works The lookup (`rbenv version-file`) is a simple upward walk: - It starts at `RBENV_DIR`, which defaults to the current directory. For the `ruby` shim, when an argument is a path to an existing file, `RBENV_DIR` becomes that file's directory, so `ruby ~/tools/report/run.rb` honours the tool's own `.ruby-version`. - At each level it checks for a **non-empty** `.ruby-version`; an empty file is skipped as if absent. - It reads only the **first word** of the file, so trailing comments or a Windows line ending do no harm. - A value of `..` or anything containing `/` is rejected with an "invalid version" message. - If no file is found, the global version file is used, even if it does not exist (then the name is `system`). A `.ruby-version` in your home directory therefore pins every project under it that has no file of its own. ## Exact names only rbenv matches the name against directories under `~/.rbenv/versions` **exactly**. Two tolerances exist: `system` is never checked for existence, and a leading `ruby-` is stripped when the literal name is not installed, so `ruby-4.0.7` works if `4.0.7` is installed. There is **no prefix matching**: a file saying `4.0` fails even when `4.0.7` is installed: ```bash $ ruby -v rbenv: version `4.0' is not installed (set by /home/dev/app/.ruby-version) ``` Fix the file, or create a symlink `~/.rbenv/versions/4.0 -> 4.0.7`; the README explicitly allows entries in that directory to be symlinks. Note that ruby-build's `rbenv install 4.0` does resolve prefixes, but it installs under the full name, so it does not make a `4.0` file valid. ## rbenv shell and shell integration `rbenv shell` has to change the **current** shell's environment, which a child process cannot do. `rbenv init -` therefore defines an `rbenv()` shell function that routes `shell` and `rehash` to their `sh-` variants and evaluates their output. Without that integration you can still export `RBENV_VERSION` by hand. Related forms: - `rbenv shell --unset` removes `RBENV_VERSION`, letting the file-based sources apply again. - `rbenv shell -` restores the value that was set before the last `rbenv shell` call. - `rbenv shell` with no argument prints the current `RBENV_VERSION`, or errors if none is set. ## Asking rbenv where the version came from - `rbenv version` prints the name and its origin, for example `4.0.7 (set by /home/dev/app/.ruby-version)` or `3.4.7 (set by RBENV_VERSION environment variable)`. - `rbenv version-name` prints only the name. - `rbenv version-file` prints the path of the file that would be used. - `rbenv versions` lists all installed versions with an asterisk on the active one. Reading the origin first turns most "wrong Ruby" reports into a one-line diagnosis: the output names the exact variable or file to change. Because rbenv starts its search at `RBENV_DIR`, a script can ask about another directory without changing into it: `RBENV_DIR=~/code/invoice-api rbenv version` resolves the version exactly as a command run inside that project would. ## Why the order is designed this way The most temporary setting wins: an environment variable for an experiment in one terminal, then a committed per-project file, then a personal default. Because the lookup runs at every shim call, moving between directories needs no hook: the next command simply finds a different file.