daft-worktree-workflow

Category: Tools & Productivity | Uploader: avihut | Downloads: 0 | Version: v1.0（Latest）

Guides the daft worktree workflow for compartmentalized Git development. Use when working in daft-managed repositories (repos with a .git/ bare directory and branch worktrees as sibling directories), when setting up worktree environment isolation, or when users ask about worktree-based workflows. Covers daft commands, hooks automation via daft.yml, and environment tooling like mise, direnv, nvm, and pyenv. --- # daft Worktree Workflow ## Core Philosophy daft treats each Git worktree as a **compartmentalized workspace**, not just a branch checked out to disk. Each worktree is a fully isolated environment with

Changelog: Source: GitHub https://github.com/avihut/daft

Directory Structure

Current level: Root

📁 .claude/
- 📁 agents/
  - 📄 code-reviewer.md 7.0 KB
  - 📄 rust-architect.md 9.3 KB
📁 .github/
- 📁 workflows/
  - 📄 bench.yml 1.7 KB
  - 📄 docs.yml 846 B
  - 📄 release-plz.yml 4.3 KB
  - 📄 release.yml 28.4 KB
  - 📄 test-homebrew.yml 5.2 KB
  - 📄 test.yml 14.0 KB
- 📄 dependabot.yml 1.8 KB
📁 benches/
- 📁 fixtures/
  - 📄 create_repo.sh 2.8 KB
  - 📄 real_repos.sh 1.1 KB
- 📁 scenarios/
  - 📄 branch_delete.sh 1.0 KB
  - 📄 checkout.sh 2.6 KB
  - 📄 checkout_with_hooks.sh 3.0 KB
  - 📄 clone.sh 838 B
  - 📄 clone_with_hooks.sh 1.3 KB
  - 📄 fetch.sh 1.1 KB
  - 📄 init.sh 615 B
  - 📄 prune.sh 1.6 KB
  - 📄 vs_competition.sh 2.9 KB
  - 📄 workflow_full.sh 2.7 KB
- 📄 bench_framework.sh 4.4 KB
- 📄 package_results.sh 1.7 KB
- 📄 run_all.sh 3.4 KB
📁 docs/
- 📁 .vitepress/
  - 📁 theme/
    
    📄 changelog.css 91 B
    
    📄 home.css 50 B
    
    📄 index.ts 121 B
  - 📄 config.ts 12.4 KB
- 📁 cli/
  - 📄 daft-adopt.md 1022 B
  - 📄 daft-carry.md 705 B
  - 📄 daft-clone.md 842 B
  - 📄 daft-completions.md 2.7 KB
  - 📄 daft-doctor.md 1.7 KB
  - 📄 daft-eject.md 795 B
  - 📄 daft-go.md 2.7 KB
  - 📄 daft-init.md 796 B
  - 📄 daft-list.md 1.7 KB
  - 📄 daft-multi-remote.md 5.3 KB
  - 📄 daft-prune.md 589 B
  - 📄 daft-release-notes.md 1.2 KB
  - 📄 daft-remove.md 850 B
  - 📄 daft-rename.md 2.0 KB
  - 📄 daft-setup.md 4.3 KB
  - 📄 daft-shell-init.md 2.4 KB
  - 📄 daft-start.md 994 B
  - 📄 daft-sync.md 3.1 KB
  - 📄 daft-update.md 2.5 KB
  - 📄 git-daft-hooks.md 7.8 KB
  - 📄 git-sync.md 2.3 KB
  - 📄 git-worktree-branch-delete.md 2.3 KB
  - 📄 git-worktree-branch.md 3.4 KB
  - 📄 git-worktree-carry.md 1.7 KB
  - 📄 git-worktree-checkout.md 3.2 KB
  - 📄 git-worktree-clone.md 2.4 KB
  - 📄 git-worktree-fetch.md 2.2 KB
  - 📄 git-worktree-flow-adopt.md 3.2 KB
  - 📄 git-worktree-flow-eject.md 2.4 KB
  - 📄 git-worktree-init.md 2.2 KB
  - 📄 git-worktree-list.md 2.4 KB
  - 📄 git-worktree-prune.md 2.2 KB
- 📁 getting-started/
  - 📄 installation.md 4.2 KB
  - 📄 quick-start.md 3.1 KB
  - 📄 shell-integration.md 2.1 KB
- 📁 guide/
  - 📄 adopting-existing-repos.md 2.4 KB
  - 📄 claude-skill.md 4.4 KB
  - 📄 configuration.md 8.8 KB
  - 📄 hooks.md 25.9 KB
  - 📄 multi-remote.md 1.8 KB
  - 📄 shortcuts.md 3.8 KB
  - 📄 worktree-workflow.md 4.7 KB
- 📁 public/
  - 📄 og-image.png 4.4 KB
  - 📄 robots.txt 68 B
