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](/docs/installation/) 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**:

```bash
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:

```bash
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`:

```ruby
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:

```bash
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:

```bash
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:

```bash
bundle plugin uninstall posh-bundler
```

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