diff --git a/README.md b/README.md index d3488569..df320c20 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,58 @@ # Simple Ruby Version Management: rbenv -rbenv lets you easily switch between multiple versions of Ruby. It's simple, unobtrusive, understandable, and follows in the Unix tradition of single-purpose tools that do one thing well. +rbenv lets you easily switch between multiple versions of Ruby. It's +simple, unobtrusive, understandable, and follows in the Unix tradition +of single-purpose tools that do one thing well. ### rbenv _does…_ * Let you **change the default Ruby version** on a per-user basis. * Provide support for **per-project Ruby versions**. -* Allow you to **override the Ruby version** with an environment variable. +* Allow you to **override the Ruby version** with an environment + variable. ### rbenv _does not…_ -* **Need to be loaded into your shell.** Instead, rbenv's shim approach works by adding a directory to your `$PATH`. +* **Need to be loaded into your shell.** Instead, rbenv's shim + approach works by adding a directory to your `$PATH`. * **Override shell commands like `cd`.** That's just obnoxious! -* **Have a configuration file.** There's nothing to configure except which version of Ruby you want to use. -* **Install Ruby.** You can build and install Ruby yourself, or use [ruby-build](https://github.com/sstephenson/ruby-build.git) to automate the process. -* **Manage gemsets.** [Bundler](http://gembundler.com/) is a better way to manage application dependencies. If you have projects that are not yet using Bundler you can install the [rbenv-gemset](https://github.com/jamis/rbenv-gemset) plugin. -* **Require changes to Ruby libraries for compatibility.** The simplicity of rbenv means as long as it's in your `$PATH`, [nothing](https://rvm.beginrescueend.com/integration/bundler/) [else](https://rvm.beginrescueend.com/integration/capistrano/) needs to know about it. -* **Prompt you with warnings when you switch to a project.** Instead of executing arbitrary code, rbenv reads just the version name from each project. There's nothing to "trust." +* **Have a configuration file.** There's nothing to configure except + which version of Ruby you want to use. +* **Install Ruby.** You can build and install Ruby yourself, or use + [ruby-build](https://github.com/sstephenson/ruby-build.git) to + automate the process. +* **Manage gemsets.** [Bundler](http://gembundler.com/) is a better + way to manage application dependencies. If you have projects that + are not yet using Bundler you can install the + [rbenv-gemset](https://github.com/jamis/rbenv-gemset) plugin. +* **Require changes to Ruby libraries for compatibility.** The + simplicity of rbenv means as long as it's in your `$PATH`, + [nothing](https://rvm.beginrescueend.com/integration/bundler/) + [else](https://rvm.beginrescueend.com/integration/capistrano/) + needs to know about it. +* **Prompt you with warnings when you switch to a project.** Instead + of executing arbitrary code, rbenv reads just the version name + from each project. There's nothing to "trust." ## How It Works -rbenv operates on the per-user directory `~/.rbenv`. Version names in rbenv correspond to subdirectories of `~/.rbenv/versions`. For example, you might have `~/.rbenv/versions/1.8.7-p354` and `~/.rbenv/versions/1.9.3-preview1`. +rbenv operates on the per-user directory `~/.rbenv`. Version names in +rbenv correspond to subdirectories of `~/.rbenv/versions`. For +example, you might have `~/.rbenv/versions/1.8.7-p354` and +`~/.rbenv/versions/1.9.3-preview1`. -Each version is a working tree with its own binaries, like `~/.rbenv/versions/1.8.7-p354/bin/ruby` and `~/.rbenv/versions/1.9.3-preview1/irb`. rbenv makes _shim binaries_ for every such binary across all installed versions of Ruby. +Each version is a working tree with its own binaries, like +`~/.rbenv/versions/1.8.7-p354/bin/ruby` and +`~/.rbenv/versions/1.9.3-preview1/irb`. rbenv makes _shim binaries_ +for every such binary across all installed versions of Ruby. -These shims are simple wrapper scripts that live in `~/.rbenv/shims` and detect which Ruby version you want to use. They insert the directory for the selected version at the beginning of your `$PATH` and then execute the corresponding binary. +These shims are simple wrapper scripts that live in `~/.rbenv/shims` +and detect which Ruby version you want to use. They insert the +directory for the selected version at the beginning of your `$PATH` +and then execute the corresponding binary. -Because of the simplicity of the shim approach, all you need to use rbenv is `~/.rbenv/shims` in your `$PATH`. +Because of the simplicity of the shim approach, all you need to use +rbenv is `~/.rbenv/shims` in your `$PATH`. ## Installation @@ -37,47 +63,65 @@ rbenv is a young project, so for now you must install it from source. $ cd $ git clone git://github.com/sstephenson/rbenv.git .rbenv -2. Add `~/.rbenv/bin` to your `$PATH` for access to the `rbenv` command-line utility. +2. Add `~/.rbenv/bin` to your `$PATH` for access to the `rbenv` +command-line utility. $ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bash_profile -3. Add rbenv's shims directory to your `$PATH` and set up Bash autocompletion. (If you prefer not to load rbenv in your shell, you can manually add `$HOME/.rbenv/shims` to your path in step 2.) +3. Add rbenv's shims directory to your `$PATH` and set up Bash +autocompletion. (If you prefer not to load rbenv in your shell, you +can manually add `$HOME/.rbenv/shims` to your path in step 2.) $ echo 'eval "$(rbenv init -)"' >> .bash_profile 4. Restart your shell. You can now begin using rbenv. - $ exec $SHELL + $ exec -5. Install Ruby versions into `~/.rbenv/versions`. For example, to install Ruby 1.9.2-p290, download and unpack the source, then run: +5. Install Ruby versions into `~/.rbenv/versions`. For example, to +install Ruby 1.9.2-p290, download and unpack the source, then run: $ ./configure --prefix=~/.rbenv/versions/1.9.2-p290 $ make $ make install - The [ruby-build](https://github.com/sstephenson/ruby-build) project simplifies this process to a single command: + The [ruby-build](https://github.com/sstephenson/ruby-build) + project simplifies this process to a single command: $ ruby-build 1.9.2-p290 ~/.rbenv/versions/1.9.2-p290 -6. Rebuild the shim binaries. You should do this any time you install a new Ruby binary (for example, when installing a new Ruby version, or when installing a gem that provides a binary). +6. Rebuild the shim binaries. You should do this any time you install +a new Ruby binary (for example, when installing a new Ruby version, or +when installing a gem that provides a binary). $ rbenv rehash ## Usage -Like `git`, the `rbenv` command delegates to subcommands based on its first argument. The most common subcommands are: +Like `git`, the `rbenv` command delegates to subcommands based on its +first argument. The most common subcommands are: -* **set-default** — sets the default version of Ruby to be used in all shells by writing the version name to the `~/.rbenv/default` file. This version can be overridden by a per-project `.rbenv-version` file, or by setting the `RBENV_VERSION` environment variable. +* **set-default** — sets the default version of Ruby to be used in all + shells by writing the version name to the `~/.rbenv/default` + file. This version can be overridden by a per-project + `.rbenv-version` file, or by setting the `RBENV_VERSION` + environment variable. $ rbenv set-default 1.9.2-p290 - The special version name `system` tells rbenv to use the system Ruby (detected by searching your `$PATH`). + The special version name `system` tells rbenv to use the system + Ruby (detected by searching your `$PATH`). -* **set-local** — sets a local per-project Ruby version by writing the version name to an `.rbenv-version` file in the current directory. This version overrides the default, and can be overridden itself by setting the `RBENV_VERSION` environment variable. +* **set-local** — sets a local per-project Ruby version by writing the + version name to an `.rbenv-version` file in the current + directory. This version overrides the default, and can be + overridden itself by setting the `RBENV_VERSION` environment + variable. $ rbenv set-local rbx-1.2.4 -* **versions** — lists all Ruby versions known to rbenv, and shows an asterisk next to the currently active version. +* **versions** — lists all Ruby versions known to rbenv, and shows an + asterisk next to the currently active version. $ rbenv versions 1.8.7-p352 @@ -87,16 +131,20 @@ Like `git`, the `rbenv` command delegates to subcommands based on its first argu rbx-1.2.4 ree-1.8.7-2011.03 -* **version** — displays the currently active Ruby version, along with information on how it was set. +* **version** — displays the currently active Ruby version, along with + information on how it was set. $ rbenv version 1.8.7-p352 (set by /Volumes/37signals/basecamp/.rbenv-version) ## Contributing -The rbenv source code is [hosted on GitHub](https://github.com/sstephenson/rbenv). It's clean, modular, and easy to understand, even if you're not a shell hacker. +The rbenv source code is [hosted on +GitHub](https://github.com/sstephenson/rbenv). It's clean, modular, +and easy to understand, even if you're not a shell hacker. -Please feel free to submit pull requests and file bugs on the [issue tracker](https://github.com/sstephenson/rbenv/issues). +Please feel free to submit pull requests and file bugs on the [issue +tracker](https://github.com/sstephenson/rbenv/issues). ## License