From 697e7455cd3d00da31087492b32cffeb4746abe5 Mon Sep 17 00:00:00 2001
From: Ilya Vassilevsky <vassilevsky@gmail.com>
Date: Mon, 22 Jan 2018 19:06:09 +0400
Subject: [PATCH] README instructions for persisting .bundle directory

---
 README.md | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 119418dd..26cdaf04 100644
--- a/README.md
+++ b/README.md
@@ -37,11 +37,33 @@ Require in `Capfile` to use the default task:
 require 'capistrano/bundler'
 ```
 
-The task will run before `deploy:updated` as part of Capistrano's default deploy, or can be run in isolation with `cap production bundler:install`
+The task will run before `deploy:updated` as part of Capistrano's default deploy, or can be run in isolation with `cap production bundler:install`.
+
+In order for Bundler to work efficiently on the server, its project configuration directory (`<release_path>/.bundle/`) should be persistent across releases.
+You need to add it to the `linked_dirs` Capistrano variable:
+
+Capisrano **3.5**+:
+
+```ruby
+# config/deploy.rb
+
+append :linked_dirs, '.bundle'
+```
+
+Capistrano < 3.5:
+
+```ruby
+# config/deploy.rb
+
+set :linked_dirs, fetch(:linked_dirs, []) << '.bundle'
+```
+
+It will still work fine with non-persistent configuration directory, but then it will have to re-resolve all gems on each deploy.
 
 By default, the plugin adds `bundle exec` prefix to common executables listed in `bundle_bins` option. This currently applies for `gem`, `rake` and `rails`.
 
 You can add any custom executable to this list:
+
 ```ruby
 set :bundle_bins, fetch(:bundle_bins, []).push('my_new_binary')
 ```