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.mdindex 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 — userAlias 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 worktreeAliases 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 subcommandsdiff --git a/docs/content/hook.md b/docs/content/hook.mdindex 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.mdindex 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 — userAlias 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 worktreeAliases 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 subcommandsdiff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex 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.rsindex 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.rsindex 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 {// Filtersassert!(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 varsdiff --git a/src/config/test.rs b/src/config/test.rsindex 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();