- 📄 biome.json 416 B
- 📄 bun.lock 43.9 KB
- 📄 changelog.md 495 B
- 📄 contributing.md 3.2 KB
- 📄 HISTORY.md 5.5 KB
- 📄 index.md 3.3 KB
- 📄 package.json 152 B
📁 man/
- 📄 daft-adopt.1 3.0 KB
- 📄 daft-carry.1 1.4 KB
- 📄 daft-clone.1 2.3 KB
- 📄 daft-doctor.1 1.6 KB
- 📄 daft-eject.1 2.2 KB
- 📄 daft-go.1 2.8 KB
- 📄 daft-init.1 2.0 KB
- 📄 daft-list.1 2.5 KB
- 📄 daft-prune.1 2.1 KB
- 📄 daft-release-notes.1 1.3 KB
- 📄 daft-remove.1 2.1 KB
- 📄 daft-rename.1 1.4 KB
- 📄 daft-start.1 1.9 KB
- 📄 daft-sync.1 2.5 KB
- 📄 daft-update.1 2.1 KB
- 📄 git-sync.1 2.5 KB
- 📄 git-worktree-branch-delete.1 2.0 KB
- 📄 git-worktree-branch.1 3.2 KB
- 📄 git-worktree-carry.1 1.4 KB
- 📄 git-worktree-checkout.1 3.2 KB
- 📄 git-worktree-clone.1 2.4 KB
- 📄 git-worktree-fetch.1 2.1 KB
- 📄 git-worktree-flow-adopt.1 3.1 KB
- 📄 git-worktree-flow-eject.1 2.3 KB
- 📄 git-worktree-init.1 2.0 KB
- 📄 git-worktree-list.1 2.5 KB
- 📄 git-worktree-prune.1 2.1 KB
📁 mise-tasks/
- 📁 bench/
  - 📄 _default 244 B
  - 📄 baseline 389 B
  - 📄 branch-delete 258 B
  - 📄 checkout 248 B
  - 📄 checkout-hooks 270 B
  - 📄 clone 242 B
  - 📄 clone-hooks 264 B
  - 📄 compare 531 B
  - 📄 competition 277 B
  - 📄 fetch 242 B
  - 📄 init 240 B
  - 📄 prune 242 B
  - 📄 workflow 258 B
- 📁 clean/
  - 📄 _default 168 B
  - 📄 rust 138 B
  - 📄 tests 193 B
- 📁 completions/
  - 📁 gen/
    
    📄 bash 432 B
    
    📄 fish 432 B
    
    📄 zsh 428 B
  - 📄 install 444 B
  - 📄 test 294 B
- 📁 dev/
  - 📄 _default 192 B
  - 📄 clean 618 B
  - 📄 setup 139 B
  - 📄 test 178 B
  - 📄 verify 522 B
- 📁 docs/
  - 📁 cli/
    
    📄 gen 324 B
    
    📄 verify 397 B
  - 📁 site/
    
    📄 _default 169 B
    
    📄 build 151 B
    
    📄 check 166 B
    
    📄 format 179 B
    
    📄 preview 161 B
    
    📄 setup 119 B
- 📁 fmt/
  - 📁 docs/
    
    📄 _default 153 B
    
    📄 check 143 B
  - 📄 _default 162 B
  - 📄 check 178 B
- 📁 lint/
  - 📄 _default 154 B
  - 📄 rust 353 B
- 📁 man/
  - 📄 gen 241 B
  - 📄 install 392 B
  - 📄 verify 340 B
- 📁 sandbox/
  - 📄 _default 2.0 KB
  - 📄 _lib.sh 538 B
  - 📄 clean 445 B
  - 📄 setup 1.8 KB
- 📁 setup/
  - 📄 _default 222 B
  - 📄 rust 1.6 KB
- 📁 test/
  - 📁 integration/
    
    📁 checkout/
    
    📄 _default 202 B
    
    📄 branch 223 B
    
    📁 flow/
    
    📄 adopt 208 B
    
    📄 eject 208 B
    
    📁 shell/
    
    📄 init 208 B
    
    📁 unknown/
    
    📄 command 223 B
    
    📄 _default 164 B
    
    📄 clone 193 B
    
    📄 config 196 B
    
    📄 exec 190 B
    
    📄 fetch 193 B
    
    📄 gitoxide 189 B
    
    📄 hooks 193 B
    
    📄 init 190 B
    
    📄 matrix 260 B
    
    📄 prune 193 B
    
    📄 setup 193 B
    
    📄 verbose 245 B
  - 📄 _default 198 B
  - 📄 unit 138 B
  - 📄 verbose 167 B
  - 📄 version-format 3.2 KB
- 📁 validate/
  - 📄 _default 141 B
  - 📄 rust 380 B
- 📁 watch/
  - 📄 _default 146 B
  - 📄 check 269 B
  - 📄 clippy 311 B
  - 📄 unit 275 B
- 📄 build 165 B
- 📄 ci 165 B
- 📄 clippy 134 B
📁 packaging/
- 📁 aur/
  - 📄 PKGBUILD 1.9 KB
- 📁 deb/
  - 📄 postinst 506 B
  - 📄 prerm 517 B
📁 src/
- 📁 commands/
  - 📁 completions/
    
    📄 bash.rs 9.3 KB
    
    📄 fig.rs 17.9 KB
    
    📄 fish.rs 10.8 KB
    
    📄 mod.rs 17.1 KB
    
    📄 zsh.rs 9.1 KB
  - 📁 hooks/
    
    📄 dump.rs 1.9 KB
    
    📄 formatting.rs 4.0 KB
    
    📄 install.rs 3.8 KB
    
    📄 migrate.rs 4.2 KB
    
    📄 mod.rs 18.0 KB
    
    📄 run_cmd.rs 9.0 KB
    
    📄 status.rs 12.4 KB
    
    📄 trust.rs 13.2 KB
    
    📄 validate.rs 1.5 KB
  - 📄 branch_delete.rs 5.1 KB
  - 📄 carry.rs 4.7 KB
  - 📄 checkout.rs 19.9 KB
  - 📄 clone.rs 9.8 KB
  - 📄 complete.rs 10.4 KB
  - 📄 docs.rs 6.3 KB
  - 📄 doctor.rs 12.7 KB
  - 📄 fetch.rs 10.6 KB
  - 📄 flow_adopt.rs 6.6 KB
  - 📄 flow_eject.rs 4.3 KB
  - 📄 init.rs 10.3 KB
  - 📄 list.rs 17.9 KB
  - 📄 mod.rs 593 B
  - 📄 multi_remote.rs 21.5 KB
  - 📄 prune.rs 13.7 KB
  - 📄 release_notes.rs 13.5 KB
  - 📄 setup.rs 7.1 KB
  - 📄 shell_init.rs 16.5 KB
  - 📄 shortcuts.rs 14.3 KB
  - 📄 sync.rs 41.1 KB
  - 📄 sync_shared.rs 9.2 KB
  - 📄 worktree_branch.rs 15.0 KB
