Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Add `intro` page to documentation
Maximilian Roosb1c0be741533
diff --git a/docs/content/advanced.md b/docs/content/advanced.mdindex 36c6f3ef8..fb5771474 100644--- a/docs/content/advanced.md+++ b/docs/content/advanced.md@@ -1,6 +1,6 @@+++title = "Advanced Features"-weight = 6+weight = 7+++Most Worktrunk users get everything they need from `wt switch`, `wt list`, `wt merge`, and `wt remove`. The features below are optional power-user capabilities.@@ -13,14 +13,20 @@ Worktrunk includes a Claude Code plugin for tracking agent status across worktreThe plugin adds status indicators to `wt list`:-```bash-$ wt list- Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message-@ main ^ ./repo b834638e 1d Initial commit-+ feature-api ↑ 🤖 ↑1 ./repo.feature-api 9606cd0f 1d Add REST API endpoints-+ review-ui ? ↑ 💬 ↑1 ./repo.review-ui afd3b353 1d Add dashboard component-+ wip-docs ?_ ./repo.wip-docs b834638e 1d Initial commit-```+<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__with_user_marker.snap — edit source to update -->++{% terminal() %}+<span class="prompt">$</span> wt list+ <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Path</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>+@ <b>main</b> <span style='opacity:0.67'>^</span> <b>./repo</b> <span style='opacity:0.67'>b834638e</span> <span style='opacity:0.67'>1d</span> <span style='opacity:0.67'>Initial commit</span>++ feature-api <span style='opacity:0.67'>↑</span> 🤖 <span style='color:var(--green,#0a0)'>↑1</span> ./repo.feature-api <span style='opacity:0.67'>9606cd0f</span> <span style='opacity:0.67'>1d</span> <span style='opacity:0.67'>Add REST API endpoints</span>++ review-ui <span style='color:var(--cyan,#0aa)'>?</span> <span style='opacity:0.67'>↑</span> 💬 <span style='color:var(--green,#0a0)'>↑1</span> ./repo.review-ui <span style='opacity:0.67'>afd3b353</span> <span style='opacity:0.67'>1d</span> <span style='opacity:0.67'>Add dashboard component</span>++ <span style='opacity:0.67'>wip-docs</span> <span style='color:var(--cyan,#0aa)'>?</span><span style='opacity:0.67'>_</span> <span style='opacity:0.67'>./repo.wip-docs</span> <span style='opacity:0.67'>b834638e</span> <span style='opacity:0.67'>1d</span> <span style='opacity:0.67'>Initial commit</span>++⚪ <span style='opacity:0.67'>Showing 4 worktrees, 2 ahead</span>+{% end %}++<!-- END AUTO-GENERATED -->- `🤖` — Claude is working- `💬` — Claude is waiting for input@@ -44,7 +50,9 @@ $ git config worktrunk.marker.feature "💬" # Direct git config## Statusline Integration-`wt list statusline` outputs a single-line status for shell prompts, starship, or editor integrations.+`wt list statusline` outputs a single-line status for shell prompts, starship, or editor integrations.[^1]++[^1]: Currently this grabs CI status, so is too slow to use in synchronous contexts. If a faster version would be helpful, please [open an issue](https://github.com/max-sixty/worktrunk/issues).### Claude Code statuslinediff --git a/docs/content/commands.md b/docs/content/commands.mdindex 07003c5a2..b4f2a54bf 100644--- a/docs/content/commands.md+++ b/docs/content/commands.md@@ -1,6 +1,6 @@+++title = "Commands Reference"-weight = 4+weight = 5+++## wt switch@@ -692,6 +692,9 @@ Global Options:## wt select+<!-- TODO: This content should come from `wt select --help-md` like other commands.+ Add the keyboard shortcuts to the help text in the codebase. -->+Interactive fzf-like fuzzy-search worktree picker with diff preview. Unix only.Navigate worktrees with keyboard shortcuts:diff --git a/docs/content/concepts.md b/docs/content/concepts.mdindex 402b559bb..8c96fcf2d 100644--- a/docs/content/concepts.md+++ b/docs/content/concepts.md@@ -1,6 +1,6 @@+++title = "Concepts"-weight = 2+weight = 3+++## Why git worktrees?@@ -29,6 +29,65 @@ Git's built-in `worktree` commands require remembering worktree locations and co| List | `wt list` (with diffstats & status) | `git worktree list` (just names & paths) || List with CI status | `wt list --full` | N/A |+### Local merging with `wt merge`++`wt merge` handles the full merge workflow: stage, commit, squash, rebase, merge, cleanup. Includes LLM commit messages, project hooks, and flags for skipping steps.++| Task | Worktrunk | Plain git |+|------|-----------|-----------|+| Merge + clean up | `wt merge` | `git add -A && git reset --soft $(git merge-base HEAD main) && git diff --staged \| llm "..." \| git commit -F - && git rebase main && cargo test && cd ../repo && git merge --ff-only feature && git worktree remove ../repo.feature && git branch -d feature && cargo install --path .` |++<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__merge__readme_example_complex.snap — edit source to update -->++{% terminal() %}+<span class="prompt">$</span> wt merge+🔄 <span style='color:var(--cyan,#0aa)'>Squashing 3 commits into a single commit <span style='color:var(--bright-black,#555)'>(3 files, <span style='color:var(--green,#0a0)'>+33</span></span></span><span style='color:var(--bright-black,#555)'>)</span>...+🔄 <span style='color:var(--cyan,#0aa)'>Generating squash commit message...</span>+<span style='background:var(--bright-white,#fff)'> </span> <b>feat(auth): Implement JWT authentication system</b>+<span style='background:var(--bright-white,#fff)'> </span>+<span style='background:var(--bright-white,#fff)'> </span> Add comprehensive JWT token handling including validation, refresh logic,+<span style='background:var(--bright-white,#fff)'> </span> and authentication tests. This establishes the foundation for secure+<span style='background:var(--bright-white,#fff)'> </span> API authentication.+<span style='background:var(--bright-white,#fff)'> </span>+<span style='background:var(--bright-white,#fff)'> </span> - Implement token refresh mechanism with expiry handling+<span style='background:var(--bright-white,#fff)'> </span> - Add JWT encoding/decoding with signature verification+<span style='background:var(--bright-white,#fff)'> </span> - Create test suite covering all authentication flows+✅ <span style='color:var(--green,#0a0)'>Squashed @ <span style='opacity:0.67'>95c3316</span></span>+🔄 <span style='color:var(--cyan,#0aa)'>Running pre-merge <b>test</b>:</span>+<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>cargo</span></span><span style='opacity:0.67'> test</span>+ Finished test [unoptimized + debuginfo] target(s) in 0.12s+ Running unittests src/lib.rs (target/debug/deps/worktrunk-abc123)++running 18 tests+test auth::tests::test_jwt_decode ... ok+test auth::tests::test_jwt_encode ... ok+test auth::tests::test_token_refresh ... ok+test auth::tests::test_token_validation ... ok++test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.08s+🔄 <span style='color:var(--cyan,#0aa)'>Running pre-merge <b>lint</b>:</span>+<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>cargo</span></span><span style='opacity:0.67'> clippy</span>+ Checking worktrunk v0.1.0+ Finished dev [unoptimized + debuginfo] target(s) in 1.23s+🔄 <span style='color:var(--cyan,#0aa)'>Merging 1 commit to <b>main</b> @ <span style='opacity:0.67'>95c3316</span> (no rebase needed)</span>+<span style='background:var(--bright-white,#fff)'> </span> * <span style='color:var(--yellow,#a60)'>95c3316</span> feat(auth): Implement JWT authentication system+<span style='background:var(--bright-white,#fff)'> </span> auth.rs | 8 <span style='color:var(--green,#0a0)'>++++++++</span>+<span style='background:var(--bright-white,#fff)'> </span> auth_test.rs | 17 <span style='color:var(--green,#0a0)'>+++++++++++++++++</span>+<span style='background:var(--bright-white,#fff)'> </span> jwt.rs | 8 <span style='color:var(--green,#0a0)'>++++++++</span>+<span style='background:var(--bright-white,#fff)'> </span> 3 files changed, 33 insertions(+)+✅ <span style='color:var(--green,#0a0)'>Merged to <b>main</b> <span style='color:var(--bright-black,#555)'>(1 commit, 3 files, +33</span></span><span style='color:var(--bright-black,#555)'>)</span>+🔄 <span style='color:var(--cyan,#0aa)'>Removing <b>feature-auth</b> worktree & branch in background (already in main)</span>+🔄 <span style='color:var(--cyan,#0aa)'>Running post-merge <b>install</b>:</span>+<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>cargo</span></span><span style='opacity:0.67'> install </span><span style='opacity:0.67'><span style='color:var(--cyan,#0aa)'>--path</span></span><span style='opacity:0.67'> .</span>+ Installing worktrunk v0.1.0+ Compiling worktrunk v0.1.0+ Finished release [optimized] target(s) in 2.34s+ Installing ~/.cargo/bin/wt+ Installed package `worktrunk v0.1.0` (executable `wt`)+{% end %}++<!-- END AUTO-GENERATED -->+### What Worktrunk adds- **Branch-based navigation**: Address worktrees by branch name, not pathdiff --git a/docs/content/configuration.md b/docs/content/configuration.mdindex 15a92633c..4ca1fff01 100644--- a/docs/content/configuration.md+++ b/docs/content/configuration.md@@ -1,8 +1,11 @@+++title = "Configuration"-weight = 3+weight = 4++++<!-- TODO: This user config vs project config distinction is a good organizing+ principle - consider orienting more of the docs around it -->+Worktrunk uses two configuration files:- **User config**: `~/.config/worktrunk/config.toml` — Personal settings, LLM commands, saved approvalsdiff --git a/docs/content/faq.md b/docs/content/faq.mdindex d11048195..3cee0c329 100644--- a/docs/content/faq.md+++ b/docs/content/faq.md@@ -1,6 +1,6 @@+++title = "FAQ"-weight = 7+weight = 8+++## What commands does Worktrunk execute?@@ -15,7 +15,9 @@ Commands from project hooks and LLM configuration require approval on first run.### Example approval prompt-```+<!-- ⚠️ AUTO-GENERATED from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_approval_prompt.snap — edit source to update -->++```text🟡 repo needs approval to execute 3 commands:⚪ post-create install:@@ -30,6 +32,8 @@ Commands from project hooks and LLM configuration require approval on first run.💡 Allow and remember? [y/N]```+<!-- END AUTO-GENERATED -->+Use `--force` to bypass prompts (useful for CI/automation).## How does Worktrunk compare to alternatives?diff --git a/docs/content/intro.md b/docs/content/intro.mdnew file mode 100644index 000000000..10ff031aa--- /dev/null+++ b/docs/content/intro.md@@ -0,0 +1,17 @@+++++title = "Intro"+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. The goal is to make spinning up a new AI "developer" for a task feel as routine as `git switch`.++++## Getting Started++We recommend:++- **Start with Worktrunk as a simpler & better `git worktree`**: create, navigate, list, and clean up git worktrees with ease+- **Later use the more advanced features if they resonate**: [LLM commit messages](/configuration/#llm-commit-messages), [local merging with CI-like checks](/concepts/#local-merging-with-wt-merge), [fzf-like worktree picker](/commands/#wt-select), [Claude Code integration](/advanced/#claude-code-integration), and more++Ready? Head to the [Quick Start](/quickstart/).diff --git a/docs/content/quickstart.md b/docs/content/quickstart.mdindex 7aa8c2706..aadb97f75 100644--- a/docs/content/quickstart.md+++ b/docs/content/quickstart.md@@ -1,6 +1,6 @@+++title = "Quick Start"-weight = 1+weight = 2+++## Install@@ -76,19 +76,8 @@ When you're done with a worktree (e.g., after merging via CI):Worktrunk checks if your changes are already on main before deleting the branch.-## Shortcuts--Use these shortcuts for common targets:--- `@` — current branch/worktree-- `-` — previous worktree (like `cd -`)-- `^` — main/default branch--```bash-$ wt switch - # Switch to previous worktree-$ wt switch --create hotfix --base=@ # Branch from current HEAD-$ wt remove @ # Remove current worktree-```+<!-- TODO: Add shortcuts (@, -, ^) somewhere more prominent in the docs -+ too early for quickstart but should be discoverable -->## Next stepsdiff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 3e910576d..0434dada8 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -1,6 +1,6 @@+++title = "Tips & Patterns"-weight = 5+weight = 6+++Practical recipes for common Worktrunk workflows.diff --git a/docs/static/wt-demo.gif b/docs/static/wt-demo.gifnew file mode 100644index 000000000..47039f660Binary files /dev/null and b/docs/static/wt-demo.gif differdiff --git a/docs/templates/index.html b/docs/templates/index.htmlindex dd8cd1eb5..07f64e43d 100644--- a/docs/templates/index.html+++ b/docs/templates/index.html@@ -107,14 +107,14 @@{% endblock toc %}{% block content %}-{# Display quickstart content directly on homepage - relies on quickstart.md existing #}+{# Display intro content directly on homepage #}{% set docs_section = get_section(path="_index.md") %}-{% set quickstart = docs_section.pages | filter(attribute="slug", value="quickstart") | first %}-<div class="heading-text">{{ quickstart.title }}</div>-{{ quickstart.content | safe }}+{% set intro = docs_section.pages | filter(attribute="slug", value="intro") | first %}+<div class="heading-text">{{ intro.title }}</div>+{{ intro.content | safe }}<div class="page-nav" style="justify-content: flex-end;">- {% set concepts = docs_section.pages | filter(attribute="slug", value="concepts") | first %}- <a href="{{ concepts.permalink | safe }}">{{ concepts.title }} →</a>+ {% set quickstart = docs_section.pages | filter(attribute="slug", value="quickstart") | first %}+ <a href="{{ quickstart.permalink | safe }}">{{ quickstart.title }} →</a></div>{% endblock content %}diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex 98dbc53cb..ea04fa314 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -808,6 +808,8 @@ fn test_docs_quickstart_examples_are_in_sync() {let doc_files = ["docs/content/quickstart.md","docs/content/configuration.md",+ "docs/content/concepts.md",+ "docs/content/advanced.md",];let mut all_errors = Vec::new();