Ability to name/add note for worktrunks

[KieranP]

Our branch names are like this: kieran/XP-1234, or kieran/rollbar-12345, which when looking at them in worktrunk isn't clear what the worktree is for. I can tab between log and changes to try and remember, but it would be cool if there were a rename function that overrode what currently shows up in Message column in switch/list (which defaults to most recent commit message).

wt rename "Add safety checks to User model"

[worktrunk-bot]

Thanks for the suggestion! Good news: worktrunk can already do this today via custom columns (experimental) plus a per-branch value, and a small alias gives you the exact wt <name> "..." ergonomics you sketched — no native rename command needed.

Put this in your user config (~/.config/worktrunk/config.toml):

# A "Note" column that renders a per-branch value...
[list.custom-columns.Note]
template = "{{ vars.note }}"
width = 40

# ...placed where the built-in Message column was.
# `columns` is exhaustive — listing it without "message" replaces Message
# with your Note. (Keep "message" in the list too if you'd rather have both.)
[list]
columns = ["branch", "status", "Note", "commit", "age"]

# The one-liner you wanted: `wt note "Add safety checks to User model"`
[aliases]
note = "wt config state vars set note={{ args }}"

Then, from inside the worktree:

$ wt note "Add safety checks to User model"
✓ Set note for kieran/XP-1234

and wt list / wt switch show your text instead of the commit subject:

  Branch          Status  Note                             Commit    Age
+ kieran/XP-1234  ↑ A     Add safety checks to User model   2219732   now

The value is stored per-branch (in git config under worktrunk.state.<branch>.vars.note), so it sticks across commits and rebases, and an empty column drops itself automatically. I tested the whole recipe above — the alias handles multi-word notes and special characters fine.

A couple of alternatives depending on your setup:

• wt config state marker set "..." is a built-in one-command way to tag a branch, but it renders in the (narrow) Status column, so it's really meant for short tags/emoji (🚧, ✅ ready) — a full sentence gets truncated to A…. Fine as a status flag, not as a replacement for Message.
• If you already keep a branch description via git branch --edit-description, use template = "{{ git.branch.description | lines | first }}" instead of {{ vars.note }} — worktrunk reads the git-native branch.<name>.description directly, so you'd skip the alias entirely.

Background & the genuine gap

The {{ git.branch.* }} custom-column namespace shipped from a very similar request in #3258 (surfacing per-branch git-config values in wt list).

What genuinely doesn't exist yet is a native way to override the built-in Message column's value in place, or a first-class wt rename/wt note command — the recipe above replaces Message with a custom column and leans on an alias for the verb. worktrunk deliberately keeps its native flag/config surface small and treats a wt alias as the standing extension point for workflow-specific verbs like this, so an alias is likely the intended answer rather than a new command. Whether a native command is worth adding is a maintainer call.

Docs: custom columns, aliases, tips & patterns.

I'll leave it to a maintainer to weigh whether a native command is worth adding — the alias should get you what you're after in the meantime.

[KieranP]

I'm trying to set this in the project specific confif (.config/wt.toml), but am getting the following error:

▲ Project config has unknown field list.columns (will be ignored)
▲ Project config has unknown field list.custom-columns (will be ignored)
▲ Project config has unknown field list.columns (will be ignored)
▲ Project config has unknown field list.custom-columns (will be ignored

Does this have to be in the global config?

[worktrunk-bot]

Yes — that's expected. The column layout settings ([list] columns and [list.custom-columns]) are user config only, so they belong in ~/.config/worktrunk/config.toml, not the checked-in project file (.config/wt.toml). The project config's [list] section only accepts url (the dev-server column), which is why you're seeing unknown field list.columns / list.custom-columns. Column layout is treated as a personal display preference rather than a team-shared setting, so it isn't part of the project schema.

The [aliases] half of the recipe (note = ...) does work in project config if you want to share the verb with teammates — only the two [list] pieces need to move to user config.

If you want it scoped to just this repo

You don't have to make it fully global. User config has a [projects."<id>"] table for per-project overrides — settings that live in your personal config but only apply to one repo. The <id> is your remote in host/owner/repo form (e.g. github.com/KieranP/myrepo, no .git):

[projects."github.com/KieranP/myrepo".list]
columns = ["branch", "status", "Note", "commit", "age"]

[projects."github.com/KieranP/myrepo".list.custom-columns.Note]
template = "{{ vars.note }}"
width = 40

That keeps the Note column on this repo only, without changing wt list in your other projects. The note alias can stay in either file.

Docs: user project-specific settings, project configuration.

[max-sixty]

@worktrunk-bot add a note in the warning when a config only exists in the other config file please. when it's user-config only, add a reference to project-specific-user-config.

[worktrunk-bot]

Opened #3473 for this. It generalizes the misplaced-key detection so a nested key valid only in the other config (like @KieranP's list.columns/list.custom-columns in project config) now reports belongs in user config instead of a bare unknown field, and — when the destination is user config — appends a note pointing at the [projects."<id>"] table for scoping the setting to one repo.