- 📁 core/
  - 📁 multi_remote/
    
    📄 config.rs 1.7 KB
    
    📄 migration.rs 11.9 KB
    
    📄 mod.rs 947 B
    
    📄 path.rs 5.3 KB
  - 📁 worktree/
    
    📄 branch_delete.rs 38.9 KB
    
    📄 carry.rs 6.9 KB
    
    📄 checkout.rs 15.2 KB
    
    📄 checkout_branch.rs 13.3 KB
    
    📄 clone.rs 14.6 KB
    
    📄 fetch.rs 21.7 KB
    
    📄 flow_adopt.rs 10.3 KB
    
    📄 flow_eject.rs 18.0 KB
    
    📄 init.rs 5.6 KB
    
    📄 list.rs 31.6 KB
    
    📄 mod.rs 861 B
    
    📄 previous.rs 3.8 KB
    
    📄 prune.rs 29.0 KB
    
    📄 push.rs 5.6 KB
    
    📄 rebase.rs 6.4 KB
    
    📄 rename.rs 14.1 KB
    
    📄 sync_dag.rs 36.5 KB
  - 📄 config.rs 1.5 KB
  - 📄 mod.rs 4.2 KB
  - 📄 progress.rs 3.2 KB
  - 📄 remote.rs 7.7 KB
  - 📄 repo.rs 6.4 KB
  - 📄 settings.rs 27.8 KB
  - 📄 tui_bridge.rs 6.5 KB
- 📁 doctor/
  - 📄 hooks_checks.rs 17.7 KB
  - 📄 installation.rs 26.0 KB
  - 📄 mod.rs 9.9 KB
  - 📄 repository.rs 13.1 KB
- 📁 executor/
  - 📄 cli_presenter.rs 8.7 KB
  - 📄 command.rs 13.5 KB
  - 📄 dag.rs 31.5 KB
  - 📄 mod.rs 9.2 KB
  - 📄 presenter.rs 5.4 KB
  - 📄 runner.rs 37.9 KB
- 📁 git/
  - 📄 branch.rs 2.3 KB
  - 📄 clone.rs 1.6 KB
  - 📄 config.rs 3.6 KB
  - 📄 mod.rs 2.6 KB
  - 📄 oxide.rs 36.6 KB
  - 📄 refs.rs 8.5 KB
  - 📄 remote.rs 14.0 KB
  - 📄 stash.rs 4.2 KB
  - 📄 worktree.rs 7.3 KB
- 📁 hooks/
  - 📁 yaml_executor/
    
    📄 mod.rs 28.8 KB
  - 📄 conditions.rs 17.6 KB
  - 📄 environment.rs 10.8 KB
  - 📄 executor.rs 26.5 KB
  - 📄 job_adapter.rs 14.7 KB
  - 📄 mod.rs 32.7 KB
  - 📄 template.rs 3.6 KB
  - 📄 trust.rs 31.5 KB
  - 📄 trust_dto.rs 8.9 KB
  - 📄 yaml_config.rs 25.5 KB
  - 📄 yaml_config_loader.rs 20.5 KB
  - 📄 yaml_config_validate.rs 25.1 KB
- 📁 output/
  - 📁 hook_progress/
    
    📄 formatting.rs 5.6 KB
    
    📄 interactive.rs 12.5 KB
    
    📄 mod.rs 14.4 KB
    
    📄 plain.rs 3.0 KB
  - 📁 tui/
    
    📄 columns.rs 6.4 KB
    
    📄 driver.rs 6.2 KB
    
    📄 mod.rs 451 B
    
    📄 presenter.rs 16.0 KB
    
    📄 render.rs 23.9 KB
    
    📄 state.rs 41.0 KB
  - 📄 buffering.rs 3.3 KB
  - 📄 cli.rs 9.2 KB
  - 📄 format.rs 10.2 KB
  - 📄 mod.rs 7.9 KB
  - 📄 test.rs 15.9 KB
- 📄 exec.rs 797 B
- 📄 hints.rs 6.0 KB
- 📄 homebrew.rs 3.6 KB
- 📄 lib.rs 5.5 KB
- 📄 logging.rs 1.5 KB
- 📄 main.rs 7.1 KB
- 📄 shortcuts.rs 9.2 KB
- 📄 styles.rs 3.7 KB
- 📄 suggest.rs 7.5 KB
- 📄 trust_prune.rs 8.3 KB
- 📄 update_check.rs 23.7 KB
- 📄 utils.rs 7.3 KB
📁 tests/
- 📁 integration/
  - 📄 test_all.sh 11.6 KB
  - 📄 test_branch_delete.sh 26.4 KB
  - 📄 test_checkout.sh 29.4 KB
  - 📄 test_checkout_branch.sh 22.9 KB
  - 📄 test_clone.sh 13.5 KB
  - 📄 test_completions.sh 18.0 KB
  - 📄 test_config.sh 11.3 KB
  - 📄 test_exec.sh 6.4 KB
  - 📄 test_fetch.sh 26.0 KB
  - 📄 test_flow_adopt.sh 9.7 KB
  - 📄 test_flow_eject.sh 10.2 KB
  - 📄 test_framework.sh 11.5 KB
  - 📄 test_hooks.sh 18.2 KB
  - 📄 test_init.sh 8.4 KB
  - 📄 test_list.sh 35.2 KB
  - 📄 test_prune.sh 35.4 KB
  - 📄 test_rename.sh 12.7 KB
  - 📄 test_setup.sh 6.5 KB
  - 📄 test_shell_init.sh 13.2 KB
  - 📄 test_simple.sh 2.6 KB
  - 📄 test_sync.sh 15.4 KB
  - 📄 test_unknown_command.sh 3.7 KB
