Document .ruby-version

README.md

@@ -105,10 +105,10 @@ easy to fork and contribute any changes back upstream.
 
     **Zsh note**: Modify your `~/.zshenv` file instead of `~/.bash_profile`.
 
-    **Ubuntu note**: Ubuntu uses `~/.profile` for enabling certain path 
-    changes. This file won't be read if you create a `~/.bash_profile`. 
-    Therefore, it's recommended that you add this line and the one in 
-    point 3 below to your `~/.profile`. This has the added advantage 
+    **Ubuntu note**: Ubuntu uses `~/.profile` for enabling certain path
+    changes. This file won't be read if you create a `~/.bash_profile`.
+    Therefore, it's recommended that you add this line and the one in
+    point 3 below to your `~/.profile`. This has the added advantage
     of working under both bash and zsh.
 
 3. Add `rbenv init` to your shell to enable shims and autocompletion.
@@ -118,10 +118,10 @@ easy to fork and contribute any changes back upstream.
     ~~~
 
     **Zsh note**: Modify your `~/.zshenv` file instead of `~/.bash_profile`.
-    
+
     **Ubuntu note**: Same as Ubuntu note for point 2 above.
 
-4. Restart your shell as a login shell so the path changes take effect. 
+4. Restart your shell as a login shell so the path changes take effect.
     You can now begin using rbenv.
 
     ~~~ sh
@@ -235,7 +235,7 @@ first argument. The most common subcommands are:
 
 Sets the global version of Ruby to be used in all shells by writing
 the version name to the `~/.rbenv/version` file. This version can be
-overridden by a per-project `.rbenv-version` file, or by setting the
+overridden by a per-project `.ruby-version` file, or by setting the
 `RBENV_VERSION` environment variable.
 
     $ rbenv global 1.9.3-p327
@@ -249,7 +249,7 @@ currently configured global version.
 ### rbenv local ###
 
 Sets a local per-project Ruby version by writing the version name to
-an `.rbenv-version` file in the current directory. This version
+a `.ruby-version` file in the current directory. This version
 overrides the global, and can be overridden itself by setting the
 `RBENV_VERSION` environment variable or with the `rbenv shell`
 command.
@@ -261,6 +261,11 @@ configured local version. You can also unset the local version:
 
     $ rbenv local --unset
 
+Previous versions of rbenv stored local version specifications in a
+file named `.rbenv-version`. For backwards compatibility, rbenv will
+read a local version specified in an `.rbenv-version` file, but a
+`.ruby-version` file in the same directory will take precedence.
+
 ### rbenv shell ###
 
 Sets a shell-specific Ruby version by setting the `RBENV_VERSION`
@@ -289,7 +294,7 @@ the currently active version.
     $ rbenv versions
       1.8.7-p352
       1.9.2-p290
-    * 1.9.3-p327 (set by /Users/sam/.rbenv/global)
+    * 1.9.3-p327 (set by /Users/sam/.rbenv/version)
       jruby-1.7.1
       rbx-1.2.4
       ree-1.8.7-2011.03
@@ -300,7 +305,7 @@ 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)
+    1.8.7-p352 (set by /Volumes/37signals/basecamp/.ruby-version)
 
 ### rbenv rehash ###