OpenParable
Skip to content
← Back to skills

Nv Worktree Commands

Development
nv-worktree-commands

Nv Worktree Commands is an Agent Skill for development published in the novuhq/novu repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Git worktree command reference: path naming, create/remove/prune, `.env*` copy, package-manager install, and cleanup. Use when implementing or debugging worktree setup — not as the primary user-facing workflow (see nv-worktree-create).

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/novuhq/novu/blob/HEAD/.cursor/skills/nv-worktree-commands/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/nv-worktree-commands, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Git worktree commands

Reference for agents implementing worktree workflows. Prefer nv-worktree-create for the end-to-end flow.

Path naming

REPO_ROOT  = $(git rev-parse --show-toplevel)
REPO_PARENT = $(dirname "$REPO_ROOT")
BRANCH     = user-provided name (used as git branch)
DIR_NAME   = sanitize(BRANCH)   # lowercase; `/` → `-`
WORKTREE   = "$REPO_PARENT/$DIR_NAME"

Examples (repo at /Users/me/work/novu):

BranchWorktree path
more-dcr-oauths/Users/me/work/more-dcr-oauths
nv-1234/foo-bar/Users/me/work/nv-1234-foo-bar

Abort if WORKTREE already exists on disk or in git worktree list.

Create (new branch)

From current HEAD:

git worktree add -b <branch> <worktree-path>

From a specific base:

git worktree add -b <branch> <worktree-path> <base-ref>

<base-ref>: HEAD, main, origin/main, a tag, or a commit SHA.

Inspect

git worktree list
git -C <worktree-path> status -sb
git -C <worktree-path> rev-parse HEAD

Copy local env files

git worktree add does not bring gitignored files. Copy local secret env files only from the main checkout — not .env.example / .env.template (those are already in git).

Preferred — rsync with explicit includes (from main repo root):

rsync -a \
  --prune-empty-dirs \
  --include='*/' \
  --include='.env' \
  --include='.env.*' \
  --exclude='.env.example' \
  --exclude='.env.template' \
  --exclude='*' \
  --exclude='node_modules/' \
  --exclude='dist/' \
  --exclude='build/' \
  --exclude='.next/' \
  --exclude='.turbo/' \
  "<main-repo-root>/" "<worktree-path>/"

Alternative — copy only gitignored env files (when rsync is unavailable):

cd <main-repo-root>
git ls-files -z --others --ignored --exclude-standard \
| while IFS= read -r -d '' f; do
    base="$(basename "$f")"
    case "$base" in
      .env|.env.*)
        case "$base" in
          .env.example|.env.template) continue ;;
        esac
        mkdir -p "<worktree-path>/$(dirname "$f")"
        cp -a "$f" "<worktree-path>/$f"
        ;;
    esac
  done

After copying, list what landed (e.g. find <worktree-path> -type f \( -name '.env' -o -name '.env.*' \) ! -name '.env.example' ! -name '.env.template').

Novu-specific

  • Copy from the parent checkout, not node scripts/setup-env-files.js. That script generates a new STORE_ENCRYPTION_KEY when .env is missing — a worktree would then disagree with the parent and shared local Mongo/Redis.
  • Typical files copied: apps/api/src/.env, .env.agent, .env.development, apps/dashboard/.env, apps/worker/src/.env, apps/ws/src/.env, etc.
  • Skip playground/ env unless the task needs it.

Install dependencies

LockfileCommand
pnpm-lock.yamlpnpm install
yarn.lockyarn install
package-lock.jsonnpm install
bun.lockbbun install

Run from the worktree root.

Build

pnpm build   # or npm/yarn/bun equivalent

Skip if no build script exists.

Remove

git worktree remove <worktree-path>
git worktree prune

Remove uncommitted work in the worktree first, or use --force only when the user explicitly asks.

For auditing merged/stale worktrees and batch cleanup, read nv-worktree-cleanup.

Anti-patterns

  • git worktree add --detach when the goal is a named feature branch — use -b.
  • cp -r the entire repo instead of git worktree add.
  • Reusing ~/.cursor/worktrees/… detached paths when a sibling ../<name> worktree is enough.
  • Running full setup scripts (pnpm setup:agent) in Cursor Cloud child worktrees when the parent already ran them.