herdr-worktreeinclude

A Herdr plugin that keeps Herdr-created Git worktrees inside the project and restores selected ignored files into them.

What it does

Use Herdr's normal New worktree UI. After creation, the plugin automatically:

• moves the checkout from Herdr's global directory to <project>/.herdr/worktrees/<branch>;
• copies files selected by .worktreeinclude from the primary checkout;
• opens the relocated worktree as the active Herdr workspace.

When you remove a plugin-managed worktree through Herdr's normal UI, an unchanged branch (one already contained in the primary checkout's HEAD) is removed silently. For a branch with unique commits, Herdr shows a small popup pane: press d to safely delete the local branch or Enter to keep it.

The plugin cannot change Herdr's built-in creation/removal dialogs. It uses lifecycle hooks immediately after those dialogs complete.

Requirements

• Herdr with plugin support (currently the Preview channel)
• Git
• Node.js 20 or later
• macOS or Linux

Install

Once the repository is public and tagged with the GitHub topic herdr-plugin:

herdr plugin install serhii-chernenko/herdr-worktreeinclude

To install a specific release:

herdr plugin install serhii-chernenko/herdr-worktreeinclude --ref v0.1.0

For local development, link it into the current Herdr session:

herdr plugin link /path/to/herdr-worktreeinclude

Plugins are registered per Herdr session

Both plugin install and plugin link only register the plugin in the Herdr session you ran the command from. Herdr keeps a separate, durable plugin registry per named session (herdr session list shows your sessions); installing in one session does not install it in any other, including sessions created later. If a New worktree dialog suggests Herdr's global ~/.herdr/worktrees/... path instead of a project-local one, the plugin most likely just isn't installed in that particular session yet.

Target a specific named session with --session:

herdr --session my-session plugin install serhii-chernenko/herdr-worktreeinclude

To install it into every session at once:

for s in $(herdr session list --json | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>console.log(JSON.parse(d).sessions.map(s=>s.name).join("\n")))'); do
  herdr --session "$s" plugin install serhii-chernenko/herdr-worktreeinclude --yes
done

A stopped session's server must be running to accept a plugin registration (a plain herdr --session <name> server in the background will start it headlessly); read-only commands like plugin list work against a stopped session, but install/link/unlink do not.

Configure copied files

Create .worktreeinclude at the project root. It uses .gitignore pattern syntax, but a file is copied only when it is both selected by .worktreeinclude and ignored by Git.

# .gitignore
.env
config/local/

# .worktreeinclude
.env
config/local/

Tracked files are never copied. Existing destination files are not overwritten. Symlinks and file modes are preserved.

Development

npm install
npm run check

After changing the manifest or scripts, relink the plugin in the target Herdr session:

herdr plugin unlink serhii-chernenko.worktreeinclude
herdr plugin link "$(pwd)"

Releases

The npm package and Herdr manifest share one version. Before publishing, update both package.json and herdr-plugin.toml, add release notes to CHANGELOG.md, then commit and push a matching tag:

git tag v0.1.1
git push origin main v0.1.1

The tag workflow verifies the version, publishes to npm through npm Trusted Publishing, and creates GitHub Release notes automatically. After claiming the package name with an initial manual publish, configure npm's Trusted Publisher for GitHub repository serhii-chernenko/herdr-worktreeinclude and workflow filename publish.yml. Subsequent matching version tags publish without a stored npm token.

Screenshots

License

MIT