From 27788c995ccca8046a84816c9cfc16437b0ade43 Mon Sep 17 00:00:00 2001
From: Fabio Rehm <fgrehm@gmail.com>
Date: Sat, 7 Dec 2013 12:57:39 -0200
Subject: [PATCH] Document rvm gotchas

Closes GH-43
---
 docs/buckets/rvm.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/docs/buckets/rvm.md b/docs/buckets/rvm.md
index a216323..f19ac49 100644
--- a/docs/buckets/rvm.md
+++ b/docs/buckets/rvm.md
@@ -14,3 +14,46 @@ Vagrant.configure("2") do |config|
   config.cache.enable :gem
 end
 ```
+
+## Heads up!
+
+If you are installing rvm, rubies and gems on a single provisioning step, **you
+will not benefit from this bucket**. There is absolutely no way we can "magically"
+hook into your provisioning scripts to configure things for leveraging the cache.
+
+For instance, the following shell provisioner **will result in no package cached at
+all**:
+
+```ruby
+config.vm.provision :shell, privileged: false, inline: %[
+  curl -L https://get.rvm.io | bash -s stable
+  rvm install 1.9.3
+  rvm use 1.9.3 --default
+  cd /path/to/project
+  bundle install
+]
+```
+
+To work around that you can either configure things by hand on your provisioning
+scripts or you can enable automatic bucket detection and split your scripts into
+multiple stages:
+
+```ruby
+# Install RVM so that Ruby tarballs are cached
+config.vm.provision :shell, privileged: false, inline: %[
+  curl -L https://get.rvm.io | bash -s stable
+]
+
+# Install Ruby 1.9.3 making use of the RVM cache and configure the RubyGems
+# cache afterwards
+config.vm.provision :shell, privileged: false, inline: %[
+  rvm install 1.9.3
+  rvm use 1.9.3 --default
+]
+
+# Install gems making use of the RubyGems cache
+config.vm.provision :shell, privileged: false, inline: %[
+  cd /path/to/project
+  bundle install
+]
+```