Skip to content

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

feat(list): add `[list] columns` to select and order built-in columns (#3141)

Maximilian Roos0fc757f08d08
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 0d877ab28..db7f41a17 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -99,9 +99,37 @@
# branches = false # Include branches without worktrees (--branches)
# remotes = false # Include remote-only branches (--remotes)
#
+# columns = ["branch", "status", "ci", "path"] # Columns to show, in order — built-ins or custom headers (omit for the default set)
+#
# task-timeout-ms = 0 # Kill individual git commands after N ms; 0 disables
# timeout-ms = 0 # Wall-clock budget for the entire collect phase; 0 disables
#
+# `columns` selects and orders the columns to render; omit it for the default set.
+# It is designed to be driven by an alias (https://worktrunk.dev/extending/#aliases) that sets it
+# per invocation — a body like `wt --config-set 'list.columns=[…]' list` gives a
+# named view (run as `wt <alias>`) without disturbing the default `wt list`.
+# Setting it statically in the config file uses the same key and works, but is not
+# the intended use: it pins one layout over a table that otherwise adapts to
+# `--full` and terminal width.
+#
+# Valid built-in names are `branch`, `status`, `working-diff`, `ahead-behind`,
+# `branch-diff`, `summary`, `upstream`, `ci`, `path`, `url`, `commit`, `age`, and
+# `message`. A custom column (#custom-columns) is named by its `[list.custom-columns]`
+# header, so a selection mixes built-ins and custom columns in one ordered list
+# (`columns = ["branch", "Ticket", "ci"]`). When `columns` is set it is exhaustive
+# — only the listed columns render, so a custom column omitted from a non-empty
+# list is hidden (omit `columns` entirely to keep the default set, where custom
+# columns append automatically). A built-in name wins over a custom header that
+# collides with it. The gutter type indicator always shows.
+#
+# Listing a column requests it but does not force it on: a column gated off
+# elsewhere stays hidden — `ci` needs `--full`, `summary` needs
+# `[commit.generation]` — so `columns` only narrows which columns may appear.
+#
+# The selection drives the rendered table and the `wt switch` picker.
+# `wt list --format json` ignores it, always emitting every field, built-in and
+# custom.
+#
# #### Custom columns [experimental]
#
# Custom columns add per-branch context to the `wt list` table. Each
diff --git a/docs/content/config.md b/docs/content/config.md
index 3df6e2060..024391213 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -186,10 +186,38 @@ full = false # Show CI, main…± diffstat, and LLM summaries (--full)
branches = false # Include branches without worktrees (--branches)
remotes = false # Include remote-only branches (--remotes)
+columns = ["branch", "status", "ci", "path"] # Columns to show, in order — built-ins or custom headers (omit for the default set)
+
task-timeout-ms = 0 # Kill individual git commands after N ms; 0 disables
timeout-ms = 0 # Wall-clock budget for the entire collect phase; 0 disables
```
+`columns` selects and orders the columns to render; omit it for the default set.
+It is designed to be driven by an [alias](@/extending.md#aliases) that sets it
+per invocation — a body like `wt --config-set 'list.columns=[…]' list` gives a
+named view (run as `wt <alias>`) without disturbing the default `wt list`.
+Setting it statically in the config file uses the same key and works, but is not
+the intended use: it pins one layout over a table that otherwise adapts to
+`--full` and terminal width.
+
+Valid built-in names are `branch`, `status`, `working-diff`, `ahead-behind`,
+`branch-diff`, `summary`, `upstream`, `ci`, `path`, `url`, `commit`, `age`, and
+`message`. A [custom column](#custom-columns) is named by its `[list.custom-columns]`
+header, so a selection mixes built-ins and custom columns in one ordered list
+(`columns = ["branch", "Ticket", "ci"]`). When `columns` is set it is exhaustive
+— only the listed columns render, so a custom column omitted from a non-empty
+list is hidden (omit `columns` entirely to keep the default set, where custom
+columns append automatically). A built-in name wins over a custom header that
+collides with it. The gutter type indicator always shows.
+
+Listing a column requests it but does not force it on: a column gated off
+elsewhere stays hidden — `ci` needs `--full`, `summary` needs
+`[commit.generation]` — so `columns` only narrows which columns may appear.
+
+The selection drives the rendered table and the `wt switch` picker.
+`wt list --format json` ignores it, always emitting every field, built-in and
+custom.
+
#### Custom columns
<span class="badge-experimental"></span>
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 3b377ba24..5f60aa042 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -185,10 +185,38 @@ full = false # Show CI, main…± diffstat, and LLM summaries (--full)
branches = false # Include branches without worktrees (--branches)
remotes = false # Include remote-only branches (--remotes)
+columns = ["branch", "status", "ci", "path"] # Columns to show, in order — built-ins or custom headers (omit for the default set)
+
task-timeout-ms = 0 # Kill individual git commands after N ms; 0 disables
timeout-ms = 0 # Wall-clock budget for the entire collect phase; 0 disables
```
+`columns` selects and orders the columns to render; omit it for the default set.
+It is designed to be driven by an [alias](https://worktrunk.dev/extending/#aliases) that sets it
+per invocation — a body like `wt --config-set 'list.columns=[…]' list` gives a
+named view (run as `wt <alias>`) without disturbing the default `wt list`.
+Setting it statically in the config file uses the same key and works, but is not
+the intended use: it pins one layout over a table that otherwise adapts to
+`--full` and terminal width.
+
+Valid built-in names are `branch`, `status`, `working-diff`, `ahead-behind`,
+`branch-diff`, `summary`, `upstream`, `ci`, `path`, `url`, `commit`, `age`, and
+`message`. A [custom column](#custom-columns) is named by its `[list.custom-columns]`
+header, so a selection mixes built-ins and custom columns in one ordered list
+(`columns = ["branch", "Ticket", "ci"]`). When `columns` is set it is exhaustive
+— only the listed columns render, so a custom column omitted from a non-empty
+list is hidden (omit `columns` entirely to keep the default set, where custom
+columns append automatically). A built-in name wins over a custom header that
+collides with it. The gutter type indicator always shows.
+
+Listing a column requests it but does not force it on: a column gated off
+elsewhere stays hidden — `ci` needs `--full`, `summary` needs
+`[commit.generation]` — so `columns` only narrows which columns may appear.
+
+The selection drives the rendered table and the `wt switch` picker.
+`wt list --format json` ignores it, always emitting every field, built-in and
+custom.
+
#### Custom columns [experimental]
Custom columns add per-branch context to the `wt list` table. Each
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 680758629..f3ffddf13 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1879,10 +1879,38 @@ full = false # Show CI, main…± diffstat, and LLM summaries (--full)
branches = false # Include branches without worktrees (--branches)
remotes = false # Include remote-only branches (--remotes)
+columns = ["branch", "status", "ci", "path"] # Columns to show, in order — built-ins or custom headers (omit for the default set)
+
task-timeout-ms = 0 # Kill individual git commands after N ms; 0 disables
timeout-ms = 0 # Wall-clock budget for the entire collect phase; 0 disables
```
+`columns` selects and orders the columns to render; omit it for the default set.
+It is designed to be driven by an [alias](@/extending.md#aliases) that sets it
+per invocation — a body like `wt --config-set 'list.columns=[…]' list` gives a
+named view (run as `wt <alias>`) without disturbing the default `wt list`.
+Setting it statically in the config file uses the same key and works, but is not
+the intended use: it pins one layout over a table that otherwise adapts to
+`--full` and terminal width.
+
+Valid built-in names are `branch`, `status`, `working-diff`, `ahead-behind`,
+`branch-diff`, `summary`, `upstream`, `ci`, `path`, `url`, `commit`, `age`, and
+`message`. A [custom column](#custom-columns) is named by its `[list.custom-columns]`
+header, so a selection mixes built-ins and custom columns in one ordered list
+(`columns = ["branch", "Ticket", "ci"]`). When `columns` is set it is exhaustive
+— only the listed columns render, so a custom column omitted from a non-empty
+list is hidden (omit `columns` entirely to keep the default set, where custom
+columns append automatically). A built-in name wins over a custom header that
+collides with it. The gutter type indicator always shows.
+
+Listing a column requests it but does not force it on: a column gated off
+elsewhere stays hidden — `ci` needs `--full`, `summary` needs
+`[commit.generation]` — so `columns` only narrows which columns may appear.
+
+The selection drives the rendered table and the `wt switch` picker.
+`wt list --format json` ignores it, always emitting every field, built-in and
+custom.
+
#### Custom columns [experimental]
Custom columns add per-branch context to the `wt list` table. Each
diff --git a/src/commands/list/collect/mod.rs b/src/commands/list/collect/mod.rs
index 847e3f92b..db212d22d 100644
--- a/src/commands/list/collect/mod.rs
+++ b/src/commands/list/collect/mod.rs
@@ -1120,6 +1120,23 @@ pub fn collect(
);
}
+ // `[list] columns` selects/reorders the columns to render. Names address
+ // built-ins or custom columns (by header → resolved index), so the custom
+ // names are passed in resolution order. Like custom columns, a bad name
+ // aborts `wt list` but only degrades the picker (which can't surface an
+ // abort mid-render), so the same `progressive_handler` fork applies. An
+ // empty selection means "use the default column set".
+ let custom_names: Vec<&str> = custom_columns.iter().map(|c| c.name.as_str()).collect();
+ let selected_columns =
+ match super::columns::parse_selected_columns(&config.list.columns, &custom_names) {
+ Ok(columns) => columns,
+ Err(e) if progressive_handler.is_some() => {
+ emit_warning(warning_message(format!("Column selection ignored: {e}")).to_string());
+ Vec::new()
+ }
+ Err(e) => return Err(e),
+ };
+
// The picker skips the networked CiStatus task, but cached statuses are
// local data: fill rows from `.git/wt/cache/ci-status/` so PR/MR numbers
// appear in the picker without touching the wire. The CI column is
@@ -1156,7 +1173,10 @@ pub fn collect(
&main_worktree.path,
url_template.as_deref(),
max_pr_number,
- &custom_columns,
+ super::layout::ColumnSelection {
+ custom: &custom_columns,
+ selected: (!selected_columns.is_empty()).then_some(selected_columns.as_slice()),
+ },
);
// Single-line invariant: with no detectable width, an unlimited width
@@ -2296,7 +2316,10 @@ mod tests {
Path::new("/tmp"),
None,
None,
- &[],
+ super::super::layout::ColumnSelection {
+ custom: &[],
+ selected: None,
+ },
);
let placeholder = super::super::render::PLACEHOLDER;
diff --git a/src/commands/list/columns.rs b/src/commands/list/columns.rs
index f00d6056d..0a56d0aae 100644
--- a/src/commands/list/columns.rs
+++ b/src/commands/list/columns.rs
@@ -58,6 +58,107 @@ impl ColumnKind {
.map(|spec| spec.base_priority)
.unwrap_or(u8::MAX)
}
+
+ /// Canonical kebab identifier for the `[list] columns` selection list.
+ ///
+ /// `None` for [`ColumnKind::Gutter`] (the worktree-type indicator, always
+ /// shown and not user-selectable) and [`ColumnKind::Custom`] (addressed by
+ /// its `[list.custom-columns]` header, not a static name). The exhaustive
+ /// match forces every new variant to declare a name or opt out, and
+ /// `test_config_name_round_trips` guards that the names stay unique and
+ /// parseable.
+ pub fn config_name(self) -> Option<&'static str> {
+ Some(match self {
+ ColumnKind::Gutter => return None,
+ ColumnKind::Branch => "branch",
+ ColumnKind::Status => "status",
+ ColumnKind::WorkingDiff => "working-diff",
+ ColumnKind::AheadBehind => "ahead-behind",
+ ColumnKind::BranchDiff => "branch-diff",
+ ColumnKind::Summary => "summary",
+ ColumnKind::Upstream => "upstream",
+ ColumnKind::CiStatus => "ci",
+ ColumnKind::Path => "path",
+ ColumnKind::Url => "url",
+ ColumnKind::Commit => "commit",
+ ColumnKind::Time => "age",
+ ColumnKind::Message => "message",
+ ColumnKind::Custom(_) => return None,
+ })
+ }
+
+ /// Resolve a kebab name from `[list] columns` to its built-in column.
+ ///
+ /// Only built-ins registered in [`COLUMN_SPECS`] are selectable; Gutter
+ /// (no name) and custom columns are unreachable here.
+ pub fn from_config_name(name: &str) -> Option<ColumnKind> {
+ COLUMN_SPECS
+ .iter()
+ .map(|spec| spec.kind)
+ .find(|kind| kind.config_name() == Some(name))
+ }
+
+ /// All selectable column names in display order, for error messages and docs.
+ pub fn selectable_names() -> Vec<&'static str> {
+ COLUMN_SPECS
+ .iter()
+ .filter_map(|spec| spec.kind.config_name())
+ .collect()
+ }
+}
+
+/// Parse the `[list] columns` selection into an ordered list of columns.
+///
+/// Each name resolves to a built-in column (by its kebab
+/// [`ColumnKind::config_name`]) or, failing that, to a custom column by its
+/// `[list.custom-columns]` header. `custom_names` lists the resolved custom
+/// headers in display order, so the matched position becomes
+/// [`ColumnKind::Custom`]`(i)` — callers must pass the same order the resolved
+/// custom columns use, since that index addresses them downstream. Built-ins
+/// win on a name collision: a custom column whose header equals a built-in name
+/// (e.g. `branch`) is shadowed and unreachable here.
+///
+/// An empty input yields an empty selection (the caller treats that as "use the
+/// default column set"). Unknown names and duplicates are hard errors so a typo
+/// can't silently render a different table; the error lists every valid name.
+/// Like `[list.custom-columns]`, this is validated at the `wt list` edge rather
+/// than at config load — `ColumnKind` lives in the command layer, out of reach
+/// of the config crate.
+pub fn parse_selected_columns(
+ names: &[String],
+ custom_names: &[&str],
+) -> anyhow::Result<Vec<ColumnKind>> {
+ let mut selected = Vec::with_capacity(names.len());
+ for name in names {
+ let kind = resolve_column_name(name, custom_names).ok_or_else(|| {
+ let mut valid = ColumnKind::selectable_names().join(", ");
+ if !custom_names.is_empty() {
+ valid.push_str("; custom columns: ");
+ valid.push_str(&custom_names.join(", "));
+ }
+ anyhow::anyhow!("Unknown column {name:?} in [list] columns. Valid columns: {valid}")
+ })?;
+ if selected.contains(&kind) {
+ anyhow::bail!("Duplicate column {name:?} in [list] columns");
+ }
+ selected.push(kind);
+ }
+ Ok(selected)
+}
+
+/// Resolve one `[list] columns` name to a built-in or custom column.
+///
+/// Built-ins take precedence, so a custom header colliding with a built-in name
+/// is shadowed. The custom index is the name's position in `custom_names`, which
+/// mirrors the resolved custom-column order.
+fn resolve_column_name(name: &str, custom_names: &[&str]) -> Option<ColumnKind> {
+ if let Some(kind) = ColumnKind::from_config_name(name) {
+ return Some(kind);
+ }
+ custom_names
+ .iter()
+ .position(|custom| *custom == name)
+ .map(|i| ColumnKind::Custom(i as u8))
}
/// Differentiates between diff-style columns with plus/minus symbols and those with arrows.
@@ -274,4 +375,106 @@ mod tests {
assert!(first < second, "custom columns keep resolution order");
assert!(second < commit, "custom columns render before Commit");
}
+
+ #[test]
+ fn test_config_name_round_trips() {
+ // Drives off COLUMN_SPECS (single source of truth): every registered
+ // built-in either has a unique, parseable name or is Gutter. A new
+ // variant added to COLUMN_SPECS without a config_name arm fails the
+ // exhaustive match in config_name() at compile time; one set to None
+ // (other than Gutter) or colliding with another name fails here.
+ for spec in COLUMN_SPECS {
+ let kind = spec.kind;
+ match kind.config_name() {
+ Some(name) => assert_eq!(
+ ColumnKind::from_config_name(name),
+ Some(kind),
+ "{kind:?} name {name:?} must round-trip (unique + parseable)"
+ ),
+ None => assert_eq!(
+ kind,
+ ColumnKind::Gutter,
+ "only Gutter may lack a config_name; {kind:?} is missing one"
+ ),
+ }
+ }
+ // Custom columns are addressed by header, never by a static name.
+ assert_eq!(ColumnKind::Custom(0).config_name(), None);
+ assert_eq!(ColumnKind::from_config_name("gutter"), None);
+ assert_eq!(ColumnKind::from_config_name("nonsense"), None);
+ }
+
+ #[test]
+ fn test_parse_selected_columns() {
+ let selected =
+ parse_selected_columns(&["ci".into(), "branch".into(), "path".into()], &[]).unwrap();
+ assert_eq!(
+ selected,
+ vec![ColumnKind::CiStatus, ColumnKind::Branch, ColumnKind::Path],
+ "selection preserves the configured order"
+ );
+
+ assert!(parse_selected_columns(&[], &[]).unwrap().is_empty());
+
+ let unknown = parse_selected_columns(&["branch".into(), "bogus".into()], &[]).unwrap_err();
+ assert!(unknown.to_string().contains("Unknown column"), "{unknown}");
+ assert!(unknown.to_string().contains("bogus"), "{unknown}");
+ // The error lists valid names so a typo is self-correcting.
+ assert!(unknown.to_string().contains("ci"), "{unknown}");
+
+ let dup = parse_selected_columns(&["branch".into(), "branch".into()], &[]).unwrap_err();
+ assert!(dup.to_string().contains("Duplicate column"), "{dup}");
+
+ // Gutter is structural and not user-selectable.
+ let gutter = parse_selected_columns(&["gutter".into()], &[]).unwrap_err();
+ assert!(gutter.to_string().contains("Unknown column"), "{gutter}");
+
+ // Matching is exact: the rendered header "Branch" is not the kebab name.
+ let cased = parse_selected_columns(&["Branch".into()], &[]).unwrap_err();
+ assert!(cased.to_string().contains("Unknown column"), "{cased}");
+ }
+
+ #[test]
+ fn test_parse_selected_columns_with_custom() {
+ // Custom columns are selectable by header, mixed freely with built-ins,
+ // and resolve to Custom(index) in the resolved custom order.
+ let selected = parse_selected_columns(
+ &[
+ "branch".into(),
+ "Ticket".into(),
+ "ci".into(),
+ "Owner".into(),
+ ],
+ &["Ticket", "Owner"],
+ )
+ .unwrap();
+ assert_eq!(
+ selected,
+ vec![
+ ColumnKind::Branch,
+ ColumnKind::Custom(0),
+ ColumnKind::CiStatus,
+ ColumnKind::Custom(1),
+ ],
+ "custom headers resolve to Custom(index) in resolved order"
+ );
+
+ // A custom header colliding with a built-in name is shadowed by the built-in.
+ let shadowed = parse_selected_columns(&["branch".into()], &["branch"]).unwrap();
+ assert_eq!(
+ shadowed,
+ vec![ColumnKind::Branch],
+ "built-in wins over a same-named custom column"
+ );
+
+ // Selecting the same custom twice errors like any duplicate.
+ let dup =
+ parse_selected_columns(&["Ticket".into(), "Ticket".into()], &["Ticket"]).unwrap_err();
+ assert!(dup.to_string().contains("Duplicate column"), "{dup}");
+
+ // An unknown name lists the configured custom headers so the typo is fixable.
+ let unknown = parse_selected_columns(&["Tickte".into()], &["Ticket"]).unwrap_err();
+ assert!(unknown.to_string().contains("Unknown column"), "{unknown}");
+ assert!(unknown.to_string().contains("Ticket"), "{unknown}");
+ }
}
diff --git a/src/commands/list/layout.rs b/src/commands/list/layout.rs
index 69721ac03..5943954ee 100644
--- a/src/commands/list/layout.rs
+++ b/src/commands/list/layout.rs
@@ -527,6 +527,21 @@ pub struct LayoutConfig {
pub status_position_mask: super::model::PositionMask,
}
+/// The user's column configuration for one render: which columns to show and
+/// the resolved custom columns available to render.
+///
+/// `selected` is `None` for the default column set (every built-in, with custom
+/// columns appended in resolution order). `Some(order)` renders exactly those
+/// columns in that order — `order` may name built-ins *and* custom columns
+/// (`ColumnKind::Custom(i)`, indexing `custom`), and anything not listed is
+/// hidden. `custom` always carries the resolved `[list.custom-columns]` so their
+/// widths and headers are available; `selected` decides which of them render.
+#[derive(Clone, Copy)]
+pub struct ColumnSelection<'a> {
+ pub selected: Option<&'a [ColumnKind]>,
+ pub custom: &'a [ResolvedCustomColumn],
+}
+
#[derive(Clone, Copy)]
struct ColumnCandidate<'a> {
spec: &'a ColumnSpec,
@@ -669,6 +684,27 @@ fn build_estimated_widths(
}
}
+/// Final visual ordering key for a column.
+///
+/// Without a `[list] columns` selection this defers to the static registry
+/// order ([`column_display_index`]). With a selection, the configured order
+/// wins for every column: Gutter pins first, then each selected column — built-in
+/// or custom — follows its position in `order`. The candidate filter drops any
+/// column not in the selection, so the `usize::MAX` sentinel only covers that
+/// unreachable case; `+ 1` runs only on a real position, so it can't overflow.
+fn display_sort_key(kind: ColumnKind, selected: Option<&[ColumnKind]>) -> (usize, usize) {
+ let Some(order) = selected else {
+ return column_display_index(kind);
+ };
+ if kind == ColumnKind::Gutter {
+ return (0, 0);
+ }
+ order
+ .iter()
+ .position(|&k| k == kind)
+ .map_or((usize::MAX, 0), |position| (position + 1, 0))
+}
+
/// Allocate columns using priority-based allocation logic.
///
/// This is the core allocation algorithm used by `calculate_layout_with_width()`
@@ -680,29 +716,50 @@ fn allocate_columns_with_priority(
commit_width: usize,
terminal_width: usize,
main_worktree_path: PathBuf,
- custom_columns: &[ResolvedCustomColumn],
+ columns: ColumnSelection,
) -> LayoutConfig {
+ let ColumnSelection {
+ custom: custom_columns,
+ selected,
+ } = columns;
let spacing = 2;
let mut remaining = terminal_width;
// Custom columns join the candidate pool with their configured priority.
// Width 0 means empty for every row — excluded entirely (values are
- // final, so unlike still-loading built-ins nothing can arrive later).
+ // final, so unlike still-loading built-ins nothing can arrive later). When
+ // `[list] columns` selects a subset, a custom column shows only if it was
+ // named (by header → `Custom(i)`); without a selection every custom joins.
let custom_specs: Vec<ColumnSpec> = custom_columns
.iter()
.enumerate()
.filter(|&(i, _)| metadata.widths.custom.get(i).copied().unwrap_or(0) > 0)
+ .filter(|&(i, _)| match selected {
+ Some(order) => order.contains(&ColumnKind::Custom(i as u8)),
+ None => true,
+ })
.map(|(i, column)| ColumnSpec::new(ColumnKind::Custom(i as u8), column.priority, None))
.collect();
- // Build candidates with priorities
- // Filter out columns whose required task is being skipped
+ // Build candidates with priorities.
+ // - Filter out columns whose required task is being skipped.
+ // - When `[list] columns` selects a subset, keep only the chosen built-ins
+ // (Gutter is structural — always kept). This filters WITHOUT renumbering
+ // base_priority, so the Summary drop loop and EMPTY_PENALTY tiers below
+ // stay correct: the allocator sorts by priority and never indexes by it,
+ // so a sparse retained set just works. Custom columns honor the same
+ // selection (filtered into `custom_specs` above), so a selection lists
+ // built-ins and customs in one ordered set.
let mut candidates: Vec<ColumnCandidate> = COLUMN_SPECS
.iter()
.filter(|spec| {
spec.requires_task
.is_none_or(|task| !skip_tasks.contains(&task))
})
+ .filter(|spec| match selected {
+ Some(order) => spec.kind == ColumnKind::Gutter || order.contains(&spec.kind),
+ None => true,
+ })
.chain(custom_specs.iter())
.map(|spec| ColumnCandidate {
spec,
@@ -864,8 +921,10 @@ fn allocate_columns_with_priority(
max_message_len = message_col.width;
}
- // Sort by display order to maintain correct visual order
- pending.sort_by_key(|col| column_display_index(col.spec.kind));
+ // Sort by display order to maintain correct visual order. With an explicit
+ // `[list] columns` selection the configured order wins (Gutter stays first);
+ // otherwise the static registry order applies.
+ pending.sort_by_key(|col| display_sort_key(col.spec.kind, selected));
// Build final column layouts with positions
let gap = 2;
@@ -954,8 +1013,9 @@ pub fn calculate_layout_with_width(
main_worktree_path: &Path,
url_template: Option<&str>,
max_pr_number: Option<u64>,
- custom_columns: &[ResolvedCustomColumn],
+ columns: ColumnSelection,
) -> LayoutConfig {
+ let custom_columns = columns.custom;
// Calculate actual widths for things we know
// Include branch names from both worktrees and standalone branches
let longest_branch = items
@@ -1023,7 +1083,7 @@ pub fn calculate_layout_with_width(
commit_width,
terminal_width,
main_worktree_path.to_path_buf(),
- custom_columns,
+ columns,
)
}
@@ -1435,7 +1495,10 @@ mod tests {
&main_worktree_path,
None,
None,
- &[],
+ ColumnSelection {
+ custom: &[],
+ selected: None,
+ },
);
assert!(
@@ -1549,7 +1612,10 @@ mod tests {
&main_worktree_path,
None,
None,
- &[],
+ ColumnSelection {
+ custom: &[],
+ selected: None,
+ },
);
assert!(
@@ -1676,7 +1742,10 @@ mod tests {
Path::new("/test"),
None,
None,
- &[],
+ ColumnSelection {
+ custom: &[],
+ selected: None,
+ },
)
}
@@ -1700,6 +1769,208 @@ mod tests {
layout.columns.iter().find(|c| c.kind == kind)
}
+ #[test]
+ fn test_selected_columns_filter_and_reorder() {
+ // Select a subset in a non-default order. At a wide width nothing drops,
+ // so the visible set is exactly Gutter (always) + the selection, in the
+ // configured order (Gutter pinned first) — not the static registry order.
+ let items = vec![make_test_item("feature-branch")];
+ let selected = [ColumnKind::Time, ColumnKind::Branch, ColumnKind::Commit];
+ let layout = calculate_layout_with_width(
+ &items,
+ &full_skip_tasks(),
+ 300,
+ Path::new("/test"),
+ None,
+ None,
+ ColumnSelection {
+ custom: &[],
+ selected: Some(&selected),
+ },
+ );
+
+ let kinds: Vec<ColumnKind> = layout.columns.iter().map(|c| c.kind).collect();
+ assert_eq!(
+ kinds,
+ vec![
+ ColumnKind::Gutter,
+ ColumnKind::Time,
+ ColumnKind::Branch,
+ ColumnKind::Commit
+ ],
+ "only Gutter + selected columns appear, in the configured order"
+ );
+ // Deselected built-ins are absent and don't inflate the hidden count
+ // (they were never candidates).
+ assert!(find_column(&layout, ColumnKind::Status).is_none());
+ assert!(find_column(&layout, ColumnKind::Message).is_none());
+ assert_eq!(layout.hidden_column_count, 0);
+ }
+
+ #[test]
+ fn test_selected_columns_include_and_hide_custom() {
+ // A selection lists built-ins and custom columns in one ordered set: a
+ // named custom renders interleaved at its configured position, while a
+ // custom omitted from a non-empty selection is hidden.
+ let mut item = make_test_item("feature-branch");
+ item.custom_values = vec!["TICKET-1".to_string(), "max".to_string()];
+ let items = vec![item];
+ let custom = [
+ ResolvedCustomColumn {
+ name: "Ticket".to_string(),
+ template: "{{ vars.ticket }}".to_string(),
+ max_width: 40,
+ priority: 9,
+ },
+ ResolvedCustomColumn {
+ name: "Owner".to_string(),
+ template: "{{ vars.owner }}".to_string(),
+ max_width: 40,
+ priority: 9,
+ },
+ ];
+ // Place Ticket (custom 0) between two built-ins; omit Owner (custom 1).
+ let selected = [
+ ColumnKind::Branch,
+ ColumnKind::Custom(0),
+ ColumnKind::Commit,
+ ];
+ let layout = calculate_layout_with_width(
+ &items,
+ &full_skip_tasks(),
+ 300,
+ Path::new("/test"),
+ None,
+ None,
+ ColumnSelection {
+ custom: &custom,
+ selected: Some(&selected),
+ },
+ );
+
+ let kinds: Vec<ColumnKind> = layout.columns.iter().map(|c| c.kind).collect();
+ assert_eq!(
+ kinds,
+ vec![
+ ColumnKind::Gutter,
+ ColumnKind::Branch,
+ ColumnKind::Custom(0),
+ ColumnKind::Commit,
+ ],
+ "a named custom renders interleaved at its configured position"
+ );
+ assert!(
+ find_column(&layout, ColumnKind::Custom(1)).is_none(),
+ "a custom omitted from a non-empty selection is hidden"
+ );
+ }
+
+ #[test]
+ fn test_default_columns_append_custom() {
+ // Without a selection (the default set), every custom column appends in
+ // resolution order — the selection filter only applies when present.
+ let mut item = make_test_item("feature-branch");
+ item.custom_values = vec!["TICKET-1".to_string()];
+ let items = vec![item];
+ let custom = [ResolvedCustomColumn {
+ name: "Ticket".to_string(),
+ template: "{{ vars.ticket }}".to_string(),
+ max_width: 40,
+ priority: 9,
+ }];
+ let layout = calculate_layout_with_width(
+ &items,
+ &full_skip_tasks(),
+ 300,
+ Path::new("/test"),
+ None,
+ None,
+ ColumnSelection {
+ custom: &custom,
+ selected: None,
+ },
+ );
+ assert!(
+ find_column(&layout, ColumnKind::Custom(0)).is_some(),
+ "custom columns append in the default (no-selection) set"
+ );
+ }
+
+ #[test]
+ fn test_selected_columns_cannot_force_a_gated_column() {
+ // Selection narrows the candidate set; it can't force on a column gated
+ // off by skip_tasks. `ci` needs --full: with CiStatus skipped, selecting
+ // it leaves a gutter-only table (the skip_tasks filter runs first).
+ let items = vec![make_test_item("feature-branch")];
+ let selected = [ColumnKind::CiStatus];
+ let gated = calculate_layout_with_width(
+ &items,
+ &non_full_skip_tasks(),
+ 200,
+ Path::new("/test"),
+ None,
+ None,
+ ColumnSelection {
+ custom: &[],
+ selected: Some(&selected),
+ },
+ );
+ assert!(
+ find_column(&gated, ColumnKind::CiStatus).is_none(),
+ "a gated column stays hidden even when selected"
+ );
+ let kinds: Vec<ColumnKind> = gated.columns.iter().map(|c| c.kind).collect();
+ assert_eq!(kinds, vec![ColumnKind::Gutter], "only the gutter survives");
+
+ // Once the gate opens (full mode, nothing skipped), the same selection
+ // renders CI.
+ let full = calculate_layout_with_width(
+ &items,
+ &full_skip_tasks(),
+ 200,
+ Path::new("/test"),
+ None,
+ None,
+ ColumnSelection {
+ custom: &[],
+ selected: Some(&selected),
+ },
+ );
+ assert!(
+ find_column(&full, ColumnKind::CiStatus).is_some(),
+ "the selected column renders once its task is no longer skipped"
+ );
+ }
+
+ #[test]
+ fn test_selected_columns_drop_by_base_priority() {
+ // Selection controls membership/order, not drop priority: on a narrow
+ // terminal the least important *selected* column drops by base_priority
+ // (Message=13 > Branch=1), independent of configured order.
+ let items = vec![make_test_item("a-fairly-long-feature-branch-name")];
+ let selected = [ColumnKind::Message, ColumnKind::Branch];
+ let layout = calculate_layout_with_width(
+ &items,
+ &full_skip_tasks(),
+ 24,
+ Path::new("/test"),
+ None,
+ None,
+ ColumnSelection {
+ custom: &[],
+ selected: Some(&selected),
+ },
+ );
+ assert!(
+ find_column(&layout, ColumnKind::Branch).is_some(),
+ "Branch (priority 1) survives a narrow width"
+ );
+ assert!(
+ find_column(&layout, ColumnKind::Message).is_none(),
+ "Message (priority 13) drops first despite being listed first"
+ );
+ }
+
#[test]
fn test_summary_absent_when_skipped() {
// Non-full mode: SummaryGenerate in skip_tasks → no Summary column
@@ -1951,8 +2222,18 @@ mod tests {
let skip = full_skip_tasks();
// At very wide terminals: both Path and Summary coexist
- let layout_wide =
- calculate_layout_with_width(&items, &skip, 300, main_path, None, None, &[]);
+ let layout_wide = calculate_layout_with_width(
+ &items,
+ &skip,
+ 300,
+ main_path,
+ None,
+ None,
+ ColumnSelection {
+ custom: &[],
+ selected: None,
+ },
+ );
assert!(
find_column(&layout_wide, ColumnKind::Summary).is_some(),
"Summary should be present at 300"
@@ -1965,8 +2246,18 @@ mod tests {
// At moderate widths (170): Summary should reach at least 50 chars.
// Currently Path eats ~30 chars from Summary's expansion budget,
// leaving Summary at ~48 and dropping Message entirely.
- let layout_170 =
- calculate_layout_with_width(&items, &skip, 170, main_path, None, None, &[]);
+ let layout_170 = calculate_layout_with_width(
+ &items,
+ &skip,
+ 170,
+ main_path,
+ None,
+ None,
+ ColumnSelection {
+ custom: &[],
+ selected: None,
+ },
+ );
let summary_170 = find_column(&layout_170, ColumnKind::Summary)
.expect("Summary should be present at 170")
.width;
@@ -2105,7 +2396,18 @@ mod tests {
let main_path = Path::new("/test/worktrunk");
let skip = full_skip_tasks();
- let layout = calculate_layout_with_width(&items, &skip, 170, main_path, None, None, &[]);
+ let layout = calculate_layout_with_width(
+ &items,
+ &skip,
+ 170,
+ main_path,
+ None,
+ None,
+ ColumnSelection {
+ custom: &[],
+ selected: None,
+ },
+ );
let mut lines = Vec::new();
lines.push(layout.render_header_line().plain_text());
@@ -2132,7 +2434,18 @@ mod tests {
// At 30 cols, ideal branch width (~57) can't fit, but Branch should still
// be allocated at a reduced width rather than dropped.
- let layout = calculate_layout_with_width(&items, &skip, 30, main_path, None, None, &[]);
+ let layout = calculate_layout_with_width(
+ &items,
+ &skip,
+ 30,
+ main_path,
+ None,
+ None,
+ ColumnSelection {
+ custom: &[],
+ selected: None,
+ },
+ );
let branch = find_column(&layout, ColumnKind::Branch);
assert!(
branch.is_some(),
@@ -2145,7 +2458,18 @@ mod tests {
);
// At 80 cols, Branch should fit comfortably
- let layout = calculate_layout_with_width(&items, &skip, 80, main_path, None, None, &[]);
+ let layout = calculate_layout_with_width(
+ &items,
+ &skip,
+ 80,
+ main_path,
+ None,
+ None,
+ ColumnSelection {
+ custom: &[],
+ selected: None,
+ },
+ );
let branch = find_column(&layout, ColumnKind::Branch).unwrap();
assert!(
branch.width > 6,
@@ -2205,7 +2529,10 @@ mod tests {
Path::new("/test"),
None,
None,
- &columns,
+ ColumnSelection {
+ custom: &columns,
+ selected: None,
+ },
);
// Value wider than max_width clamps to it
@@ -2244,7 +2571,10 @@ mod tests {
Path::new("/test"),
None,
None,
- &columns,
+ ColumnSelection {
+ custom: &columns,
+ selected: None,
+ },
);
// Values are final before layout, so an all-empty column is excluded
@@ -2267,7 +2597,10 @@ mod tests {
Path::new("/test"),
None,
None,
- &columns,
+ ColumnSelection {
+ custom: &columns,
+ selected: None,
+ },
);
// Priority 9 loses to the core columns when space runs out, and the
diff --git a/src/config/user/sections.rs b/src/config/user/sections.rs
index ec7a2cfbf..f4168a559 100644
--- a/src/config/user/sections.rs
+++ b/src/config/user/sections.rs
@@ -192,6 +192,24 @@ pub struct ListConfig {
#[serde(rename = "timeout-ms", skip_serializing_if = "Option::is_none")]
pub timeout_ms: Option<u64>,
+ /// Columns to render, in order. When non-empty this is exhaustive — only
+ /// these columns appear (a subset and/or reorder); empty means the default
+ /// set. Built-ins are kebab identifiers (`branch`, `status`, `working-diff`,
+ /// `ahead-behind`, `branch-diff`, `summary`, `upstream`, `ci`, `path`,
+ /// `url`, `commit`, `age`, `message`); custom columns are named by their
+ /// `[list.custom-columns]` header, so a selection mixes both in one list. A
+ /// built-in wins over a custom header that collides with its name. The
+ /// gutter type indicator always shows. A custom column omitted from a
+ /// non-empty selection is hidden; with no selection, custom columns append
+ /// to the default set. Set as a TOML array in config files.
+ // TODO(list-columns-env): `WORKTRUNK__LIST__COLUMNS` is not wired up yet. The
+ // env overlay can only deliver a scalar string, which a plain `Vec<String>`
+ // rejects. When we add it, parse the scalar as TOML
+ // (`WORKTRUNK__LIST__COLUMNS='["branch", "ci"]'`) so the env form matches the
+ // config-file array exactly, rather than splitting on commas.
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ pub columns: Vec<String>,
+
/// Custom columns, keyed by header text. See [`ListColumnConfig`].
///
/// *(Experimental — fields may change in future releases.)*
@@ -252,6 +270,16 @@ impl Merge for ListConfig {
.iter()
.map(|(k, v)| (k.clone(), v.clone())),
);
+ // Column selection replaces wholesale (a more specific layer's order is
+ // the order it wants); an empty list means "unset", so it falls back to
+ // the base layer rather than blanking the selection. Unlike
+ // custom_columns, merging entries would be meaningless — a column list
+ // is an ordering, not a keyed set.
+ let columns = if other.columns.is_empty() {
+ self.columns.clone()
+ } else {
+ other.columns.clone()
+ };
Self {
full: other.full.or(self.full),
branches: other.branches.or(self.branches),
@@ -259,6 +287,7 @@ impl Merge for ListConfig {
summary: other.summary.or(self.summary),
task_timeout_ms: other.task_timeout_ms.or(self.task_timeout_ms),
timeout_ms: other.timeout_ms.or(self.timeout_ms),
+ columns,
custom_columns,
}
}
diff --git a/src/config/user/tests.rs b/src/config/user/tests.rs
index ab99c4565..5cacd5487 100644
--- a/src/config/user/tests.rs
+++ b/src/config/user/tests.rs
@@ -278,6 +278,7 @@ fn test_list_config_serde() {
summary: None,
task_timeout_ms: Some(500),
timeout_ms: None,
+ columns: vec!["branch".into(), "ci".into(), "path".into()],
custom_columns: Default::default(),
};
let json = serde_json::to_string(&config).unwrap();
@@ -288,6 +289,28 @@ fn test_list_config_serde() {
assert_eq!(parsed.summary, None);
assert_eq!(parsed.task_timeout_ms, Some(500));
assert_eq!(parsed.timeout_ms, None);
+ assert_eq!(parsed.columns, vec!["branch", "ci", "path"]);
+}
+
+#[test]
+fn test_list_config_columns_from_toml_array() {
+ // Config files use a TOML array.
+ let from_array: ListConfig = toml::from_str(r#"columns = ["branch", "ci"]"#).unwrap();
+ assert_eq!(from_array.columns, vec!["branch", "ci"]);
+
+ // Array entries are taken verbatim, so a stray-space entry survives to fail
+ // loudly at the wt list edge rather than being silently dropped.
+ let untrimmed: ListConfig = toml::from_str(r#"columns = [" branch "]"#).unwrap();
+ assert_eq!(untrimmed.columns, vec![" branch "]);
+
+ // Absent → empty (the default column set), not an error.
+ let absent: ListConfig = toml::from_str("full = true").unwrap();
+ assert!(absent.columns.is_empty());
+
+ // TODO(list-columns-env): the env overlay can only deliver a scalar, so the
+ // string form is rejected until env-var support lands (see ListConfig::columns).
+ let from_string: Result<ListConfig, _> = toml::from_str(r#"columns = "branch,ci""#);
+ assert!(from_string.is_err());
}
#[test]
@@ -607,6 +630,7 @@ fn test_merge_list_config() {
summary: Some(true),
task_timeout_ms: Some(1000),
timeout_ms: Some(2000),
+ columns: vec!["branch".into(), "ci".into()],
custom_columns: Default::default(),
};
let override_config = ListConfig {
@@ -616,6 +640,7 @@ fn test_merge_list_config() {
summary: None, // Should fall back to base
task_timeout_ms: None, // Should fall back to base
timeout_ms: None, // Should fall back to base
+ columns: Vec::new(), // Empty → fall back to base
custom_columns: Default::default(),
};
@@ -626,6 +651,24 @@ fn test_merge_list_config() {
assert_eq!(merged.summary, Some(true)); // From base
assert_eq!(merged.task_timeout_ms, Some(1000)); // From base
assert_eq!(merged.timeout_ms, Some(2000)); // From base
+ assert_eq!(merged.columns, vec!["branch", "ci"]); // From base (override empty)
+}
+
+#[test]
+fn test_merge_list_config_columns_replace() {
+ // A non-empty override replaces the whole list (it's an ordering, not a
+ // keyed set), unlike the per-key union used for custom_columns.
+ let base = ListConfig {
+ columns: vec!["branch".into(), "ci".into(), "path".into()],
+ ..Default::default()
+ };
+ let override_config = ListConfig {
+ columns: vec!["status".into(), "branch".into()],
+ ..Default::default()
+ };
+
+ let merged = base.merge_with(&override_config);
+ assert_eq!(merged.columns, vec!["status", "branch"]);
}
#[test]
@@ -1059,6 +1102,7 @@ fn test_list_config_accessor_methods_with_values() {
summary: Some(true),
task_timeout_ms: Some(5000),
timeout_ms: Some(3000),
+ columns: Vec::new(),
custom_columns: Default::default(),
};
assert!(config.full());
diff --git a/tests/integration_tests/list_config.rs b/tests/integration_tests/list_config.rs
index 56748fec3..43e792866 100644
--- a/tests/integration_tests/list_config.rs
+++ b/tests/integration_tests/list_config.rs
@@ -895,3 +895,196 @@ template = "{{ worktree_name }}"
"branch-only row has no worktree name, so the Dir cell is empty"
);
}
+
+/// `[list] columns` selects and reorders the built-in columns end-to-end:
+/// only the listed columns appear (Commit, normally shown at this width, is
+/// gone), in the configured order (Age before Branch), with the gutter always
+/// present.
+#[rstest]
+fn test_list_config_columns_select_and_reorder(repo: TestRepo) {
+ fs::write(
+ repo.test_config_path(),
+ r#"[list]
+columns = ["age", "branch"]
+"#,
+ )
+ .unwrap();
+
+ let settings = setup_snapshot_settings(&repo);
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ repo.configure_wt_cmd(&mut cmd);
+ // Wide enough that the default set (incl. Commit) would all fit, so an
+ // absent Commit proves selection filtered it rather than width dropping.
+ cmd.env("COLUMNS", "200");
+ cmd.arg("list").current_dir(repo.root_path());
+
+ let output = cmd.output().unwrap();
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(output.status.success(), "exit code should be 0: {stderr}");
+ let stdout = String::from_utf8_lossy(&output.stdout);
+
+ let header = stdout
+ .lines()
+ .find(|line| line.contains("Branch"))
+ .unwrap_or_else(|| panic!("no header row in:\n{stdout}"));
+ assert!(header.contains("Age"), "Age selected, got header: {header}");
+ assert!(
+ !header.contains("Commit"),
+ "Commit not selected, should be absent: {header}"
+ );
+ assert!(
+ !header.contains("Message"),
+ "Message not selected, should be absent: {header}"
+ );
+ let age_at = header.find("Age").unwrap();
+ let branch_at = header.find("Branch").unwrap();
+ assert!(
+ age_at < branch_at,
+ "configured order puts Age before Branch: {header}"
+ );
+ });
+}
+
+/// Custom columns are addressable in `[list] columns` by their header. A named
+/// custom renders interleaved with built-ins at its configured position, while a
+/// custom omitted from a non-empty selection is hidden. Both use the `codename`
+/// filter so every row has a value (an all-empty custom drops regardless).
+#[rstest]
+fn test_list_config_columns_select_custom(repo: TestRepo) {
+ fs::write(
+ repo.test_config_path(),
+ r#"[list]
+columns = ["branch", "Codename", "age"]
+
+[list.custom-columns.Codename]
+template = "{{ branch | codename }}"
+
+[list.custom-columns.Owner]
+template = "{{ branch | codename }}"
+"#,
+ )
+ .unwrap();
+
+ let settings = setup_snapshot_settings(&repo);
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ repo.configure_wt_cmd(&mut cmd);
+ cmd.env("COLUMNS", "200");
+ cmd.arg("list").current_dir(repo.root_path());
+
+ let output = cmd.output().unwrap();
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(output.status.success(), "exit code should be 0: {stderr}");
+ let stdout = String::from_utf8_lossy(&output.stdout);
+
+ let header = stdout
+ .lines()
+ .find(|line| line.contains("Branch"))
+ .unwrap_or_else(|| panic!("no header row in:\n{stdout}"));
+ assert!(
+ header.contains("Codename"),
+ "a selected custom column renders: {header}"
+ );
+ assert!(
+ !header.contains("Owner"),
+ "a custom omitted from a non-empty selection is hidden: {header}"
+ );
+ let branch_at = header.find("Branch").unwrap();
+ let codename_at = header.find("Codename").unwrap();
+ let age_at = header.find("Age").unwrap();
+ assert!(
+ branch_at < codename_at && codename_at < age_at,
+ "the custom sorts at its configured position between built-ins: {header}"
+ );
+ });
+}
+
+/// TODO(list-columns-env): `WORKTRUNK__LIST__COLUMNS` is not wired up yet. The
+/// env overlay can only deliver a scalar, which the `Vec<String>` field rejects,
+/// so the override is dropped — but with a warning naming the var, not silently
+/// (see `ListConfig::columns`). The default columns still render. When env
+/// support lands, this becomes a working selection (Commit drops, Age stays).
+#[rstest]
+fn test_list_config_columns_env_override_not_yet_supported(repo: TestRepo) {
+ let settings = setup_snapshot_settings(&repo);
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ repo.configure_wt_cmd(&mut cmd);
+ cmd.env("COLUMNS", "200");
+ cmd.env("WORKTRUNK__LIST__COLUMNS", "branch,age");
+ cmd.arg("list").current_dir(repo.root_path());
+ assert_cmd_snapshot!(cmd);
+ });
+}
+
+/// An unknown column name aborts `wt list` with a message that lists the valid
+/// names, so a typo is self-correcting rather than silently rendering a
+/// different table.
+#[rstest]
+fn test_list_config_columns_unknown_name_errors(repo: TestRepo) {
+ fs::write(
+ repo.test_config_path(),
+ r#"[list]
+columns = ["branch", "bogus"]
+"#,
+ )
+ .unwrap();
+
+ let settings = setup_snapshot_settings(&repo);
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ repo.configure_wt_cmd(&mut cmd);
+ cmd.arg("list").current_dir(repo.root_path());
+
+ let output = cmd.output().unwrap();
+ assert!(
+ !output.status.success(),
+ "an unknown column name should abort wt list"
+ );
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(stderr.contains("Unknown column"), "stderr: {stderr}");
+ assert!(
+ stderr.contains("bogus"),
+ "stderr names the bad column: {stderr}"
+ );
+ assert!(
+ stderr.contains("branch"),
+ "stderr lists valid names: {stderr}"
+ );
+ });
+}
+
+/// The headline use case: `wt --config-set 'list.columns=[…]' list` renders a
+/// reduced view for a single invocation. The TOML array parses natively in the
+/// override fragment (no string splitting needed), winning over any config file.
+#[rstest]
+fn test_list_config_columns_cli_override(repo: TestRepo) {
+ let settings = setup_snapshot_settings(&repo);
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ repo.configure_wt_cmd(&mut cmd);
+ cmd.env("COLUMNS", "200");
+ cmd.args([
+ "--config-set",
+ r#"list.columns = ["branch", "age"]"#,
+ "list",
+ ])
+ .current_dir(repo.root_path());
+
+ let output = cmd.output().unwrap();
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(output.status.success(), "exit code should be 0: {stderr}");
+ let stdout = String::from_utf8_lossy(&output.stdout);
+
+ let header = stdout
+ .lines()
+ .find(|line| line.contains("Branch"))
+ .unwrap_or_else(|| panic!("no header row in:\n{stdout}"));
+ assert!(header.contains("Age"), "Age selected: {header}");
+ assert!(
+ !header.contains("Commit"),
+ "Commit not selected, should be absent: {header}"
+ );
+ });
+}
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index 15cb6b5e9..38f063b69 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -165,9 +165,37 @@ Creates ~/.config/worktrunk/config.toml with the following content:
  # branches = false # Include branches without worktrees (--branches)
  # remotes = false # Include remote-only branches (--remotes)
  #
+  # columns = ["branch", "status", "ci", "path"] # Columns to show, in order — built-ins or custom headers (omit for the default set)
+  #
  # task-timeout-ms = 0 # Kill individual git commands after N ms; 0 disables
  # timeout-ms = 0 # Wall-clock budget for the entire collect phase; 0 disables
  #
+  # `columns` selects and orders the columns to render; omit it for the default set.
+  # It is designed to be driven by an alias (https://worktrunk.dev/extending/#aliases) that sets it
+  # per invocation — a body like `wt --config-set 'list.columns=[…]' list` gives a
+  # named view (run as `wt <alias>`) without disturbing the default `wt list`.
+  # Setting it statically in the config file uses the same key and works, but is not
+  # the intended use: it pins one layout over a table that otherwise adapts to
+  # `--full` and terminal width.
+  #
+  # Valid built-in names are `branch`, `status`, `working-diff`, `ahead-behind`,
+  # `branch-diff`, `summary`, `upstream`, `ci`, `path`, `url`, `commit`, `age`, and
+  # `message`. A custom column (#custom-columns) is named by its `[list.custom-columns]`
+  # header, so a selection mixes built-ins and custom columns in one ordered list
+  # (`columns = ["branch", "Ticket", "ci"]`). When `columns` is set it is exhaustive
+  # — only the listed columns render, so a custom column omitted from a non-empty
+  # list is hidden (omit `columns` entirely to keep the default set, where custom
+  # columns append automatically). A built-in name wins over a custom header that
+  # collides with it. The gutter type indicator always shows.
+  #
+  # Listing a column requests it but does not force it on: a column gated off
+  # elsewhere stays hidden — `ci` needs `--full`, `summary` needs
+  # `[commit.generation]` — so `columns` only narrows which columns may appear.
+  #
+  # The selection drives the rendered table and the `wt switch` picker.
+  # `wt list --format json` ignores it, always emitting every field, built-in and
+  # custom.
+  #
  # #### Custom columns [experimental]
  #
  # Custom columns add per-branch context to the `wt list` table. Each
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 980808a22..865233ca0 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -213,9 +213,37 @@ Persistent flag values for wt list. Override on command line as needed.
  branches = false # Include branches without worktrees (--branches)
  remotes = false # Include remote-only branches (--remotes)
 
+  columns = ["branch", "status", "ci", "path"] # Columns to show, in order — built-ins or custom headers (omit for the default set)
+ 
  task-timeout-ms = 0 # Kill individual git commands after N ms; 0 disables
  timeout-ms = 0 # Wall-clock budget for the entire collect phase; 0 disables
+columns selects and orders the columns to render; omit it for the default set.
+It is designed to be driven by an alias that sets it
+per invocation — a body like wt --config-set 'list.columns=[…]' list gives a
+named view (run as wt <alias>) without disturbing the default wt list.
+Setting it statically in the config file uses the same key and works, but is not
+the intended use: it pins one layout over a table that otherwise adapts to
+--full and terminal width.
+
+Valid built-in names are branch, status, working-diff, ahead-behind,
+branch-diff, summary, upstream, ci, path, url, commit, age, and
+message. A custom column is named by its [list.custom-columns]
+header, so a selection mixes built-ins and custom columns in one ordered list
+(columns = ["branch", "Ticket", "ci"]). When columns is set it is exhaustive
+— only the listed columns render, so a custom column omitted from a non-empty
+list is hidden (omit columns entirely to keep the default set, where custom
+columns append automatically). A built-in name wins over a custom header that
+collides with it. The gutter type indicator always shows.
+
+Listing a column requests it but does not force it on: a column gated off
+elsewhere stays hidden — ci needs --full, summary needs
+[commit.generation] — so columns only narrows which columns may appear.
+
+The selection drives the rendered table and the wt switch picker.
+wt list --format json ignores it, always emitting every field, built-in and
+custom.
+
Custom columns [experimental]
Custom columns add per-branch context to the wt list table. Each
diff --git a/tests/snapshots/integration__integration_tests__list_config__list_config_columns_env_override_not_yet_supported.snap b/tests/snapshots/integration__integration_tests__list_config__list_config_columns_env_override_not_yet_supported.snap
new file mode 100644
index 000000000..f2c284f02
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__list_config__list_config_columns_env_override_not_yet_supported.snap
@@ -0,0 +1,58 @@
+---
+source: tests/integration_tests/list_config.rs
+info:
+ program: wt
+ args:
+ - list
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "200"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
+ WORKTRUNK__LIST__COLUMNS: "branch,age"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+ Branch Status HEAD± main↕ Remote⇅ Path Commit Age Message
+@ main ^| | . 05a4a45d 16h Initial commit
++ feature-a ↑ ↑1 ../repo.feature-a 1b87d473 16h Add feature-a file
++ feature-b ↑ ↑1 ../repo.feature-b f62940fc 16h Add feature-b file
++ feature-c ↑ ↑1 ../repo.feature-c 345c7c93 16h Add feature-c file
+
+○ Showing 4 worktrees, 3 ahead
+
+----- stderr -----
+▲ Ignoring env var overrides: WORKTRUNK__LIST__COLUMNS=branch,age
+  invalid type: string "branch,age", expected a sequence
+  in `list.columns`