Automatic sync with Bundler

The posh-bundler plugin keeps your local docs in sync after bundle install and bundle update, including targeted updates such as bundle update rails. Install POSH first and make sure posh is on your PATH. The plugin requires Ruby 2.7 or newer and Bundler >= 2.3.17, < 5.0; it does not install the POSH executable.

This is an optional local-development tool, not an application or deployment dependency. Install it on development machines; production and CI do not need it.

Enable for one project

On your development machine, from your Ruby project’s directory, enable it for that project only:

bundle plugin install posh-bundler

This does not add an application dependency to your Gemfile. Installing inside one project does not enable automatic sync in other projects. Repeat the command in each project where you want automatic sync, or install the plugin globally.

Enable for all your projects

Run the same command from a directory with no Gemfile in it or any parent directory. For example, if your home directory meets that requirement:

cd ~
bundle plugin install posh-bundler

Global installations are scoped to your user and Bundler’s plugin configuration.

Shared project setup

For a shared project-level opt-in, you can instead declare the plugin in your Gemfile. Bundler installs it on the next bundle install:

plugin "posh-bundler"

Use plugin, not gem: this is a Bundler extension, not an application dependency. Each contributor still needs POSH installed separately. The directive is not automatically limited to development. Prefer the per-developer installation command above if you do not want Bundler to install the plugin in CI or production.

How syncing works

The plugin runs posh sync --project /path/to/project once after the installer succeeds and writes Gemfile.lock. It also runs when your gems are already installed. Sync runs synchronously and uses the network; POSH reuses installed docsets. If POSH is missing or sync fails, you get a warning without failing Bundler. Run posh sync to retry manually.

The plugin targets the standard Gemfile.lock that POSH discovers in your project. It does not run after bundle lock, git pull, or a branch switch. Run posh sync manually after those operations if dependencies changed.

Automatic sync not running?

From the project where you expect syncing to happen, check:

bundle plugin list

If posh-bundler is not listed (or Bundler reports No plugins installed), it is not enabled for that project. Install it there or use the global setup above. Then run bundle install to trigger a sync without updating dependency versions.

Skip automatic sync

For a single command, for example while offline, in CI, or during a production deployment:

POSH_AUTO_SYNC=0 bundle install

If the plugin is present in CI or production, set POSH_AUTO_SYNC=0 in those environments. The plugin does not detect development or production automatically. This skips syncing; Bundler can still install a plugin declared in the Gemfile. Manual posh sync commands still work.

Remove the plugin

Run this from the project where you enabled it, or outside a project for a global installation:

bundle plugin uninstall posh-bundler

If you declared plugin "posh-bundler" in your Gemfile, remove that line too so Bundler does not reinstall it.