Previously, when someone activated rbenv shim `foo`, rbenv would error out if `RBENV_ROOT/versions/RBENV_VERSION/bin/foo` did not exist.
This change allows `foo` to be additionally looked up in PATH as fallback. This prevents a case where one of the Ruby versions is shadowing a system-wide command of the same name, preventing the use of the global command across all other Ruby versions.
rbenv used to be strict around this, allowing the fallback to avoid ever falling back to system Ruby for invocations like `bundle` if the current Ruby version did not yet install Bundler. The current approach prevents this scenario by explicitly disallowing fallback for the following executables: ruby, rake, gem, bundle, bundler, irb, rdoc, ri.
Considerations:
- `./libexec/rbenv` executable is the entrypoint to the program;
- BASH_SOURCE might be the path to a symlink that has activated `./libexec/rbenv`;
- We must resolve the symlink to learn where rbenv's libexec directory is;
- It's not guaranteed that rbenv commands will always remain directly under their own "libexec" directory, since a package maintainer can change that, e.g. rbenv commands are sometimes placed into `/usr/libexec/rbenv/*`;
- Resolving symlinks might fail and in that case we just assume rbenv project layout.
The rehash process will now discover executables in additional locations:
- `~/.gem/ruby/<version>/bin/*`
- `$GEM_HOME/bin`
The `rbenv which` (and thus `rbenv exec`) command will also search these locations when looking up a command. This enables shims to dispatch calls to executables added by `gem install --user-install`.
Note that this support is limited:
- It will only work with C Ruby, as it's difficult to guess the `~/.gem/<engine>/<version>` directory for other Rubies without actually loading Ruby;
- It will only work for RBENV_VERSION values in the format `X.Y.Z` and not "system".
rbenv is now the most popular Ruby version manager, so we don't need to
sell it so hard. Instead, help the reader find installation and usage
instructions more easily.
The installation instructions are now simpler and pointing out that
ruby-build needs a separate install is now done in the "Installing Ruby
versions" section.
Finally, link to a wiki doc about potential downsides of rbenv along
with the comparison of different version manager tools.
Homebrew places the rbenv executable in a location such as
`/usr/local/bin/rbenv`, which is in PATH. However, that is a symlink to
`/usr/local/Cellar/rbenv/<VERSION>/bin/rbenv`, which is itself a symlink to
`/usr/local/Cellar/rbenv/<VERSION>/libexec/rbenv`. Upon executing, rbenv
will add its own directory to PATH so that it can easily invoke its
subcommands.
When generating shims during `rbenv rehash`, rbenv will try to put the
absolute path to itself inside each shim so that shims would work even
if rbenv itself isn't in PATH. Under Homebrew, rbenv's directory will be
the versioned directory in Homebrew's Cellar. However, due to Homebrew's
auto-cleanup functionality, shims generated this way will be broken
after upgrading rbenv because of the versioned Cellar path.
This changes how rbenv discovers itself in PATH: it will look at the
original PATH, not in the one modified by rbenv, with the intention of
excluding results under rbenv's own `libexec/`. If rbenv wasn't found in
PATH, return the absolute path to rbenv's own `bin/rbenv`.
This speeds up subsequent `rbenv init -` executions for the user who
followed these instructions because the shell will no longer have to be
detected each time.
