Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 180 lines (131 sloc) 6.843 kb
a804b5e Sam Stephenson Add LICENSE and README.md
authored
1 # Simple Ruby Version Management: rbenv
2
b4a9164 Sam Stephenson Hard-wrap
authored
3 rbenv lets you easily switch between multiple versions of Ruby. It's
77964fb Sam Stephenson Simplify
authored
4 simple, unobtrusive, and follows the UNIX tradition of single-purpose
5 tools that do one thing well.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
6
e8d010f Sam Stephenson Fix italics
authored
7 ### rbenv _does…_
a804b5e Sam Stephenson Add LICENSE and README.md
authored
8
9 * Let you **change the default Ruby version** on a per-user basis.
10 * Provide support for **per-project Ruby versions**.
b4a9164 Sam Stephenson Hard-wrap
authored
11 * Allow you to **override the Ruby version** with an environment
12 variable.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
13
e8d010f Sam Stephenson Fix italics
authored
14 ### rbenv _does not…_
a804b5e Sam Stephenson Add LICENSE and README.md
authored
15
b4a9164 Sam Stephenson Hard-wrap
authored
16 * **Need to be loaded into your shell.** Instead, rbenv's shim
17 approach works by adding a directory to your `$PATH`.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
18 * **Override shell commands like `cd`.** That's just obnoxious!
b4a9164 Sam Stephenson Hard-wrap
authored
19 * **Have a configuration file.** There's nothing to configure except
20 which version of Ruby you want to use.
21 * **Install Ruby.** You can build and install Ruby yourself, or use
22 [ruby-build](https://github.com/sstephenson/ruby-build.git) to
23 automate the process.
24 * **Manage gemsets.** [Bundler](http://gembundler.com/) is a better
25 way to manage application dependencies. If you have projects that
26 are not yet using Bundler you can install the
27 [rbenv-gemset](https://github.com/jamis/rbenv-gemset) plugin.
28 * **Require changes to Ruby libraries for compatibility.** The
29 simplicity of rbenv means as long as it's in your `$PATH`,
30 [nothing](https://rvm.beginrescueend.com/integration/bundler/)
31 [else](https://rvm.beginrescueend.com/integration/capistrano/)
32 needs to know about it.
33 * **Prompt you with warnings when you switch to a project.** Instead
34 of executing arbitrary code, rbenv reads just the version name
35 from each project. There's nothing to "trust."
a804b5e Sam Stephenson Add LICENSE and README.md
authored
36
37 ## How It Works
38
b4a9164 Sam Stephenson Hard-wrap
authored
39 rbenv operates on the per-user directory `~/.rbenv`. Version names in
40 rbenv correspond to subdirectories of `~/.rbenv/versions`. For
41 example, you might have `~/.rbenv/versions/1.8.7-p354` and
42 `~/.rbenv/versions/1.9.3-preview1`.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
43
b4a9164 Sam Stephenson Hard-wrap
authored
44 Each version is a working tree with its own binaries, like
45 `~/.rbenv/versions/1.8.7-p354/bin/ruby` and
46 `~/.rbenv/versions/1.9.3-preview1/irb`. rbenv makes _shim binaries_
47 for every such binary across all installed versions of Ruby.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
48
b4a9164 Sam Stephenson Hard-wrap
authored
49 These shims are simple wrapper scripts that live in `~/.rbenv/shims`
50 and detect which Ruby version you want to use. They insert the
51 directory for the selected version at the beginning of your `$PATH`
52 and then execute the corresponding binary.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
53
b4a9164 Sam Stephenson Hard-wrap
authored
54 Because of the simplicity of the shim approach, all you need to use
55 rbenv is `~/.rbenv/shims` in your `$PATH`.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
56
57 ## Installation
58
59 rbenv is a young project, so for now you must install it from source.
60
61 1. Check out rbenv into `~/.rbenv`.
62
63 $ cd
64 $ git clone git://github.com/sstephenson/rbenv.git .rbenv
65
b4a9164 Sam Stephenson Hard-wrap
authored
66 2. Add `~/.rbenv/bin` to your `$PATH` for access to the `rbenv`
67 command-line utility.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
68
69 $ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bash_profile
70
b4a9164 Sam Stephenson Hard-wrap
authored
71 3. Add rbenv's shims directory to your `$PATH` and set up Bash
72 autocompletion. (If you prefer not to load rbenv in your shell, you
73 can manually add `$HOME/.rbenv/shims` to your path in step 2.)
a804b5e Sam Stephenson Add LICENSE and README.md
authored
74
75 $ echo 'eval "$(rbenv init -)"' >> .bash_profile
76
77 4. Restart your shell. You can now begin using rbenv.
78
b4a9164 Sam Stephenson Hard-wrap
authored
79 $ exec
a804b5e Sam Stephenson Add LICENSE and README.md
authored
80
b4a9164 Sam Stephenson Hard-wrap
authored
81 5. Install Ruby versions into `~/.rbenv/versions`. For example, to
82 install Ruby 1.9.2-p290, download and unpack the source, then run:
a804b5e Sam Stephenson Add LICENSE and README.md
authored
83
84 $ ./configure --prefix=~/.rbenv/versions/1.9.2-p290
85 $ make
86 $ make install
87
b4a9164 Sam Stephenson Hard-wrap
authored
88 The [ruby-build](https://github.com/sstephenson/ruby-build)
89 project simplifies this process to a single command:
a804b5e Sam Stephenson Add LICENSE and README.md
authored
90
91 $ ruby-build 1.9.2-p290 ~/.rbenv/versions/1.9.2-p290
92
b4a9164 Sam Stephenson Hard-wrap
authored
93 6. Rebuild the shim binaries. You should do this any time you install
94 a new Ruby binary (for example, when installing a new Ruby version, or
95 when installing a gem that provides a binary).
a804b5e Sam Stephenson Add LICENSE and README.md
authored
96
97 $ rbenv rehash
98
99 ## Usage
100
b4a9164 Sam Stephenson Hard-wrap
authored
101 Like `git`, the `rbenv` command delegates to subcommands based on its
102 first argument. The most common subcommands are:
a804b5e Sam Stephenson Add LICENSE and README.md
authored
103
b4a9164 Sam Stephenson Hard-wrap
authored
104 * **set-default** — sets the default version of Ruby to be used in all
105 shells by writing the version name to the `~/.rbenv/default`
106 file. This version can be overridden by a per-project
107 `.rbenv-version` file, or by setting the `RBENV_VERSION`
108 environment variable.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
109
110 $ rbenv set-default 1.9.2-p290
111
b4a9164 Sam Stephenson Hard-wrap
authored
112 The special version name `system` tells rbenv to use the system
113 Ruby (detected by searching your `$PATH`).
a804b5e Sam Stephenson Add LICENSE and README.md
authored
114
b4a9164 Sam Stephenson Hard-wrap
authored
115 * **set-local** — sets a local per-project Ruby version by writing the
116 version name to an `.rbenv-version` file in the current
117 directory. This version overrides the default, and can be
118 overridden itself by setting the `RBENV_VERSION` environment
119 variable.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
120
121 $ rbenv set-local rbx-1.2.4
122
b4a9164 Sam Stephenson Hard-wrap
authored
123 * **versions** — lists all Ruby versions known to rbenv, and shows an
124 asterisk next to the currently active version.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
125
126 $ rbenv versions
127 1.8.7-p352
128 1.9.2-p290
129 * 1.9.3-preview1 (set by /Users/sam/.rbenv/default)
130 jruby-1.6.3
131 rbx-1.2.4
132 ree-1.8.7-2011.03
133
b4a9164 Sam Stephenson Hard-wrap
authored
134 * **version** — displays the currently active Ruby version, along with
135 information on how it was set.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
136
137 $ rbenv version
138 1.8.7-p352 (set by /Volumes/37signals/basecamp/.rbenv-version)
139
f8f49fd Sam Stephenson Document rbenv-rehash
authored
140 * **rehash** — installs shims for all Ruby binaries known to rbenv
141 (i.e., `~/.rbenv/versions/*/bin/*`). Run this command after you
142 install a new version of Ruby, or install a gem that provides
143 binaries.
144
145 $ rbenv rehash
146
a804b5e Sam Stephenson Add LICENSE and README.md
authored
147 ## Contributing
148
b4a9164 Sam Stephenson Hard-wrap
authored
149 The rbenv source code is [hosted on
150 GitHub](https://github.com/sstephenson/rbenv). It's clean, modular,
151 and easy to understand, even if you're not a shell hacker.
a804b5e Sam Stephenson Add LICENSE and README.md
authored
152
b4a9164 Sam Stephenson Hard-wrap
authored
153 Please feel free to submit pull requests and file bugs on the [issue
154 tracker](https://github.com/sstephenson/rbenv/issues).
a804b5e Sam Stephenson Add LICENSE and README.md
authored
155
156 ## License
157
158 (The MIT license)
159
160 Copyright (c) 2011 Sam Stephenson
161
162 Permission is hereby granted, free of charge, to any person obtaining
163 a copy of this software and associated documentation files (the
164 "Software"), to deal in the Software without restriction, including
165 without limitation the rights to use, copy, modify, merge, publish,
166 distribute, sublicense, and/or sell copies of the Software, and to
167 permit persons to whom the Software is furnished to do so, subject to
168 the following conditions:
169
170 The above copyright notice and this permission notice shall be
171 included in all copies or substantial portions of the Software.
172
173 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
174 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
175 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
176 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
177 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
178 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
e8d010f Sam Stephenson Fix italics
authored
179 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.