- 📄 README.md 4.5 KB
- 📄 test_all.sh 7.2 KB
- 📄 test_checkout.sh 10.4 KB
- 📄 test_checkout_branch.sh 11.2 KB
- 📄 test_clone.sh 7.1 KB
- 📄 test_concurrency.rs 7.5 KB
- 📄 test_framework.sh 7.4 KB
- 📄 test_init.sh 8.8 KB
- 📄 test_prune.sh 11.7 KB
- 📄 test_security.rs 12.5 KB
- 📄 test_simple.sh 4.8 KB
📁 wix/
- 📄 main.wxs 10.0 KB
📁 xtask/
- 📁 src/
  - 📄 main.rs 31.7 KB
- 📄 Cargo.toml 220 B
📄 .gitignore 587 B
📄 .prettierignore 104 B
📄 .prettierrc 85 B
📄 build.rs 2.0 KB
📄 bun.lock 361 B
📄 Cargo.toml 3.8 KB
📄 CHANGELOG.md 18.1 KB
📄 CLAUDE.md 6.7 KB
📄 cliff.toml 1.9 KB
📄 CODE_OF_CONDUCT.md 743 B
📄 cog.toml 59 B
📄 CONTRIBUTING.md 3.3 KB
📄 daft.yml 1.4 KB
📄 demo.tape 794 B
📄 dist-workspace.toml 1.8 KB
📄 flake.lock 1.9 KB
📄 flake.nix 3.1 KB
📄 HOMEBREW.md 12.2 KB
📄 lefthook.yml 781 B
📄 LICENSE 1.0 KB
📄 mise.lock 8.0 KB
📄 mise.toml 975 B
📄 package.json 74 B
📄 README.md 7.8 KB
📄 release-plz.toml 1.7 KB
📄 RELEASING.md 11.7 KB
📄 SECURITY.md 912 B
📄 SETUP_RELEASE.md 11.8 KB
📄 SKILL.md 30.6 KB

SKILL.md

---
name: daft-worktree-workflow
description:
  Guides the daft worktree workflow for compartmentalized Git development. Use
  when working in daft-managed repositories (repos with a .git/ bare directory
  and branch worktrees as sibling directories), when setting up worktree
  environment isolation, or when users ask about worktree-based workflows.
  Covers daft commands, hooks automation via daft.yml, and environment tooling
  like mise, direnv, nvm, and pyenv.
---

# daft Worktree Workflow

## Core Philosophy

daft treats each Git worktree as a **compartmentalized workspace**, not just a
branch checked out to disk. Each worktree is a fully isolated environment with
its own:

- Working files and Git index
- Build artifacts (`node_modules/`, `target/`, `venv/`, `.build/`)
- IDE state and configuration (`.vscode/`, `.idea/`)
- Environment files (`.envrc`, `.env`)
- Running processes (dev servers, watchers, test runners)
- Installed dependencies (potentially different versions per branch)

This means creating a new worktree is not just "checking out a branch" -- it is
spinning up a new development environment. Automation (via `daft.yml` hooks)
should install dependencies, configure environment tools, and prepare the
workspace so the developer can start working immediately.

Never use `git checkout` or `git switch` to change branches in a daft-managed
repo. Navigate between worktree directories instead.

## Detecting a daft-managed Repository

A daft-managed repository has this layout:

```
my-project/
+-- .git/                    # Bare repository (shared Git metadata)
+-- main/                    # Worktree for the default branch
|   +-- src/
|   +-- package.json
+-- feature/auth/            # Worktree for a feature branch
|   +-- src/
|   +-- package.json
+-- bugfix/login/            # Worktree for a bugfix branch
```

Key indicators:

- `.git/` at the project root is a **bare repository** (directory, not a file)
- Branch worktrees are **sibling directories** to `.git/`
- Use `git rev-parse --git-common-dir` from any worktree to find the project
  root

If you see this layout, the user is using daft. Apply worktree-aware guidance
throughout the session.

## Invocation Forms

daft commands can be invoked in three ways:

| Form           | Example                               | Requires                                |
| -------------- | ------------------------------------- | --------------------------------------- |
| Git subcommand | `git worktree-checkout feature/auth`  | `git-worktree-checkout` symlink on PATH |
| Direct binary  | `daft worktree-checkout feature/auth` | Only the `daft` binary                  |
| Verb alias     | `daft go feature/auth`                | Only the `daft` binary                  |
| Shortcut alias | `gwtco feature/auth`                  | Shortcut symlink on PATH                |

The git subcommand form (`git worktree-*`) is what users type in their terminals
and what documentation references. Shortcuts are optional short aliases managed
via `daft setup shortcuts`.

### Verb Aliases

daft provides short verb aliases for common commands:

