@lsst/pik-plugin-worktree

Git worktree management plugin for pik - easily create, list, and remove git worktrees.

Installation

This plugin is included with @lsst/pik by default.

npm install -g @lsst/pik

Usage

# Interactive create (default)
pik worktree

# Create with specific name
pik worktree create my-feature

# Create new branch
pik worktree create my-feature -n -b feature/new-thing

# List all worktrees
pik worktree list

# Remove a worktree
pik worktree remove

Configuration

Add to your pik.config.ts:

import { defineConfig } from '@lsst/pik';

export default defineConfig({
  worktree: {
    // Directory where worktrees are created (relative to repo root)
    baseDir: '../',

    // Files to copy to new worktrees
    copyFiles: ['.env.local', '.env.development'],

    // Files/dirs to symlink into new worktrees instead of copying.
    // Useful for large, regenerable directories (caches, deps) that can be
    // shared with the main repo to save disk space.
    linkFiles: ['node_modules', '.angular/cache'],

    // Command to run after creating worktree
    postCreate: 'npm install',
  },
});

copyFiles vs linkFiles

• copyFiles makes an independent copy in the worktree — safe to diverge from the main repo. Use it for things like .env files.
• linkFiles creates a symlink pointing back at the absolute path of the source in the main repo. This saves disk for large, regenerable directories (build caches, node_modules, .angular/cache).

⚠️ A symlinked path is shared with the main repo — writes from one worktree affect the other. That's the intended win for regenerable caches, but it is shared mutable state, not an isolated copy. Only link things that are safe to share (caches, deps); never link source or env files you intend to diverge per worktree.

If a path appears in both lists, copyFiles wins: files are copied first, and linkFiles skips any destination that already exists.

Commands

| Command | Alias | Description | |---------|-------|-------------| | pik worktree | wt | Interactive worktree creation | | pik worktree create [name] | add | Create a new worktree | | pik worktree list | ls | List all worktrees | | pik worktree remove [path] | rm | Remove a worktree |

Create Options

| Option | Description | |--------|-------------| | -b, --branch <branch> | Branch to checkout or create | | -n, --new | Create a new branch |

Remove Options

| Option | Description | |--------|-------------| | -f, --force | Force removal even if dirty | | -D, --delete-branch | Also delete the branch |

License

MIT