Skip to content

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

feat(config): add `hash` template filter (#2453)

Worktrunk Bot719a102409c5
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 9f15be1c0..df55f6051 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -184,9 +184,17 @@ 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` | `{{ branch \| hash }}` | 3-character base36 digest of the input |
| `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 `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:
+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` filter is the bare 3-character base36 digest, useful for composing your own truncate-with-collision-avoidance recipes when an output budget is tight (e.g., Unix socket paths capped at 107 bytes):
+
+```toml
+# Truncated branch slug + hash: collisions remain disambiguated even when prefixes match
+worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash }}"
+```
+
+The `hash_port` filter is useful for running dev servers on unique ports per worktree:
```toml
[post-start]
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index bf251c35b..812a3c541 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -175,9 +175,17 @@ 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` | `{{ branch \| hash }}` | 3-character base36 digest of the input |
| `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 `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:
+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` filter is the bare 3-character base36 digest, useful for composing your own truncate-with-collision-avoidance recipes when an output budget is tight (e.g., Unix socket paths capped at 107 bytes):
+
+```toml
+# Truncated branch slug + hash: collisions remain disambiguated even when prefixes match
+worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash }}"
+```
+
+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 6065ffdd9..9f519e094 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1361,9 +1361,17 @@ 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` | `{{ branch \| hash }}` | 3-character base36 digest of the input |
| `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 `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:
+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` filter is the bare 3-character base36 digest, useful for composing your own truncate-with-collision-avoidance recipes when an output budget is tight (e.g., Unix socket paths capped at 107 bytes):
+
+```toml
+# Truncated branch slug + hash: collisions remain disambiguated even when prefixes match
+worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash }}"
+```
+
+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 f2f40e937..996a702d4 100644
--- a/src/config/expansion.rs
+++ b/src/config/expansion.rs
@@ -566,6 +566,9 @@ fn setup_template_env(repo: &Repository) -> Environment<'static> {
env.add_filter("sanitize_hash", |value: Value| -> String {
crate::path::sanitize_for_filename(value.as_str().unwrap_or_default())
});
+ env.add_filter("hash", |value: Value| -> String {
+ short_hash(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.
@@ -703,6 +706,7 @@ pub fn validate_template(
/// - `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` — 3-character base36 hash digest of the input
/// - `hash_port` — Hash to deterministic port number (10000-19999)
///
/// # Functions
@@ -1344,6 +1348,61 @@ mod tests {
}
}
+ #[test]
+ fn test_hash_filter() {
+ let test = test_repo();
+ let mut vars = HashMap::new();
+ vars.insert("branch", "feature/very-long-branch-name");
+
+ // Filter produces a 3-char base36 digest
+ let result =
+ expand_template("{{ branch | hash }}", &vars, false, &test.repo, "test").unwrap();
+ assert_eq!(result.len(), 3);
+ assert!(
+ result
+ .chars()
+ .all(|c| c.is_ascii_digit() || c.is_ascii_lowercase()),
+ "got: {result}"
+ );
+
+ // Deterministic: same input produces same hash across calls
+ let r1 = expand_template("{{ branch | hash }}", &vars, false, &test.repo, "test").unwrap();
+ let r2 = expand_template("{{ branch | hash }}", &vars, false, &test.repo, "test").unwrap();
+ assert_eq!(r1, r2);
+
+ // Composable: hash reflects the upstream filter's output
+ vars.insert("branch", "feature/auth");
+ let raw = expand_template("{{ branch | hash }}", &vars, false, &test.repo, "test").unwrap();
+ let sanitized = expand_template(
+ "{{ branch | sanitize | hash }}",
+ &vars,
+ false,
+ &test.repo,
+ "test",
+ )
+ .unwrap();
+ // `sanitize` rewrites `/` to `-`, so the hashed input differs and the digest does too.
+ assert_ne!(raw, sanitized);
+
+ // User-composed truncation + hash recipe (from extending docs)
+ let truncated = expand_template(
+ "{{ (branch | sanitize)[:8] }}_{{ branch | sanitize | hash }}",
+ &vars,
+ false,
+ &test.repo,
+ "test",
+ )
+ .unwrap();
+ assert!(truncated.starts_with("feature-"), "got: {truncated}");
+ assert_eq!(truncated.len(), 8 + 1 + 3);
+
+ // Empty input: still produces a 3-char digest (empty-string hash is stable)
+ vars.insert("branch", "");
+ let empty =
+ expand_template("{{ branch | hash }}", &vars, false, &test.repo, "test").unwrap();
+ assert_eq!(empty.len(), 3);
+ }
+
#[test]
fn test_hash_port_filter() {
let test = test_repo();
@@ -1751,6 +1810,7 @@ mod tests {
assert!(
validate_template("{{ branch | sanitize_hash }}", hook, &test.repo, "test").is_ok()
);
+ assert!(validate_template("{{ branch | hash }}", hook, &test.repo, "test").is_ok());
assert!(validate_template("{{ branch | hash_port }}", hook, &test.repo, "test").is_ok());
// Conditionals with optional vars