| Verb Alias    | Equivalent Command          |
| ------------- | --------------------------- |
| `daft go`     | `daft worktree-checkout`    |
| `daft start`  | `daft worktree-checkout -b` |
| `daft clone`  | `daft worktree-clone`       |
| `daft init`   | `daft worktree-init`        |
| `daft carry`  | `daft worktree-carry`       |
| `daft list`   | `daft worktree-list`        |
| `daft update` | `daft worktree-fetch`       |
| `daft prune`  | `daft worktree-prune`       |
| `daft remove` | `daft worktree-branch -d`   |
| `daft rename` | `daft worktree-branch -m`   |
| `daft sync`   | `daft git-sync`             |
| `daft adopt`  | `daft worktree-flow-adopt`  |
| `daft eject`  | `daft worktree-flow-eject`  |

**Agent execution rule**: When running daft commands, always use the direct
binary form (`daft <subcommand>`) or verb aliases. The git subcommand form
requires symlinks and shell wrappers that are not available in most agent shell
sandboxes. When explaining daft usage to users, reference the git subcommand
form (`git worktree-*`), verb aliases, or shortcuts, as these are what users
interact with in their configured terminals.

After creating a worktree with `daft`, the shell does not automatically `cd`
into it (that requires shell wrappers). Navigate to the new worktree using the
layout convention: `cd ../<branch-name>/` relative to any existing worktree.

## Command Reference

All commands below use the `daft` binary form for agent execution. Users know
these as `git` subcommands (e.g., `daft worktree-checkout` is
`git worktree-checkout` to the user).

### Worktree Lifecycle

| Command                                                                                                              | Description                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `daft worktree-clone <url>`                                                                                          | Clone a remote repository into daft's worktree layout                                                                                                                      |
| `daft worktree-init <name>`                                                                                          | Initialize a new local repository in worktree layout                                                                                                                       |
| `daft worktree-checkout <branch>`                                                                                    | Create a worktree for an existing local or remote branch                                                                                                                   |
| `daft worktree-checkout -- -`                                                                                        | Switch to the previous worktree (`cd -` style toggle)                                                                                                                      |
| `daft worktree-checkout -s <branch>`                                                                                 | Same as above, but auto-creates branch if not found (also `daft.go.autoStart`)                                                                                             |
| `daft worktree-checkout -b <new-branch> [base]`                                                                      | Create a new branch and worktree from current or specified base                                                                                                            |
| `daft worktree-branch -d <branch>`                                                                                   | Safely delete a branch: its worktree, local branch, and remote tracking branch                                                                                             |
| `daft worktree-branch -D <branch>`                                                                                   | Force-delete a branch bypassing safety checks; for the default branch, removes worktree only (preserves branch ref and remote)                                             |
| `daft worktree-prune [-f] [-v\|-vv] [--stat summary\|lines]`                                                         | Remove worktrees whose remote branches have been deleted (`-v` hook details, `-vv` full sequential)                                                                        |
| `daft worktree-carry <targets>`                                                                                      | Transfer uncommitted changes to one or more other worktrees                                                                                                                |
| `daft worktree-fetch [targets]`                                                                                      | Update worktree branches from remote (supports refspec syntax source:destination)                                                                                          |
| `daft worktree-branch -m <source> <new-branch>`                                                                      | Rename a branch, move its worktree, and rename the remote branch                                                                                                           |
| `daft git-sync [-f] [-v\|-vv] [--rebase BRANCH [--autostash]] [--push [--force-with-lease]] [--stat summary\|lines]` | Synchronize all worktrees: prune stale + update all + optional rebase + optional push (`-f`/`--prune-dirty` for dirty worktrees, `-v` hook details, `-vv` full sequential) |

### Adoption and Ejection

| Command                           | Description                                                |
| --------------------------------- | ---------------------------------------------------------- |
| `daft worktree-flow-adopt [path]` | Convert a traditional repository to daft's worktree layout |
| `daft worktree-flow-eject`        | Convert back to a traditional repository layout            |

### Management

| Command                             | Description                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `daft worktree-list [--json]`       | List all worktrees with branch (`◉` = default), path (relative to cwd), base ahead/behind, file status (+N staged, -N unstaged, ?N untracked), remote status (⇡N unpushed, ⇣N unpulled), branch age, and commit info. JSON includes `is_default_branch`, `staged`, `unstaged`, `untracked`, `remote_ahead`, `remote_behind`, `branch_age` fields. |
| `daft hooks <subcommand>`           | Manage hooks trust and configuration (`trust`, `prompt`, `deny`, `status`, `run`, `install`, `validate`, `dump`, `migrate`)                                                                                                                                                                                                                       |
| `daft doctor`                       | Diagnose installation and configuration issues; `--fix` auto-repairs symlinks, shortcuts, refspecs, hooks; `--fix --dry-run` previews fixes                                                                                                                                                                                                       |
| `daft setup shortcuts <subcommand>` | Manage command shortcut symlinks                                                                                                                                                                                                                                                                                                                  |
| `daft shell-init <shell>`           | Generate shell integration wrappers                                                                                                                                                                                                                                                                                                               |
| `daft completions <shell>`          | Generate shell tab completions                                                                                                                                                                                                                                                                                                                    |

All worktree commands can be run from **any directory** within any worktree.
They find the project root automatically via `git rev-parse --git-common-dir`.

### Post-setup Command Execution (`-x`/`--exec`)

The `clone`, `init`, and `checkout` commands support `-x`/`--exec` to run
commands in the new worktree immediately after setup:

```bash
daft worktree-clone https://github.com/org/repo -x 'mise install' -x 'npm run dev'
daft worktree-checkout -b my-feature -x claude
daft worktree-init my-project -x 'echo "ready"'
```

