README instructions for persisting .bundle directory

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')
 ```