Skip to content

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.toml
index 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.md
index 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-auth
worktree-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 messages
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 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.md
index 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-auth
worktree-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 messages
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index 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.rs
index 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-auth
worktree-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 messages
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index 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: 40
info:
program: wt
args:
@@ -10,6 +9,7 @@ info:
env:
CLICOLOR_FORCE: "1"
COLUMNS: "500"
+ GIT_EDITOR: ""
LANG: C
LC_ALL: C
NO_COLOR: ""
@@ -72,7 +72,7 @@ Creates ~/.config/worktrunk/config.toml with the following content:
  #
  # **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`)
@@ -92,7 +92,11 @@ Creates ~/.config/worktrunk/config.toml with the following content:
  # # 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/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 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: 40
info:
program: wt
args:
@@ -9,6 +8,7 @@ info:
env:
CLICOLOR_FORCE: "1"
COLUMNS: "500"
+ GIT_EDITOR: ""
LANG: C
LC_ALL: C
NO_COLOR: ""
@@ -117,7 +117,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)
@@ -136,8 +136,12 @@ Controls where new worktrees are created.
  # Centralized worktrees directory
  # Creates: ~/worktrees/myproject/feature-auth
  worktree-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 messages