[Feature Request] specify custom worktree directory name independent of branch name

[christowiz]

Problem

When creating a new worktree with wt switch --create, the worktree directory name is always derived from the branch name. For branches using / separators (e.g. feature/JIRA-1234), the slash is sanitized to a dash, giving a directory like feature-JIRA-1234. There is no way to specify a different directory name on the command line.

Example:

• wt switch --create feature/JIRA-1234 → directory feature-JIRA-1234, branch feature/JIRA-1234

If I want the directory to be named something descriptive like navigation-animation-refactor while the branch is feature/JIRA-1234, there's currently no way to do this.

Desired behavior

An option (e.g. --path or --name) that lets you specify the worktree directory path independently of the branch name:

wt switch --create feature/JIRA-1234 --path navigation-animation-refactor

This would create a branch called feature/JIRA-1234 with the worktree at a directory called navigation-animation-refactor — exactly what git worktree add already supports:

git worktree add -b feature/JIRA-1234 ../navigation-animation-refactor
# or
git worktree add ../navigation-animation-refactor feature/JIRA-1234

Workaround

Today the only workaround is to drop down to git worktree add directly, which bypasses all of worktrunk's hooks, path templating, and shell integration.

Notes

• The worktree-path config template controls the base path but not the per-invocation leaf name
• Related: feature request: Need branch prefix #1494 (branch prefix), Rename a branch/worktree folder #1451 (rename after creation)

[worktrunk-bot]

Thanks for the suggestion! I searched the codebase and confirmed there's no existing flag to override the worktree directory name per-invocation on wt switch --create.

The closest related functionality is the worktree-path template in your config, which supports a replace filter for common patterns. For example, if your branches are always feature/JIRA-1234, you could strip the prefix:

[project]
worktree-path = "{{ repo_path }}/../{{ repo }}.{{ branch | replace('feature/', '') | sanitize }}"

That would give you repo.JIRA-1234 instead of repo.feature-JIRA-1234 — but it's a global rule, not a per-invocation override, so it doesn't address the core request (choosing an arbitrary descriptive name like navigation-animation-refactor at creation time).

I'll leave it for a maintainer to evaluate and prioritize.

[max-sixty]

A core part of Worktrunk is making a reliable mapping between branches and worktrees. So the bar would be extremely high for us to offer a way to deviate from that.

(wt step promote is one (the only?) example of us doing that)

probably the best way would be to make an alias which ran git worktree move with a vars. @worktrunk-bot could you give an example / options of what that would look like?

and then, as ever — if something catches on, then we can consider how to update worktrunk towards it

[worktrunk-bot]

Here are a couple of options:

Option 1: wt step alias (simplest)

# ~/.config/worktrunk/config.toml
[aliases]
rename = "git worktree move {{ worktree_path }} {{ repo_path }}/../{{ repo }}.{{ name }}"

Usage:

wt switch --create feature/JIRA-1234
wt step rename --var name=navigation-animation-refactor
cd ../myrepo.navigation-animation-refactor   # shell needs to follow the move

The {{ repo_path }}/../{{ repo }}.{{ name }} pattern mirrors the default worktree-path template, just with a custom leaf name instead of the sanitized branch. If you've customized worktree-path, the alias template should match your pattern.

Downside: After git worktree move, the current shell is still in the old (now-gone) directory, so you need a manual cd. The shell integration can't intercept this since the move happens inside the alias command.

Option 2: Shell function (handles the cd)

# In .zshrc / .bashrc
wt-rename() {
  local new_name="$1"
  local old_path="$(pwd)"
  local new_path="$(dirname "$old_path")/$new_name"
  git worktree move "$old_path" "$new_path" && cd "$new_path"
}

Usage:

wt switch --create feature/JIRA-1234
wt-rename navigation-animation-refactor

This one handles the cd automatically since it's a shell function. Doesn't use wt template variables, but it doesn't need to — it just moves wherever you currently are.

---

I'd lean toward Option 2 for ergonomics — the cd issue with Option 1 adds friction. Option 1 is nice if you want the rename path to follow your worktree-path template pattern though.

[max-sixty]

ok. I think we could combine these two into an alias:

wt switch --create feature/JIRA-1234
wt step rename --var name=navigation-animation-refactor

...but fair point on the cd; that does somewhat require a shell function

[worktrunk-bot]

Yeah — the alias is cleaner for discoverability but the shell function is the only way to get the cd for free. If a pattern emerges from users doing this, a native wt move or wt rename command could handle the shell integration the same way wt switch does (via the shell wrapper).

[christowiz]

I guess this is a "me" problem ;)

The main argument for me is that I can organize my context as I see fit and Git natively already supports this behavior. To use only branch prefixes and issue numbers would result in a list of worktrees and directories like the following:

feature-JIRA-1234
feature-JIRA-2242
feature-JIRA-2664
...

There is a simple workaround which is to adjust my workflow start adding my custom context to the branch names:

feature-JIRA-1234-custom-context
feature-JIRA-2242-add-cool-system-fix
feature-JIRA-2664-change-some-behavior
...

It is additional noise unfortunately

[max-sixty]

I guess this is a "me" problem ;)

ha, totally understandable, and I empathize. I do think that part of the role of Worktrunk is to set some norms so coordination becomes easier, even if that makes some existing workflows a bit harder

I'm genuine in suggesting trying to build something outside the norms, and then seeing how that goes. Or use vars to set vars on the worktrees and then use the structured data about them; like a jira ticket no.

[endigma]

I would also like it if worktrunk could name the folders something completely irrelevant, like Conductor or Zed's built in worktrees. I personally don't need the branch name in the folder, it's included in my shell's statusline.

Something like {{ word }} and {{ city }} for use within the directory template using datasets similar to Zed/Conductor would be great.