Skip to content

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

feat(config): add `sanitize_hash` template filter (#2172)

Maximilian Roosd7680a27c692
diff --git a/docs/content/extending.md b/docs/content/extending.md
index 674f1543e..fb660d70e 100644
--- a/docs/content/extending.md
+++ b/docs/content/extending.md
@@ -132,25 +132,6 @@ When both user and project config define the same alias name, both run — user
Alias names that collide with built-in step commands (`commit`, `squash`, `rebase`, etc.) are shadowed by the built-in.
-### Recipe: tail a specific hook log
-
-`wt config state logs --format=json` emits structured entries — `branch`, `source`, `hook_type`, `name`, `path`. Pipe through `jq` to resolve one entry, then wrap in an alias for quick access:
-
-```toml
-[aliases]
-# Tail the current worktree's post-start hook named {{ name }}:
-# wt step hook-log --name=server
-hook-log = '''
-tail -f "$(wt config state logs --format=json | jq -r --arg name "{{ name }}" '
- .hook_output[]
- | select(.branch == "{{ branch }}" and .hook_type == "post-start" and .name == $name)
- | .path
-' | head -1)"
-'''
-```
-
-Hook names that required sanitization (had invalid filename characters) pick up a short hash suffix on disk, e.g. `server-abc` for configured name `server`. The alias matches on the exact on-disk `name`, so pass the sanitized form when filtering those.
-
### Recipe: move or copy in-progress changes to a new worktree
Aliases compose existing commands into richer workflows. These three aliases wrap `wt switch --create` with git's stash and diff plumbing so staged, unstaged, and untracked changes can follow you into a new worktree:
@@ -181,6 +162,25 @@ How they work:
Because an inner `wt switch --create` inside an alias [propagates its `cd` to the parent shell](@/step.md#aliases), all three drop the shell in the new worktree directly.
+### Recipe: tail a specific hook log
+
+`wt config state logs --format=json` emits structured entries — `branch`, `source`, `hook_type`, `name`, `path`. Pipe through `jq` to resolve one entry, then wrap in an alias for quick access:
+
+```toml
+[aliases]
+# Tail the current worktree's post-start hook named {{ name }} (handles sanitization):
+# wt step hook-log --name=feature/auth
+hook-log = '''
+tail -f "$(wt config state logs --format=json | jq -r --arg name "{{ name | sanitize_hash }}" '
+ .hook_output[]
+ | select(.branch == "{{ branch | sanitize_hash }}" and .hook_type == "post-start" and .name == $name)
+ | .path
+' | head -1)"
+'''
+```
+
+The `sanitize_hash` filter produces a filesystem-safe name with a hash suffix that keeps distinct originals unique — the same transformation Worktrunk applies on disk — so the alias resolves the right log even for branch and hook names containing characters like `/`.
+
See [`wt step` — Aliases](@/step.md#aliases) for the full reference.
## External subcommands
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 30341b441..5ab5fc5ec 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -171,9 +171,10 @@ Templates support Jinja2 filters for transforming values:
|--------|---------|-------------|
| `sanitize` | `{{ branch \| sanitize }}` | Replace `/` and `\` with `-` |
| `sanitize_db` | `{{ branch \| sanitize_db }}` | Database-safe identifier with hash suffix (`[a-z0-9_]`, max 63 chars) |
+| `sanitize_hash` | `{{ branch \| sanitize_hash }}` | Filesystem-safe name with hash suffix for uniqueness |
| `hash_port` | `{{ branch \| hash_port }}` | Hash to port 10000-19999 |
-The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `hash_port` filter is useful for running dev servers on unique ports per worktree:
+The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `sanitize_hash` filter produces a filesystem-safe name and appends a 3-character hash suffix when sanitization changed the input, so distinct originals never collide — already-safe names pass through unchanged. The `hash_port` filter is useful for running dev servers on unique ports per worktree:
```toml
[post-start]
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index 72148a877..f6fce7b1b 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -129,25 +129,6 @@ When both user and project config define the same alias name, both run — user
Alias names that collide with built-in step commands (`commit`, `squash`, `rebase`, etc.) are shadowed by the built-in.
-### Recipe: tail a specific hook log
-
-`wt config state logs --format=json` emits structured entries — `branch`, `source`, `hook_type`, `name`, `path`. Pipe through `jq` to resolve one entry, then wrap in an alias for quick access:
-
-```toml
-[aliases]
-# Tail the current worktree's post-start hook named {{ name }}:
-# wt step hook-log --name=server
-hook-log = '''
-tail -f "$(wt config state logs --format=json | jq -r --arg name "{{ name }}" '
- .hook_output[]
- | select(.branch == "{{ branch }}" and .hook_type == "post-start" and .name == $name)
- | .path
-' | head -1)"
-'''
-```
-
-Hook names that required sanitization (had invalid filename characters) pick up a short hash suffix on disk, e.g. `server-abc` for configured name `server`. The alias matches on the exact on-disk `name`, so pass the sanitized form when filtering those.
-
### Recipe: move or copy in-progress changes to a new worktree
Aliases compose existing commands into richer workflows. These three aliases wrap `wt switch --create` with git's stash and diff plumbing so staged, unstaged, and untracked changes can follow you into a new worktree:
@@ -178,6 +159,25 @@ How they work:
Because an inner `wt switch --create` inside an alias [propagates its `cd` to the parent shell](https://worktrunk.dev/step/#aliases), all three drop the shell in the new worktree directly.
+### Recipe: tail a specific hook log
+
+`wt config state logs --format=json` emits structured entries — `branch`, `source`, `hook_type`, `name`, `path`. Pipe through `jq` to resolve one entry, then wrap in an alias for quick access:
+
+```toml
+[aliases]
+# Tail the current worktree's post-start hook named {{ name }} (handles sanitization):
+# wt step hook-log --name=feature/auth
+hook-log = '''
+tail -f "$(wt config state logs --format=json | jq -r --arg name "{{ name | sanitize_hash }}" '
+ .hook_output[]
+ | select(.branch == "{{ branch | sanitize_hash }}" and .hook_type == "post-start" and .name == $name)
+ | .path
+' | head -1)"
+'''
+```
+
+The `sanitize_hash` filter produces a filesystem-safe name with a hash suffix that keeps distinct originals unique — the same transformation Worktrunk applies on disk — so the alias resolves the right log even for branch and hook names containing characters like `/`.
+
See [`wt step` — Aliases](https://worktrunk.dev/step/#aliases) for the full reference.
## External subcommands
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 82dd47021..0a4bc78d4 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -162,9 +162,10 @@ Templates support Jinja2 filters for transforming values:
|--------|---------|-------------|
| `sanitize` | `{{ branch \| sanitize }}` | Replace `/` and `\` with `-` |
| `sanitize_db` | `{{ branch \| sanitize_db }}` | Database-safe identifier with hash suffix (`[a-z0-9_]`, max 63 chars) |
+| `sanitize_hash` | `{{ branch \| sanitize_hash }}` | Filesystem-safe name with hash suffix for uniqueness |
| `hash_port` | `{{ branch \| hash_port }}` | Hash to port 10000-19999 |
-The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `hash_port` filter is useful for running dev servers on unique ports per worktree:
+The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `sanitize_hash` filter produces a filesystem-safe name and appends a 3-character hash suffix when sanitization changed the input, so distinct originals never collide — already-safe names pass through unchanged. The `hash_port` filter is useful for running dev servers on unique ports per worktree:
```toml
[post-start]
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 031927916..f8ef1abbb 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1371,9 +1371,10 @@ Templates support Jinja2 filters for transforming values:
|--------|---------|-------------|
| `sanitize` | `{{ branch \| sanitize }}` | Replace `/` and `\` with `-` |
| `sanitize_db` | `{{ branch \| sanitize_db }}` | Database-safe identifier with hash suffix (`[a-z0-9_]`, max 63 chars) |
+| `sanitize_hash` | `{{ branch \| sanitize_hash }}` | Filesystem-safe name with hash suffix for uniqueness |
| `hash_port` | `{{ branch \| hash_port }}` | Hash to port 10000-19999 |
-The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `hash_port` filter is useful for running dev servers on unique ports per worktree:
+The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `sanitize_hash` filter produces a filesystem-safe name and appends a 3-character hash suffix when sanitization changed the input, so distinct originals never collide — already-safe names pass through unchanged. The `hash_port` filter is useful for running dev servers on unique ports per worktree:
```toml
[post-start]
diff --git a/src/config/expansion.rs b/src/config/expansion.rs
index 7873e6126..0b22b794d 100644
--- a/src/config/expansion.rs
+++ b/src/config/expansion.rs
@@ -323,6 +323,9 @@ fn setup_template_env(repo: &Repository) -> Environment<'static> {
env.add_filter("sanitize_db", |value: Value| -> String {
sanitize_db(value.as_str().unwrap_or_default())
});
+ env.add_filter("sanitize_hash", |value: Value| -> String {
+ crate::path::sanitize_for_filename(value.as_str().unwrap_or_default())
+ });
env.add_filter("hash_port", |value: String| string_to_port(&value));
// Register worktree_path_of_branch function for looking up branch worktree paths.
@@ -424,6 +427,7 @@ pub fn validate_template(
/// # Filters
/// - `sanitize` — Replace `/` and `\` with `-` for filesystem-safe paths
/// - `sanitize_db` — Transform to database-safe identifier (`[a-z0-9_]`, max 63 chars)
+/// - `sanitize_hash` — Filesystem-safe name with hash suffix so distinct inputs never collide
/// - `hash_port` — Hash to deterministic port number (10000-19999)
///
/// # Functions
@@ -1360,6 +1364,7 @@ mod tests {
// Filters
assert!(validate_template("{{ branch | sanitize }}", &test.repo, "test").is_ok());
assert!(validate_template("{{ branch | sanitize_db }}", &test.repo, "test").is_ok());
+ assert!(validate_template("{{ branch | sanitize_hash }}", &test.repo, "test").is_ok());
assert!(validate_template("{{ branch | hash_port }}", &test.repo, "test").is_ok());
// Conditionals with optional vars
diff --git a/src/config/test.rs b/src/config/test.rs
index ee0c25570..52d5d736c 100644
--- a/src/config/test.rs
+++ b/src/config/test.rs
@@ -51,6 +51,50 @@ fn test_expand_template_branch_with_slashes() {
assert_eq!(result, "echo feature-nested-branch");
}
+#[test]
+fn test_expand_template_sanitize_hash_filter() {
+ let test = test_repo();
+
+ // Already-safe names pass through unchanged (no hash suffix)
+ let vars = vars_with_branch("server");
+ let result = expand_template(
+ "{{ branch | sanitize_hash }}",
+ &vars,
+ false,
+ &test.repo,
+ "test",
+ )
+ .unwrap();
+ assert_eq!(result, "server");
+
+ // Unsafe characters are replaced and a 3-char hash suffix is appended
+ let vars = vars_with_branch("feature/auth");
+ let result = expand_template(
+ "{{ branch | sanitize_hash }}",
+ &vars,
+ false,
+ &test.repo,
+ "test",
+ )
+ .unwrap();
+ assert!(result.starts_with("feature-auth-"), "got: {result}");
+ assert_eq!(result.len(), "feature-auth-".len() + 3, "got: {result}");
+
+ // Empty input becomes "_empty-<hash>"
+ let mut vars = HashMap::new();
+ vars.insert("name", "");
+ let result = expand_template(
+ "{{ name | sanitize_hash }}",
+ &vars,
+ false,
+ &test.repo,
+ "test",
+ )
+ .unwrap();
+ assert!(result.starts_with("_empty-"), "got: {result}");
+ assert_eq!(result.len(), "_empty-".len() + 3, "got: {result}");
+}
+
#[test]
fn test_expand_template_branch_raw_with_slashes() {
let test = test_repo();