Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

fix: documentation incorrectly shows ~ concatenation with | filter without parentheses (#373)

coriocactusab4b7e680109
diff --git a/docs/content/hook.md b/docs/content/hook.md
index ee69b4c83..b10c37ee0 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -173,7 +173,7 @@ Hash any string, including concatenations:
```toml
# Unique port per repo+branch combination
-dev = "npm run dev --port {{ repo ~ '-' ~ branch | hash_port }}"
+dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"
```
### JSON context
@@ -275,7 +275,7 @@ Each worktree can have its own database. Docker containers get unique names and
db = """
docker run -d --rm \
--name {{ repo }}-{{ branch | sanitize }}-postgres \
- -p {{ 'db-' ~ branch | hash_port }}:5432 \
+ -p {{ ('db-' ~ branch) | hash_port }}:5432 \
-e POSTGRES_DB={{ repo }} \
-e POSTGRES_PASSWORD=dev \
postgres:16
@@ -285,7 +285,8 @@ docker run -d --rm \
db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
```
-The `'db-' ~ branch` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.
+The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.
+Jinja2's operator precedence has pipe `|` with higher precedence than concatenation `~`, meaning expressions need parentheses to filter concatenated values.
Generate `.env.local` with the connection string:
@@ -293,7 +294,7 @@ Generate `.env.local` with the connection string:
[post-create]
env = """
cat > .env.local << EOF
-DATABASE_URL=postgres://postgres:dev@localhost:{{ 'db-' ~ branch | hash_port }}/{{ repo }}
+DATABASE_URL=postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ repo }}
DEV_PORT={{ branch | hash_port }}
EOF
"""
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index c7452edcd..f6095dbf6 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -77,7 +77,7 @@ Each worktree can have its own isolated database. Docker containers get unique n
db = """
docker run -d --rm \
--name {{ repo }}-{{ branch | sanitize }}-postgres \
- -p {{ 'db-' ~ branch | hash_port }}:5432 \
+ -p {{ ('db-' ~ branch) | hash_port }}:5432 \
-e POSTGRES_DB={{ repo }} \
-e POSTGRES_PASSWORD=dev \
postgres:16
@@ -87,7 +87,8 @@ docker run -d --rm \
db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
```
-The `'db-' ~ branch` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.
+The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.
+Jinja2's operator precedence has pipe `|` with higher precedence than concatenation `~`, meaning expressions need parentheses to filter concatenated values.
Generate `.env.local` with the correct `DATABASE_URL` using a `post-create` hook:
@@ -95,7 +96,7 @@ Generate `.env.local` with the correct `DATABASE_URL` using a `post-create` hook
[post-create]
env = """
cat > .env.local << EOF
-DATABASE_URL=postgres://postgres:dev@localhost:{{ 'db-' ~ branch | hash_port }}/{{ repo }}
+DATABASE_URL=postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ repo }}
DEV_PORT={{ branch | hash_port }}
EOF
"""
diff --git a/src/cli.rs b/src/cli.rs
index 56a8f2f7a..7299dd797 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1643,7 +1643,7 @@ Hash any string, including concatenations:
```toml
# Unique port per repo+branch combination
-dev = "npm run dev --port {{ repo ~ '-' ~ branch | hash_port }}"
+dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"
```
### JSON context
@@ -1745,7 +1745,7 @@ Each worktree can have its own database. Docker containers get unique names and
db = """
docker run -d --rm \
--name {{ repo }}-{{ branch | sanitize }}-postgres \
- -p {{ 'db-' ~ branch | hash_port }}:5432 \
+ -p {{ ('db-' ~ branch) | hash_port }}:5432 \
-e POSTGRES_DB={{ repo }} \
-e POSTGRES_PASSWORD=dev \
postgres:16
@@ -1755,7 +1755,8 @@ docker run -d --rm \
db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
```
-The `'db-' ~ branch` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.
+The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.
+Jinja2's operator precedence has pipe `|` with higher precedence than concatenation `~`, meaning expressions need parentheses to filter concatenated values.
Generate `.env.local` with the connection string:
@@ -1763,7 +1764,7 @@ Generate `.env.local` with the connection string:
[post-create]
env = """
cat > .env.local << EOF
-DATABASE_URL=postgres://postgres:dev@localhost:{{ 'db-' ~ branch | hash_port }}/{{ repo }}
+DATABASE_URL=postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ repo }}
DEV_PORT={{ branch | hash_port }}
EOF
"""
diff --git a/src/config/expansion.rs b/src/config/expansion.rs
index 6e8062c9e..30ee7ef64 100644
--- a/src/config/expansion.rs
+++ b/src/config/expansion.rs
@@ -16,7 +16,7 @@
//! - `hash_port` — Hash a string to a deterministic port number (10000-19999)
//! ```text
//! {{ branch | hash_port }} → 12472
-//! {{ repo ~ "-" ~ branch | hash_port }} → 15839
+//! {{ (repo ~ "-" ~ branch) | hash_port }} → 15839
//! ```
use minijinja::{Environment, Value};
@@ -294,8 +294,14 @@ mod tests {
assert!((10000..20000).contains(&port));
// Concatenation produces different (but deterministic) result
- let r1 = expand_template("{{ repo ~ '-' ~ branch | hash_port }}", &vars, false).unwrap();
- let r2 = expand_template("{{ repo ~ '-' ~ branch | hash_port }}", &vars, false).unwrap();
+ let r1 = expand_template("{{ (repo ~ '-' ~ branch) | hash_port }}", &vars, false).unwrap();
+ let r1_port: u16 = r1.parse().expect("should be a number");
+ let r2 = expand_template("{{ (repo ~ '-' ~ branch) | hash_port }}", &vars, false).unwrap();
+ let r2_port: u16 = r2.parse().expect("should be a number");
+
+ assert!((10000..20000).contains(&r1_port));
+ assert!((10000..20000).contains(&r2_port));
+
assert_eq!(r1, r2);
}
}