The option is repeatable -- commands run sequentially in the worktree directory,
after hooks complete. Execution stops on first failure. Interactive programs
(claude, vim) work because stdio is fully inherited.

## Shell Integration

Shell integration is important because the daft binary creates worktrees
internally, but the parent shell stays in the original directory. Shell wrappers
solve this by reading the CD target from a temp file (`DAFT_CD_FILE`) and
running `cd` in the parent shell.

```bash
# Bash / Zsh -- add to ~/.bashrc or ~/.zshrc
eval "$(daft shell-init bash)"

# Fish -- add to ~/.config/fish/config.fish
daft shell-init fish | source

# With short aliases (gwco, gwcob, gwcobd) -- gwcob maps to checkout -b
eval "$(daft shell-init bash --aliases)"
```

Disable auto-cd per-command with `--no-cd` or globally with
`git config daft.autocd false`.

## Hooks System (daft.yml)

Hooks automate worktree lifecycle events. The recommended approach is a
`daft.yml` file at the repository root.

### Hook Types

| Hook                   | Trigger                       | Runs From                   |
| ---------------------- | ----------------------------- | --------------------------- |
| `post-clone`           | After `daft worktree-clone`   | New default branch worktree |
| `worktree-pre-create`  | Before new worktree is added  | Source worktree             |
| `worktree-post-create` | After new worktree is created | New worktree                |
| `worktree-pre-remove`  | Before worktree is removed    | Worktree being removed      |
| `worktree-post-remove` | After worktree is removed     | Current worktree            |

During `daft worktree-clone`, hooks fire in this order: `post-clone` first
(one-time repo bootstrap), then `worktree-post-create` (per-worktree setup).
This lets `post-clone` install foundational tools that `worktree-post-create`
may depend on.

### daft.yml Format

```yaml
min_version: "1.5.0" # Optional: minimum daft version
hooks:
  worktree-post-create:
    parallel: true # Run jobs concurrently (default)
    jobs:
      - name: install-deps
        run: npm install
      - name: setup-env
        run: cp .env.example .env
```

### Config File Locations (first match wins)

`daft.yml`, `daft.yaml`, `.daft.yml`, `.daft.yaml`, `.config/daft.yml`,
`.config/daft.yaml`

Additionally: `daft-local.yml` for machine-specific overrides (not committed),
and per-hook files like `worktree-post-create.yml`.

### Execution Modes

Set one per hook (default is `parallel`):

| Mode     | Field            | Behavior                          |
| -------- | ---------------- | --------------------------------- |
| Parallel | `parallel: true` | All jobs run concurrently         |
| Piped    | `piped: true`    | Sequential; stop on first failure |
| Follow   | `follow: true`   | Sequential; continue on failure   |

### Job Fields

```yaml
- name: job-name # Display name and dependency reference
  description: "Install npm dependencies" # Human-readable description
  run: "npm install" # Inline command (or use script: "setup.sh")
  runner: "bash" # Interpreter for script files
  root: "frontend" # Working directory relative to worktree
  env: # Extra environment variables
    NODE_ENV: development
  tags: ["build"] # Tags for filtering
  skip: CI # Skip when $CI is set
  only: DEPLOY_ENABLED # Only run when $DEPLOY_ENABLED is set
  os: linux # Target OS: macos, linux, windows (or list)
  arch: x86_64 # Target arch: x86_64, aarch64 (or list)
  needs: [install-npm] # Wait for these jobs to complete first
  interactive: true # Needs TTY (forces sequential)
  priority: 1 # Lower runs first
  fail_text: "Setup failed" # Custom failure message
```

### Job Dependencies

```yaml
hooks:
  worktree-post-create:
    jobs:
      - name: install-npm
        run: npm install
      - name: install-pip
        run: pip install -r requirements.txt
      - name: build
        run: npm run build
        needs: [install-npm]
      - name: test
        run: npm test
        needs: [build, install-pip]
```

Independent jobs (`install-npm`, `install-pip`) run in parallel. Dependent jobs
wait for their dependencies.

### Groups

A job can contain a nested group with its own execution mode:

```yaml
- name: checks
  group:
    parallel: true
    jobs:
      - name: lint
        run: cargo clippy
      - name: format
        run: cargo fmt --check
```

### Template Variables

Available in `run` commands:

| Variable            | Description                            |
| ------------------- | -------------------------------------- |
| `{branch}`          | Target branch name                     |
| `{worktree_path}`   | Path to the target worktree            |
| `{worktree_root}`   | Project root directory                 |
| `{source_worktree}` | Path to the source worktree            |
| `{git_dir}`         | Path to the `.git` directory           |
| `{remote}`          | Remote name (usually `origin`)         |
| `{job_name}`        | Name of the current job                |
| `{base_branch}`     | Base branch (for checkout -b commands) |
| `{repository_url}`  | Repository URL (for post-clone)        |
| `{default_branch}`  | Default branch name (for post-clone)   |

### Skip and Only Conditions

```yaml
skip: CI                         # Skip when env var is truthy
skip: true                       # Always skip
skip:
  - merge                        # Skip during merge
  - rebase                       # Skip during rebase
  - ref: "release/*"             # Skip if branch matches glob
  - env: SKIP_HOOKS              # Skip if env var is truthy
  - run: "test -f .skip-hooks"   # Skip if command exits 0
    desc: "Skip file exists"     # Human-readable reason for the skip

only:
  - env: DEPLOY_ENABLED          # Only run when env var is set
  - ref: "main"                  # Only run on main branch
```

