Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: add bare repository worktree-path example and layout guide (#1664)
Maximilian Roos7339e4b283c4
diff --git a/dev/config.example.toml b/dev/config.example.tomlindex a48aaf0c1..f71078c48 100644--- a/dev/config.example.toml+++ b/dev/config.example.toml@@ -13,7 +13,7 @@## **Variables:**#-# - `{{ repo_path }}` — absolute path to the repository (e.g., `/Users/me/code/myproject`)+# - `{{ repo_path }}` — absolute path to the repository root (e.g., `/Users/me/code/myproject`. Or for bare repos, the bare directory itself)# - `{{ repo }}` — repository directory name (e.g., `myproject`)# - `{{ branch }}` — raw branch name (e.g., `feature/auth`)# - `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)@@ -33,7 +33,11 @@# # Creates: ~/worktrees/myproject/feature-auth# worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"#-# `~` expands to the home directory. Relative paths are relative to the repository root.+# # Bare repository (git clone --bare <url> myproject/.git)+# # Creates: ~/code/myproject/feature-auth+# worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"+#+# `~` expands to the home directory. Relative paths resolve from `repo_path`.## ## LLM commit messages#diff --git a/docs/content/config.md b/docs/content/config.mdindex 24c72f41a..28bd2cc20 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -83,7 +83,7 @@ Controls where new worktrees are created.**Variables:**-- `{{ repo_path }}` — absolute path to the repository (e.g., `/Users/me/code/myproject`)+- `{{ repo_path }}` — absolute path to the repository root (e.g., `/Users/me/code/myproject`. Or for bare repos, the bare directory itself)- `{{ repo }}` — repository directory name (e.g., `myproject`)- `{{ branch }}` — raw branch name (e.g., `feature/auth`)- `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)@@ -103,9 +103,13 @@ worktree-path = "{{ repo_path }}/.worktrees/{{ branch | sanitize }}"# Centralized worktrees directory# Creates: ~/worktrees/myproject/feature-authworktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"++# Bare repository (git clone --bare <url> myproject/.git)+# Creates: ~/code/myproject/feature-auth+worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"```-`~` expands to the home directory. Relative paths are relative to the repository root.+`~` expands to the home directory. Relative paths resolve from `repo_path`.## LLM commit messagesdiff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 491a54c36..1cf6dd7df 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -362,7 +362,16 @@ alias wtlog='f() { tail -f "$(wt config state logs get --hook="$1")"; }; f'## Bare repository layout-An alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories:+A [bare repository](https://git-scm.com/docs/gitrepository-layout) has no working tree, so all branches — including the default — are [linked worktrees](https://git-scm.com/docs/git-worktree) at equal paths. No branch gets special treatment.++Cloning a bare repo into `<project>/.git` puts all worktrees under one directory:++```bash+git clone --bare <url> myproject/.git+cd myproject+```++With `worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"`, worktrees become subdirectories of `myproject/`:```myproject/@@ -372,18 +381,11 @@ myproject/└── bugfix/ # bugfix branch```-Setup:--```bash-git clone --bare <url> myproject/.git-cd myproject-```--Configure worktrunk to create worktrees as subdirectories:+Configure worktrunk:```toml# ~/.config/worktrunk/config.toml-worktree-path = "../{{ branch | sanitize }}"+worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"```Create the first worktree:diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex f56a845e4..ca7d368ab 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -74,7 +74,7 @@ Controls where new worktrees are created.**Variables:**-- `{{ repo_path }}` — absolute path to the repository (e.g., `/Users/me/code/myproject`)+- `{{ repo_path }}` — absolute path to the repository root (e.g., `/Users/me/code/myproject`. Or for bare repos, the bare directory itself)- `{{ repo }}` — repository directory name (e.g., `myproject`)- `{{ branch }}` — raw branch name (e.g., `feature/auth`)- `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)@@ -94,9 +94,13 @@ worktree-path = "{{ repo_path }}/.worktrees/{{ branch | sanitize }}"# Centralized worktrees directory# Creates: ~/worktrees/myproject/feature-authworktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"++# Bare repository (git clone --bare <url> myproject/.git)+# Creates: ~/code/myproject/feature-auth+worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"```-`~` expands to the home directory. Relative paths are relative to the repository root.+`~` expands to the home directory. Relative paths resolve from `repo_path`.## LLM commit messagesdiff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex f594d2fd2..21078f070 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -351,7 +351,16 @@ alias wtlog='f() { tail -f "$(wt config state logs get --hook="$1")"; }; f'## Bare repository layout-An alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories:+A [bare repository](https://git-scm.com/docs/gitrepository-layout) has no working tree, so all branches — including the default — are [linked worktrees](https://git-scm.com/docs/git-worktree) at equal paths. No branch gets special treatment.++Cloning a bare repo into `<project>/.git` puts all worktrees under one directory:++```bash+git clone --bare <url> myproject/.git+cd myproject+```++With `worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"`, worktrees become subdirectories of `myproject/`:```myproject/@@ -361,18 +370,11 @@ myproject/└── bugfix/ # bugfix branch```-Setup:--```bash-git clone --bare <url> myproject/.git-cd myproject-```--Configure worktrunk to create worktrees as subdirectories:+Configure worktrunk:```toml# ~/.config/worktrunk/config.toml-worktree-path = "../{{ branch | sanitize }}"+worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"```Create the first worktree:diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 48d38ccbe..403a289db 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1616,7 +1616,7 @@ Controls where new worktrees are created.**Variables:**-- `{{ repo_path }}` — absolute path to the repository (e.g., `/Users/me/code/myproject`)+- `{{ repo_path }}` — absolute path to the repository root (e.g., `/Users/me/code/myproject`. Or for bare repos, the bare directory itself)- `{{ repo }}` — repository directory name (e.g., `myproject`)- `{{ branch }}` — raw branch name (e.g., `feature/auth`)- `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)@@ -1636,9 +1636,13 @@ worktree-path = "{{ repo_path }}/.worktrees/{{ branch | sanitize }}"# Centralized worktrees directory# Creates: ~/worktrees/myproject/feature-authworktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"++# Bare repository (git clone --bare <url> myproject/.git)+# Creates: ~/code/myproject/feature-auth+worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"```-`~` expands to the home directory. Relative paths are relative to the repository root.+`~` expands to the home directory. Relative paths resolve from `repo_path`.## LLM commit messagesdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snapindex b9f628799..67ec1120e 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap@@ -1,6 +1,5 @@---source: tests/integration_tests/help.rs-assertion_line: 40info:program: wtargs:@@ -10,6 +9,7 @@ info:env:CLICOLOR_FORCE: "1"COLUMNS: "500"+ GIT_EDITOR: ""LANG: CLC_ALL: CNO_COLOR: ""@@ -72,7 +72,7 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[107m [0m [2m#[0m[107m [0m [2m# **Variables:**[0m[107m [0m [2m#[0m-[107m [0m [2m# - `{{ repo_path }}` — absolute path to the repository (e.g., `/Users/me/code/myproject`)[0m+[107m [0m [2m# - `{{ repo_path }}` — absolute path to the repository root (e.g., `/Users/me/code/myproject`. Or for bare repos, the bare directory itself)[0m[107m [0m [2m# - `{{ repo }}` — repository directory name (e.g., `myproject`)[0m[107m [0m [2m# - `{{ branch }}` — raw branch name (e.g., `feature/auth`)[0m[107m [0m [2m# - `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)[0m@@ -92,7 +92,11 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[107m [0m [2m# # Creates: ~/worktrees/myproject/feature-auth[0m[107m [0m [2m# worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"[0m[107m [0m [2m#[0m-[107m [0m [2m# `~` expands to the home directory. Relative paths are relative to the repository root.[0m+[107m [0m [2m# # Bare repository (git clone --bare <url> myproject/.git)[0m+[107m [0m [2m# # Creates: ~/code/myproject/feature-auth[0m+[107m [0m [2m# worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"[0m+[107m [0m [2m#[0m+[107m [0m [2m# `~` expands to the home directory. Relative paths resolve from `repo_path`.[0m[107m [0m [2m#[0m[107m [0m [2m# ## LLM commit messages[0m[107m [0m [2m#[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snapindex dea703aa1..71f49ca7b 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap@@ -1,6 +1,5 @@---source: tests/integration_tests/help.rs-assertion_line: 40info:program: wtargs:@@ -9,6 +8,7 @@ info:env:CLICOLOR_FORCE: "1"COLUMNS: "500"+ GIT_EDITOR: ""LANG: CLC_ALL: CNO_COLOR: ""@@ -117,7 +117,7 @@ Controls where new worktrees are created.[1mVariables:[0m-- [2m{{ repo_path }}[0m — absolute path to the repository (e.g., [2m/Users/me/code/myproject[0m)+- [2m{{ repo_path }}[0m — absolute path to the repository root (e.g., [2m/Users/me/code/myproject[0m. Or for bare repos, the bare directory itself)- [2m{{ repo }}[0m — repository directory name (e.g., [2mmyproject[0m)- [2m{{ branch }}[0m — raw branch name (e.g., [2mfeature/auth[0m)- [2m{{ branch | sanitize }}[0m — filesystem-safe: [2m/[0m and [2m\[0m become [2m-[0m (e.g., [2mfeature-auth[0m)@@ -136,8 +136,12 @@ Controls where new worktrees are created.[107m [0m [2m# Centralized worktrees directory[0m[107m [0m [2m# Creates: ~/worktrees/myproject/feature-auth[0m[107m [0m [2mworktree-path = [0m[2m[32m"~/worktrees/{{ repo }}/{{ branch | sanitize }}"[0m+[107m [0m+[107m [0m [2m# Bare repository (git clone --bare <url> myproject/.git)[0m+[107m [0m [2m# Creates: ~/code/myproject/feature-auth[0m+[107m [0m [2mworktree-path = [0m[2m[32m"{{ repo_path }}/../{{ branch | sanitize }}"[0m-[2m~[0m expands to the home directory. Relative paths are relative to the repository root.+[2m~[0m expands to the home directory. Relative paths resolve from [2mrepo_path[0m.[1m[32mLLM commit messages[0m