Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Merge concepts into quickstart and reorganize opening page
Maximilian Roosc7167aaf569c
diff --git a/docs/content/concepts.md b/docs/content/concepts.mddeleted file mode 100644index 351c1b792..000000000--- a/docs/content/concepts.md+++ /dev/null@@ -1,47 +0,0 @@-+++-title = "Concepts"-weight = 2-+++--## Why git worktrees?--When working with multiple AI agents (or multiple tasks), you have a few options:--| Approach | Pros | Cons |-|----------|------|------|-| One working tree, many branches | Simple setup | Agents step on each other, can't use git for staging/committing |-| Multiple clones | Full isolation | Slow to set up, drift out of sync |-| Git worktrees | Isolation + shared history | Requires management |--Git worktrees are a built-in git feature that creates multiple working directories from a single repository. Each worktree has its own branch and working tree, while sharing the object database and refs with the main repository. Branches created in one worktree are immediately visible to others with no sync overhead.--For more details, see [git-worktree documentation](https://git-scm.com/docs/git-worktree).--## Why Worktrunk?--Git's `worktree` commands require remembering paths and composing git + `cd` sequences. Worktrunk bundles these into simple commands and adds extended capabilities.--### Simple commands--Worktrunk addresses worktrees by branch name rather than filesystem path, using consistent directory naming (`repo.branch`, customizable):--| Task | Worktrunk | Plain git |-|------|-----------|-----------|-| Switch worktrees | `wt switch feature` | `cd ../repo.feature` |-| Create + start Claude | `wt switch -c -x claude feature` | `git worktree add -b feature ../repo.feature main && cd ../repo.feature && claude` |-| Clean up | `wt remove` | `cd ../repo && git worktree remove ../repo.feature && git branch -d feature` |-| List | `wt list` (with diffstats & status) | `git worktree list` (just names & paths) |--### Extended capabilities--Beyond simplifying common tasks, Worktrunk adds features that git worktrees don't provide.--**[LLM commit messages](@/llm-commits.md)** generate commit messages from diffs using external tools like [llm](https://llm.datasette.io/). Works for regular commits and squash commits during merge.--**[Lifecycle hooks](@/hooks.md)** run project-defined commands at key points: worktree creation, switching, and merging. Use them for dependency installation, dev servers, formatters, tests, or deployment.--**[Unified status](@/list.md)** shows changes, ahead/behind counts, diff stats, and commit messages across all worktrees. With `--full`, it adds CI status (GitHub/GitLab), conflict detection, and line-level diffs against main.--**[Merge workflow](@/merge.md)** handles the full pipeline: stage, squash, rebase, run hooks, push, and clean up.--**[Safe cleanup](@/remove.md#branch-cleanup)** validates that changes are integrated before deleting worktrees and branches.diff --git a/docs/content/quickstart.md b/docs/content/quickstart.mdindex 8825cd2b5..f211c8cc8 100644--- a/docs/content/quickstart.md+++ b/docs/content/quickstart.md@@ -1,29 +1,44 @@+++-title = "Quick Start"+title = "Why Worktrunk?"weight = 1+++-Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows. Git worktrees give each agent an isolated branch and directory; Worktrunk adds branch-based navigation, unified status, and lifecycle hooks. It makes spinning up a new AI "developer" for a task feel as routine as `git switch`.+Worktrunk is a CLI for git worktree management, designed for parallel AI agent workflows. Git worktrees give each agent an isolated branch and directory; Worktrunk adds branch-based navigation, unified status, and lifecycle hooks. Creating a new agent workspace is as quick as `git switch`.-## Install+## The problem-**Homebrew (macOS & Linux):**+Multiple AI agents on one repo need isolation:-```bash-$ brew install max-sixty/worktrunk/wt-$ wt config shell install # allows commands to change directories-```+| Approach | Tradeoff |+|----------|----------|+| One working tree, many branches | Agents step on each other; can't use git for staging |+| Multiple clones | Slow setup, repos drift out of sync |+| Git worktrees | Isolation + shared history, but requires management |-**Cargo:**+Git worktrees provide isolation with shared history. But git's built-in commands require remembering paths and composing `git` + `cd` sequences.-```bash-$ cargo install worktrunk-$ wt config shell install-```+## What Worktrunk adds++Worktrunk addresses worktrees by branch name, not path:++| Task | Worktrunk | Plain git |+|------|-----------|-----------|+| Switch worktrees | `wt switch feature` | `cd ../repo.feature` |+| Create + start Claude | `wt switch -c -x claude feature` | `git worktree add -b feature ../repo.feature && cd ../repo.feature && claude` |+| Clean up | `wt remove` | `cd ../repo && git worktree remove ../repo.feature && git branch -d feature` |+| List with status | `wt list` | `git worktree list` (paths only) |-## Create a worktree+Beyond navigation:++- **[LLM commit messages](@/llm-commits.md)** — generate commits from diffs using tools like [llm](https://llm.datasette.io/)+- **[Lifecycle hooks](@/hooks.md)** — run commands on create, switch, merge (deps, dev servers, tests)+- **[Unified status](@/list.md)** — changes, ahead/behind, diffs, CI status across all worktrees+- **[Safe cleanup](@/remove.md)** — validates changes are integrated before deleting+- **[Merge workflow](@/merge.md)** — stage, squash, rebase, push, clean up++## In practice<!-- ⚠️ AUTO-GENERATED-HTML from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_simple_switch.snap — edit source to update -->@@ -36,8 +51,6 @@ $ wt config shell installThis creates `../repo.fix-auth` on branch `fix-auth`.-## Switch between worktrees-<!-- ⚠️ AUTO-GENERATED-HTML from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_switch_back.snap — edit source to update -->{% terminal() %}@@ -47,8 +60,6 @@ This creates `../repo.fix-auth` on branch `fix-auth`.<!-- END AUTO-GENERATED -->-## List worktrees-<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__readme_example_list.snap — edit source to update -->{% terminal() %}@@ -63,11 +74,9 @@ This creates `../repo.fix-auth` on branch `fix-auth`.<!-- END AUTO-GENERATED -->-Add `--full` for CI status and conflicts. Add `--branches` to include all branches.+Add `--full` for CI status and conflicts, `--branches` to include all branches.-## Clean up--When you're done with a worktree (e.g., after merging via CI):+When done with a worktree (e.g., after merging via CI):<!-- ⚠️ AUTO-GENERATED-HTML from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_remove.snap — edit source to update -->@@ -78,10 +87,26 @@ When you're done with a worktree (e.g., after merging via CI):<!-- END AUTO-GENERATED -->-Worktrunk checks if your changes are already on main before deleting the branch.+Worktrunk checks if changes are already on main before deleting the branch.++## Install++**Homebrew (macOS & Linux):**++```bash+$ brew install max-sixty/worktrunk/wt+$ wt config shell install # allows commands to change directories+```++**Cargo:**++```bash+$ cargo install worktrunk+$ wt config shell install+```## Next steps-- Understand [why worktrees matter](@/concepts.md) and how Worktrunk improves on plain git+- Learn the core commands: [wt switch](@/switch.md), [wt list](@/list.md), [wt remove](@/remove.md)- Set up [project hooks](@/hooks.md) for automated setup-- Explore advanced features: [LLM commit messages](@/llm-commits.md), [local merging](@/merge.md), [fzf-like picker](@/select.md), [Claude Code integration](@/claude-code.md)+- Explore [LLM commit messages](@/llm-commits.md), [local merging](@/merge.md), [fzf-like picker](@/select.md), [Claude Code integration](@/claude-code.md)