### Trust Management

Hooks from untrusted repos do not run automatically. Manage trust with:

```bash
daft hooks trust        # Allow hooks to run
daft hooks prompt       # Prompt before each execution
daft hooks deny         # Never run hooks (default)
daft hooks status       # Check current trust level
daft hooks install      # Scaffold a daft.yml with placeholders
daft hooks validate     # Validate configuration syntax
daft hooks dump         # Show fully merged configuration
daft hooks run <type>   # Manually run a hook (bypasses trust)
```

### Manual Hook Execution

Run hooks on demand, bypassing trust checks (the user is explicitly invoking):

```bash
daft hooks run worktree-post-create              # Run all jobs
daft hooks run worktree-post-create --job "mise" # Run a single job
daft hooks run worktree-post-create --tag setup  # Run jobs tagged "setup"
daft hooks run worktree-post-create --dry-run    # Preview without executing
daft hooks run worktree-post-create --verbose    # Show skipped jobs with reasons
```

Use cases: re-running after a failure, iterating during hook development, or
bootstrapping existing worktrees that predate the hooks config.

### Environment Variables in Hooks

All hooks receive: `DAFT_HOOK`, `DAFT_COMMAND`, `DAFT_PROJECT_ROOT`,
`DAFT_GIT_DIR`, `DAFT_REMOTE`, `DAFT_SOURCE_WORKTREE`.

Worktree hooks add: `DAFT_WORKTREE_PATH`, `DAFT_BRANCH_NAME`.

Creation hooks add: `DAFT_IS_NEW_BRANCH`, `DAFT_BASE_BRANCH`.

Clone hooks add: `DAFT_REPOSITORY_URL`, `DAFT_DEFAULT_BRANCH`.

Removal hooks add: `DAFT_REMOVAL_REASON` (`remote-deleted`, `manual`, or
`ejecting`).

## Environment Tool Detection and Setup

When working in a daft repo, detect environment tools by their marker files and
suggest `daft.yml` hooks to automate setup for new worktrees.

### Tool Detection Table

| Tool       | Marker Files                                      | Purpose                                                 |
| ---------- | ------------------------------------------------- | ------------------------------------------------------- |
| mise       | `.mise.toml`, `.tool-versions`                    | Polyglot runtime manager (Node, Python, Ruby, Go, etc.) |
| direnv     | `.envrc`                                          | Per-directory environment variables                     |
| nvm / fnm  | `.nvmrc`, `.node-version`                         | Node.js version management                              |
| pyenv      | `.python-version`                                 | Python version management                               |
| rbenv      | `.ruby-version`                                   | Ruby version management                                 |
| Docker     | `Dockerfile`, `docker-compose.yml`, `compose.yml` | Containerized development                               |
| npm        | `package.json`, `package-lock.json`               | Node.js dependencies                                    |
| yarn       | `yarn.lock`                                       | Node.js dependencies (Yarn)                             |
| pnpm       | `pnpm-lock.yaml`                                  | Node.js dependencies (pnpm)                             |
| pip        | `requirements.txt`, `pyproject.toml`, `setup.py`  | Python dependencies                                     |
| Cargo      | `Cargo.toml`, `Cargo.lock`                        | Rust dependencies                                       |
| Go modules | `go.mod`, `go.sum`                                | Go dependencies                                         |
| Bundler    | `Gemfile`, `Gemfile.lock`                         | Ruby dependencies                                       |
| Composer   | `composer.json`, `composer.lock`                  | PHP dependencies                                        |

### Hook Jobs for Detected Tools

**mise** (if `.mise.toml` or `.tool-versions` exists):

```yaml
- name: mise-install
  run: mise install
```

**direnv** (if `.envrc` exists):

```yaml
- name: direnv-allow
  run: direnv allow .
```

**nvm** (if `.nvmrc` or `.node-version` exists):

```yaml
- name: nvm-use
  run: |
    export NVM_DIR="$HOME/.nvm"
    [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
    nvm install
```

**npm** (if `package.json` exists):

```yaml
- name: npm-install
  run: npm install
```

**pip with venv** (if `requirements.txt` exists):

```yaml
- name: pip-install
  run: |
    python -m venv .venv
    . .venv/bin/activate
    pip install -r requirements.txt
```

**Cargo** (if `Cargo.toml` exists):

```yaml
- name: cargo-build
  run: cargo build
```

### Comprehensive Example

For a project using mise, direnv, and npm:

```yaml
hooks:
  post-clone:
    piped: true
    jobs:
      - name: mise-install
        run: mise install
      - name: direnv-allow
        run: direnv allow .
      - name: npm-install
        run: npm install
        needs: [mise-install]
      - name: setup-env
        run: cp .env.example .env

  worktree-post-create:
    jobs:
      - name: mise-install
        run: mise install
      - name: direnv-allow
        run: direnv allow .
      - name: npm-install
        run: npm install
        needs: [mise-install]
```

## Suggesting Tooling for Repos That Lack It

When a daft-managed repo has no `daft.yml`, check for dependency files and
suggest creating one. A `worktree-post-create` hook that installs dependencies
is the most impactful automation to add.

### Starter Configurations

**Node.js project** (detected via `package.json`):

```yaml
hooks:
  worktree-post-create:
    jobs:
      - name: install-deps
        run: npm install
```

**Python project** (detected via `requirements.txt` or `pyproject.toml`):

```yaml
hooks:
  worktree-post-create:
    jobs:
      - name: install-deps
        run: |
          python -m venv .venv
          . .venv/bin/activate
          pip install -r requirements.txt
```

**Rust project** (detected via `Cargo.toml`):

