vcspull worktree¶

The vcspull worktree command manages git worktrees declaratively from your vcspull configuration. Instead of manually running git worktree add for each branch or tag, you declare the desired worktrees in YAML and let vcspull create, update, and prune them.

Command¶

Usage¶

usage: vcspull worktree [-h] {list,sync,prune} ...

Choose a subcommand for details:

vcspull worktree list — show configured worktrees and their status
vcspull worktree sync — create or update worktrees
vcspull worktree prune — remove worktrees not in configuration

Configuration¶

Worktrees are configured as a list under a repository entry. Each worktree requires a dir (relative to workspace root or absolute) and exactly one ref type: tag, branch, or commit.

~/code/:
  myproject:
    url: "git+https://github.com/myorg/myproject.git"
    worktrees:
      # Pin a stable release (detached HEAD)
      - dir: "../myproject-v2.0"
        tag: "v2.0.0"
        lock: true
        lock_reason: "production reference"

      # Track a development branch (updatable)
      - dir: "../myproject-dev"
        branch: "develop"

      # Pin a specific commit (detached HEAD)
      - dir: "../myproject-bisect"
        commit: "abc1234"

Fields¶

Field	Required	Description
`dir`	yes	Worktree path (relative to workspace root or absolute)
`tag`	one of	Tag to checkout (creates detached HEAD)
`branch`	one of	Branch to checkout (can be updated/pulled)
`commit`	one of	Commit SHA to checkout (creates detached HEAD)
`lock`	no	Lock the worktree to prevent accidental removal
`lock_reason`	no	Reason for locking (implies `lock: true`)

Exactly one of tag, branch, or commit must be specified per entry.

Integration with vcspull sync¶

The vcspull sync command can sync worktrees alongside repositories using the --include-worktrees flag:

$ vcspull sync --include-worktrees '*'

Preview the combined operation:

$ vcspull sync --include-worktrees --dry-run '*'

This first syncs (clones/updates) the repository itself, then processes its configured worktrees.

JSON output¶

All subcommands support --json for structured output:

$ vcspull worktree list --json 'myproject'

Each worktree entry emits:

{
  "worktree_path": "~/code/myproject-v2.0",
  "ref_type": "tag",
  "ref_value": "v2.0.0",
  "action": "unchanged",
  "exists": true,
  "is_dirty": false,
  "detail": "tag worktree already exists",
  "error": null
}

NDJSON output¶

Stream events line-by-line with --ndjson:

$ vcspull worktree list --ndjson 'myproject'

Each line is a self-contained JSON object, suitable for piping to jq or log aggregation.

Safety¶

vcspull applies several safety checks before modifying worktrees:

Dirty worktrees are BLOCKED. If a worktree has uncommitted changes, vcspull will not update or remove it. Commit or stash your changes first.

Missing refs are ERROR. If a configured tag, branch, or commit doesn’t exist in the repository, the entry is marked as an error. Fetch from the remote to make the ref available.

Lock support. Worktrees created with lock: true or lock_reason are locked via git worktree lock, preventing accidental removal with git worktree remove.

Pattern filtering¶

Filter which repositories are processed using fnmatch-style patterns:

$ vcspull worktree list 'django*'

$ vcspull worktree sync 'myproject' 'another-repo'

Use '*' to match all repositories with worktrees configured.

Workspace filtering¶

Filter by workspace root directory:

$ vcspull worktree list --workspace ~/code/

Configuration file selection¶

Specify a custom config file:

$ vcspull worktree list --file ~/projects/.vcspull.yaml

Color output¶

Control colored output with --color:

--color auto (default): Use colors if outputting to a terminal
--color always: Always use colors
--color never: Never use colors

The NO_COLOR environment variable is also respected.

Use cases¶

LLM / agentic workflows¶

Clone a repository trunk and pin multiple release tags for reference:

~/code/:
  cpython:
    url: "git+https://github.com/python/cpython.git"
    worktrees:
      - dir: "../cpython-3.12"
        tag: "v3.12.0"
      - dir: "../cpython-3.13"
        tag: "v3.13.0"

This gives agents read-only snapshots of specific versions alongside the main checkout.

Parallel development across branches¶

Work on multiple feature branches without switching:

~/code/:
  webapp:
    url: "git+https://github.com/myorg/webapp.git"
    worktrees:
      - dir: "../webapp-feature-auth"
        branch: "feature/auth"
      - dir: "../webapp-feature-billing"
        branch: "feature/billing"

Maintaining versioned reference copies¶

Lock stable releases to prevent accidental modification:

~/code/:
  library:
    url: "git+https://github.com/myorg/library.git"
    worktrees:
      - dir: "../library-v1"
        tag: "v1.0.0"
        lock: true
        lock_reason: "legacy API reference"
      - dir: "../library-v2"
        tag: "v2.0.0"
        lock: true
        lock_reason: "current stable reference"