Sorting support for `wt list`

[everag]

Feature Request: Configurable row sorting for wt list

Summary

Allow configuring the sort order of rows displayed by wt list.

The list.columns configuration already provides control over which columns are displayed and their order. It would be useful to have equivalent control over the ordering of the rows.

Motivation

I use a custom wt list layout with the worktree path displayed before the branch:

[list]
columns = ["path", "branch", "status", ...]

For this layout, I'd also like the rows to be sorted by path, so that the listing corresponds naturally to the physical organization of my worktrees.

Currently, the row ordering appears to be determined internally, with no configuration option to change it.

Proposed configuration

Something along the lines of:

[list]
columns = ["path", "branch", "status", ...]
sort = ["path"]

Potentially supporting multiple sort keys:

[list]
sort = ["path", "branch"]

And optionally descending order:

[list]
sort = [
  { column = "path", order = "asc" },
  { column = "age", order = "desc" },
]

The exact syntax is up to the implementation; the important part is allowing users to choose the primary (and optionally secondary) sort columns.

Use case

For example, with:

~/repo
~/repo.feature-a
~/repo.feature-b
~/repo.fix-c

I'd like wt list to display those worktrees in path order while retaining the normal table rendering and all of the existing status information.

This would be particularly useful now that list.columns supports customizable column selection and ordering.

[worktrunk-bot]

Thanks for the suggestion — there's no [list] sort key today. Row order is fixed in sort_worktrees_with_cache: current worktree first, primary worktree second, then committer date descending; branch-only and remote rows are committer date descending. The ListConfig struct is where a sort field would slot in, next to columns.

Two things worth knowing before the syntax gets settled, since they'd shape it:

Sorting by path is cheaper than the current default, not more expensive. The committer date is the reason the batched git log commit-details fork sits on the critical path — the module docstring calls this out explicitly: "%ct — sort order on the skeleton. This is why #6 is pre-skeleton; the skeleton can't pick row order without it." path and branch come straight off git worktree list --porcelain, so a config that sorts on either could in principle let the skeleton paint before that fork returns.

But most columns aren't sortable at skeleton time. path, branch, commit, age, and message are known pre-skeleton; status, working-diff, ahead-behind, branch-diff, upstream, ci, summary, url, and custom columns stream in afterwards and update cells in place. Sorting on one of those means either blocking the skeleton on data that may be a network round-trip away (ci), or reordering rows mid-render — which the progressive table doesn't do today. So a first cut restricted to the pre-skeleton keys is a much smaller change than one that accepts any column name, and it's worth deciding up front which shape sort is promising.

One design question that falls out: [list] config is shared with the wt switch picker — both go through the same collect::collect. In the picker the "current first, primary second" prefix is navigational rather than presentational, so whether a user sort replaces that prefix or only orders the rows below it is a call someone has to make rather than a detail that falls out of the implementation.

No table-preserving workaround exists in the meantime — wt list --format=json | jq will sort by any field but gives up the rendering and the status columns, which is exactly what you said you wanted to keep.

For precedent, list.columns came out of #3133, so this is the natural follow-on ask. I'll leave it for a maintainer to evaluate and prioritize.

[max-sixty]

seems reasonable! please go ahead @worktrunk-bot . as you say, only for the cols available at skeleton time

[worktrunk-bot]

Opened #3933. [list] sort takes column names, most significant first, with a - prefix for descending — so your case is:

[list]
columns = ["path", "branch", "status"]
sort = ["path"]

Sortable keys are the skeleton-time columns only, per the scoping above: branch, path, commit, age, message. Naming a streamed column (status, ci, upstream, the diff columns) is an error that says why rather than a silently ignored setting.

Two calls worth flagging, since they weren't settled on this thread:

• A spec replaces the default order outright, pinned prefix included. Keeping the current and primary worktrees at the top would defeat the point of sort = ["path"], so they sort with everything else. Newest-commit-first stays as the final tiebreak, which is what keeps branch-only rows (no path) in the order they have today.
• --format json follows sort, unlike columns. Reordering an array neither narrows the payload nor adds a forge call, so neither reason for excluding columns applies.

Rows still sort within their group — worktrees, then --branches, then --remotes — never across.

[max-sixty]

Can I ask: how useful is this _if we can only sort by the available columns in #3933 _

I worry that it would almost never be used; the only potentially useful one would be path, and requires quite specific path constructions to be useful...

[worktrunk-bot]

Your worry is right, and it's sharper than stated: path is the key that's redundant, not the one that saves the feature.

The worktree-path template's per-worktree variable set is just branch. format_path binds main_worktree, repo, repo_path, owner, and remote_repo — all constant within a repo — plus branch. So whatever template a user writes, path order is branch order, differing only where sanitize's /→- flips two adjacent names. The reporter's example listing is the default template rendering exactly that: ~/repo first (the primary worktree isn't at a template path, and repo prefixes repo.), then the rest alphabetical by sanitized branch.

That collapses the five sortable keys to about one real one. path ≡ branch. commit and message sort on a hash and a subject line — no use case. -age (oldest first, for spotting stale worktrees) is the only other one with a story, and it's weak next to just reading the age column. What's left is branch: alphabetical instead of recency, which is the entire ask once you strip the path framing off it.

If that residue is worth shipping, it's one setting rather than a spec language — something like [list] order = "recent" | "alphabetical", default recent, with the current-then-primary prefix left pinned. That's a fraction of the surface: no - prefix, no per-key validation errors, no sortable-vs-streamed-column concept to document, no --format json question. It also avoids a cost of the reverted design I under-weighted — dropping the pinned prefix moved the current worktree off row 0, which is what the picker's speculative preview warm-up primes against.

Whether even that clears the bar is your call; the deciding input is @everag's — is the need "alphabetical rather than recency" (which order covers), or something about paths specifically that I've missed? The one thing not shipping costs is that there's still no table-preserving workaround: --format json | jq reorders anything but gives up the rendering and the status columns.

Happy to implement the one-key version if you want it, or to leave this closed as not-planned.

Why path order can't diverge from branch order

The three templates in the config docs all place a constant prefix in front of {{ branch }} or {{ branch | sanitize }}, so each is order-preserving over branch names. Simulating the default against a mixed branch set:

branches   : main, feature/auth, feature-b, fix-c, zz/aa
by branch  : feature-b, feature/auth, fix-c, main, zz/aa
by path    : main, feature/auth, feature-b, fix-c, zz/aa
paths      : myrepo, myrepo.feature-auth, myrepo.feature-b, myrepo.fix-c, myrepo.zz-aa

The two orders differ only in the primary worktree's position (which the current default already pins to the top) and in feature-b vs feature/auth (the /→- substitution in sanitize_branch_name).

A worktree created by hand at an arbitrary path (git worktree add ~/scratch/foo) is the one case that escapes this, since wt didn't pick its path. That's narrow enough not to carry a config key.

Residual argument for alphabetical that isn't about paths at all: recency order is unstable under commits — committing in a worktree moves its row to the top and shifts everything beneath it, so positions in the picker don't hold still between invocations. Alphabetical does. That's an argument for the ordering, not for sort keys.