```yaml
hooks:
  worktree-post-create:
    jobs:
      - name: build
        run: cargo build
```

**Go project** (detected via `go.mod`):

```yaml
hooks:
  worktree-post-create:
    jobs:
      - name: download-deps
        run: go mod download
```

When suggesting `daft.yml`, also remind the user to trust the repo:
`daft hooks trust`.

## Workflow Guidance for Agents

When working in a daft-managed repository, apply these translations:

| User intent           | Correct daft approach                                                                              |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| "Create a branch"     | `daft worktree-checkout -b <name>` -- creates branch + worktree + pushes                           |
| "Branch from main"    | `daft worktree-checkout -b <name> main` -- branches from the specified base                        |
| "Switch to branch X"  | Navigate to the worktree directory: `cd ../X/`                                                     |
| "Go back"             | `daft worktree-checkout -- -` -- toggles to the previous worktree                                  |
| "Check out a PR"      | `daft worktree-checkout <branch>` -- creates worktree for existing branch                          |
| "Delete a branch"     | `daft worktree-branch -d <branch>` -- removes worktree, local branch, and remote tracking branch   |
| "Clean up branches"   | `daft worktree-prune` -- removes worktrees for deleted remote branches                             |
| "Wrong branch"        | `daft worktree-carry <correct-branch>` -- moves uncommitted changes                                |
| "Update from remote"  | `daft worktree-fetch` -- updates current or specified worktrees (use source:dest for cross-branch) |
| "Adopt existing repo" | `daft worktree-flow-adopt` -- converts traditional repo to daft layout                             |

### Per-worktree Isolation

Each worktree has its **own** `node_modules/`, `.venv/`, `target/`, etc. When a
new worktree is created without `daft.yml` hooks, dependencies are not installed
automatically. If the user creates a new worktree and encounters
missing-dependency errors, the fix is to run the appropriate install command in
that worktree (e.g., `npm install`, `pip install -r requirements.txt`).

### Navigating Worktrees

From any worktree, sibling worktrees are at `../<branch-name>/`. The project
root (containing `.git/`) is at `..` relative to any top-level worktree. Use
`git rev-parse --git-common-dir` to programmatically find the root.

### Modifying Shared Files

Files like `daft.yml`, `.gitignore`, and CI configuration live in each worktree
independently (they are part of the Git-tracked content). Changes to these files
in one worktree must be committed and merged to propagate to other worktrees.

## Shortcuts

daft supports three shortcut styles as symlink aliases for faster terminal use:

| Style         | Shortcuts                                                                                                | Example              |
| ------------- | -------------------------------------------------------------------------------------------------------- | -------------------- |
| Git (default) | `gwtclone`, `gwtinit`, `gwtco`, `gwtcb`, `gwtbd`, `gwtprune`, `gwtcarry`, `gwtfetch`, `gwtls`, `gwtsync` | `gwtco feature/auth` |
| Shell         | `gwco`, `gwcob`                                                                                          | `gwco feature/auth`  |
| Legacy        | `gclone`, `gcw`, `gcbw`, `gprune`                                                                        | `gcw feature/auth`   |

The `gwtcb`, `gwcob`, and `gcbw` shortcuts map to `git-worktree-checkout -b`
(branch creation mode).

Default-branch shortcuts (`gwtcm`, `gwtcbm`, `gwcobd`, `gcbdw`) are available
via shell integration only (`daft shell-init`). They resolve the remote's
default branch dynamically and use `git-worktree-checkout -b`.

Shell integration also provides `gwtrn` (maps to `daft rename`) and `gwtsync`
(maps to `git-sync`) as shell functions with cd behavior.

Manage with `daft setup shortcuts list`, `enable <style>`, `disable <style>`,
`only <style>`.

When a user asks how to use daft more efficiently, mention shortcuts as a
convenience option. Agents should never execute shortcuts directly -- always use
the `daft` binary form (see [Invocation Forms](#invocation-forms)).

## Configuration Reference

Key `git config` settings:

| Key                         | Default       | Description                                            |
| --------------------------- | ------------- | ------------------------------------------------------ |
| `daft.autocd`               | `true`        | CD into new worktrees via shell wrappers               |
| `daft.remote`               | `"origin"`    | Default remote name                                    |
| `daft.checkout.push`        | `true`        | Push new branches to remote                            |
| `daft.checkout.upstream`    | `true`        | Set upstream tracking                                  |
| `daft.checkout.carry`       | `false`       | Carry uncommitted changes on checkout                  |
| `daft.checkoutBranch.carry` | `true`        | Carry uncommitted changes on branch creation           |
| `daft.update.args`          | `"--ff-only"` | Default pull arguments for update (same-branch mode)   |
| `daft.prune.cdTarget`       | `"root"`      | Where to cd after pruning (`root` or `default-branch`) |
| `daft.list.stat`            | `"summary"`   | Statistics mode for list (`summary` or `lines`)        |
| `daft.sync.stat`            | `"summary"`   | Statistics mode for sync (`summary` or `lines`)        |
| `daft.prune.stat`           | `"summary"`   | Statistics mode for prune (`summary` or `lines`)       |
| `daft.go.autoStart`         | `false`       | Auto-create worktree when branch not found in go       |
| `daft.hooks.enabled`        | `true`        | Master switch for hooks                                |
| `daft.hooks.defaultTrust`   | `"deny"`      | Default trust for unknown repos                        |
| `daft.hooks.timeout`        | `300`         | Hook timeout in seconds                                |

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

daft-worktree-workflow

Directory Structure

SKILL.md

Report

Notice