# Worktree Tending

> Manage git worktrees for parallel branch development using custom git scripts (git-newtree, git-killtree, git-maingulp). Use when creating new worktrees, listing active worktrees, or closing/merging worktrees back to main. All worktrees are stored in .tree/ subdirectories of the repository.

- Skill: `majiayu000/worktree-tending` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/worktree-tending`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/worktree-tending/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/worktree-tending

---


# Worktree Tending

## Overview

This skill helps manage git worktrees using a customized workflow with scripts stored in `~/bin/`. Worktrees enable working on multiple branches simultaneously by creating separate working directories that share the same git repository. All worktrees are stored in `.tree/` subdirectories.

## Core Workflow

The typical worktree lifecycle:

1. **Create** a new worktree for a branch using `git newtree`
2. **Work** in that worktree (user navigates manually)
3. **Close** the worktree when done, optionally merging back to main

## Available Operations

### Creating a New Worktree

To create a new worktree for a branch:

```bash
git newtree <tree-name> [branch-name]
```

**Behavior:**
- Creates worktree at `.tree/<tree-name>`
- If branch exists, checks it out; otherwise creates new branch
- Branch name defaults to tree-name if not specified
- Copies `.env` and `.envrc` files to the new worktree if present
- Reports the path for manual navigation

**Examples:**
```bash
git newtree feature-x              # Creates .tree/feature-x with branch 'feature-x'
git newtree fix check/lint-graphql # Creates .tree/fix with existing branch 'check/lint-graphql'
```

**When to use:** User asks to create a new worktree, start work on a new branch, or work on a branch in parallel.

### Listing Active Worktrees

To show all active worktrees with status:

```bash
git worktree list
```

**Output format:**
```
/path/to/repo                      commit-hash (detached HEAD)
/path/to/repo/.tree/feature-x      commit-hash [feature-x]
/path/to/repo/.tree/maincomp       commit-hash [main]
```

**Interactive selection with fzf:** When closing or switching worktrees, use fzf for interactive selection of worktrees from the list.

**When to use:** User asks to see active worktrees, list branches being worked on, or needs to select a worktree to close.

### Closing a Worktree

When closing a worktree, **always ask the user** whether to merge back to main or just remove the worktree.

#### Option 1: Merge to Main and Cleanup

Use `git maingulp` to merge changes back to main and cleanup:

```bash
cd .tree/maincomp  # or wherever main branch worktree is
git maingulp <branch-name> <worktree-path>
```

**Requirements:**
- Must be run from the main branch worktree
- Performs fast-forward merge (rebases main onto branch)
- Pushes main to remote
- Removes worktree and deletes branch

**Example:**
```bash
cd .tree/maincomp
git maingulp feature-x .tree/feature-x
```

**When to use:** Work is complete and ready to be merged into main.

#### Option 2: Just Remove Worktree

Use `git killtree` to remove worktree without merging:

```bash
git killtree <worktree-path> [--force]
```

**Behavior:**
- Removes worktree at specified path
- Deletes branch only if fully merged (unless --force)
- Use --force to remove dirty worktree and force-delete unmerged branch

**Examples:**
```bash
git killtree .tree/feature-x          # Remove worktree, delete if merged
git killtree .tree/experiment --force # Force remove unmerged work
```

**When to use:** Work is abandoned, experimental, or will be merged manually later.

### Interactive Worktree Selection

When the user asks to close a worktree without specifying which one, use fzf for interactive selection:

```bash
# First list worktrees
git worktree list

# Parse the output and use fzf to let user select
# Then confirm merge vs. remove decision
```

**Example interaction:**
1. User: "Close a worktree"
2. Show `git worktree list` output
3. Use fzf or present choices for selection
4. Ask: "Merge to main or just remove?"
5. Execute appropriate command

## References

See `references/git-scripts-reference.md` for detailed documentation of all git scripts including `git-archivebranch` and `git-substat`.

## Working Directory Conventions

- **Main repo:** Usually has detached HEAD
- **Worktrees:** Located in `.tree/` subdirectory
- **Main branch:** Typically lives in `.tree/maincomp` or similar
- **Feature branches:** Each in its own `.tree/<name>` directory

## Common Patterns

**Starting new feature work:**
```bash
git newtree my-feature
cd .tree/my-feature
# work on feature
```

**Completing and merging feature:**
```bash
cd .tree/maincomp
git maingulp my-feature .tree/my-feature
```

**Abandoning experimental work:**
```bash
git killtree .tree/experiment --force
```