Skip to content

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

feat(switch): make the picker filter text match the gutter sigil (#3143)

Maximilian Roosc5c2742058d7
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 42b82033b..8e375afd2 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -84,6 +84,8 @@ The CI column shows cached PR/MR status when earlier runs (`wt list --full`, the
Plain digits go to the filter, so a branch name containing a number can be typed directly; the preview tabs move to `Alt`.
+Typing a gutter sigil filters by row kind: `+` narrows to linked worktrees and `@` to the current worktree. The other sigils don't filter cleanly — `^` and `|` are skim's prefix-anchor and OR query operators (so `^` matches every row and `|` none), and `/` matches most rows because every worktree path contains it.
+
**Preview tabs** — jump with `Alt-1`–`Alt-5`, or cycle with `Tab`/`Shift-Tab`:
1. **HEAD±** — Diff of uncommitted changes
diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.md
index 53b4ee152..17562bdc3 100644
--- a/skills/worktrunk/reference/switch.md
+++ b/skills/worktrunk/reference/switch.md
@@ -80,6 +80,8 @@ The CI column shows cached PR/MR status when earlier runs (`wt list --full`, the
Plain digits go to the filter, so a branch name containing a number can be typed directly; the preview tabs move to `Alt`.
+Typing a gutter sigil filters by row kind: `+` narrows to linked worktrees and `@` to the current worktree. The other sigils don't filter cleanly — `^` and `|` are skim's prefix-anchor and OR query operators (so `^` matches every row and `|` none), and `/` matches most rows because every worktree path contains it.
+
**Preview tabs** — jump with `Alt-1`–`Alt-5`, or cycle with `Tab`/`Shift-Tab`:
1. **HEAD±** — Diff of uncommitted changes
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 91983c1d7..680758629 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -655,6 +655,8 @@ The CI column shows cached PR/MR status when earlier runs (`wt list --full`, the
Plain digits go to the filter, so a branch name containing a number can be typed directly; the preview tabs move to `Alt`.
+Typing a gutter sigil filters by row kind: `+` narrows to linked worktrees and `@` to the current worktree. The other sigils don't filter cleanly — `^` and `|` are skim's prefix-anchor and OR query operators (so `^` matches every row and `|` none), and `/` matches most rows because every worktree path contains it.
+
**Preview tabs** — jump with `Alt-1`–`Alt-5`, or cycle with `Tab`/`Shift-Tab`:
1. **HEAD±** — Diff of uncommitted changes
diff --git a/src/commands/list/model/item.rs b/src/commands/list/model/item.rs
index 86e8d006c..72b6bca24 100644
--- a/src/commands/list/model/item.rs
+++ b/src/commands/list/model/item.rs
@@ -103,6 +103,34 @@ pub enum ItemKind {
Branch(BranchScope),
}
+impl ItemKind {
+ /// The single-character gutter glyph identifying this row's kind:
+ /// worktrees by location (`@` current, `^` primary/main, `+` other
+ /// linked), branches by scope (`/` local, `|` remote). Single-width
+ /// ASCII by design — the gutter must dodge skim's `width_cjk` clipping.
+ ///
+ /// Canonical source shared by the rendered Gutter column (which appends
+ /// a trailing space for the two-cell sigil) and the picker's fuzzy-search
+ /// text, so the glyph a user sees is the glyph they can type to filter.
+ /// A skeleton-time fact — `is_current`/`is_main` are set at construction
+ /// and `BranchScope` is structural — so folding it into the search text
+ /// keeps fuzzy ranks stable across the picker's progressive column updates.
+ pub fn gutter_glyph(&self) -> char {
+ match self {
+ ItemKind::Worktree(data) => {
+ if data.is_current {
+ '@'
+ } else if data.is_main {
+ '^'
+ } else {
+ '+'
+ }
+ }
+ ItemKind::Branch(scope) => scope.gutter_glyph(),
+ }
+ }
+}
+
/// Whether a branch-without-worktree row is a local branch
/// (`refs/heads/…`, checked out nowhere) or a remote-tracking branch
/// (`refs/remotes/<remote>/…`, not present locally until fetched).
@@ -125,13 +153,13 @@ pub enum BranchScope {
}
impl BranchScope {
- /// The two-cell gutter sigil (`glyph` + trailing space) for a branch
- /// row of this scope. ASCII single-width by design — the gutter must
- /// dodge skim's `width_cjk` clipping.
- pub const fn gutter_sigil(self) -> &'static str {
+ /// The gutter glyph for a branch row of this scope: `/` local, `|`
+ /// remote. See [`ItemKind::gutter_glyph`] for the row-kind axis this
+ /// feeds and how the rendered sigil and picker search text share it.
+ pub const fn gutter_glyph(self) -> char {
match self {
- BranchScope::Local => "/ ",
- BranchScope::Remote => "| ",
+ BranchScope::Local => '/',
+ BranchScope::Remote => '|',
}
}
}
@@ -741,6 +769,24 @@ mod tests {
assert!(item.worktree_path().is_none());
}
+ #[test]
+ fn gutter_glyph_marks_each_row_kind() {
+ let worktree = |is_main, is_current| {
+ ItemKind::Worktree(Box::new(WorktreeData {
+ is_main,
+ is_current,
+ ..Default::default()
+ }))
+ };
+ // Worktrees by location (`is_current` wins when a row is both).
+ assert_eq!(worktree(false, true).gutter_glyph(), '@');
+ assert_eq!(worktree(true, false).gutter_glyph(), '^');
+ assert_eq!(worktree(false, false).gutter_glyph(), '+');
+ // Branches by scope.
+ assert_eq!(ItemKind::Branch(BranchScope::Local).gutter_glyph(), '/');
+ assert_eq!(ItemKind::Branch(BranchScope::Remote).gutter_glyph(), '|');
+ }
+
#[test]
fn test_list_item_should_dim() {
// No status_symbols = should NOT dim (data still loading)
diff --git a/src/commands/list/render.rs b/src/commands/list/render.rs
index b5d87f6bc..110d3eb56 100644
--- a/src/commands/list/render.rs
+++ b/src/commands/list/render.rs
@@ -297,7 +297,9 @@ impl LayoutConfig {
// render (and its Status-column twin) — no flash or flicker.
match &item.kind {
ItemKind::Worktree(_) => cell.push_styled(format!("{spinner} "), dim),
- ItemKind::Branch(scope) => cell.push_styled(scope.gutter_sigil(), dim),
+ ItemKind::Branch(scope) => {
+ cell.push_styled(format!("{} ", scope.gutter_glyph()), dim)
+ }
}
}
ColumnKind::Branch => {
@@ -415,26 +417,20 @@ impl ColumnLayout {
// ASCII — the gutter must dodge skim's `width_cjk` clipping.
//
// TODO(pr-rows): PR rows (open PRs with no local branch) land
- // on a separate branch; add a `#` arm here (and a matching `#`
- // in the Status upstream column). Not done here — PR rows don't
- // exist in this branch, and the picker skips CI/PR detection (a
- // network call), so a `#` driven by PR status would never
- // render in the picker.
+ // on a separate branch; add a `#` arm to `ItemKind::gutter_glyph`
+ // (and a matching `#` in the Status upstream column). Not done
+ // here — PR rows don't exist on this branch, and the picker
+ // skips CI/PR detection (a network call), so a `#` driven by PR
+ // status would never render in the picker.
let mut cell = StyledLine::new();
+ // `glyph` + trailing space = the two-cell sigil; the bare glyph
+ // also feeds the picker's fuzzy-search text (`gutter_glyph`).
+ let sigil = format!("{} ", item.kind.gutter_glyph());
match &item.kind {
- ItemKind::Worktree(data) => {
- let symbol = if data.is_current {
- "@ " // Current worktree
- } else if data.is_main {
- "^ " // Main worktree
- } else {
- "+ " // Regular worktree (including previous)
- };
- cell.push_raw(symbol);
- }
- ItemKind::Branch(scope) => {
- cell.push_styled(scope.gutter_sigil(), Style::new().dimmed());
- }
+ // Worktree rows are materialized on disk — render bright.
+ ItemKind::Worktree(_) => cell.push_raw(sigil),
+ // Branch rows are refs with no working copy — render dim.
+ ItemKind::Branch(_) => cell.push_styled(sigil, Style::new().dimmed()),
}
cell
}
diff --git a/src/commands/picker/progressive_handler.rs b/src/commands/picker/progressive_handler.rs
index 0037a3346..f344bc31a 100644
--- a/src/commands/picker/progressive_handler.rs
+++ b/src/commands/picker/progressive_handler.rs
@@ -135,11 +135,16 @@ impl PickerProgressHandler for PickerHandler {
.unwrap_or_default();
// `search_text` is what the matcher sees — fuzzy ranks stay
// stable across progressive updates because this field only
- // depends on fast data (branch + path).
+ // depends on fast data (branch + path + gutter glyph). The
+ // trailing gutter glyph lets typing a sigil filter by row kind:
+ // `+` to linked worktrees, `@` to the current one, `/`/`|` to
+ // local/remote branches (`gutter_glyph` is the same skeleton-time
+ // fact the rendered Gutter column uses).
+ let gutter = item.kind.gutter_glyph();
let search_text = if path_str.is_empty() {
- branch_name.clone()
+ format!("{branch_name} {gutter}")
} else {
- format!("{branch_name} {path_str}")
+ format!("{branch_name} {path_str} {gutter}")
};
// Strip OSC 8 hyperlinks — skim's pipeline mangles them into
@@ -340,6 +345,92 @@ mod tests {
assert_eq!(shared[2].output().as_ref(), "feat-b");
}
+ /// `on_skeleton` folds each row's gutter glyph onto the end of the
+ /// matcher's `search_text`, so typing a sigil filters by row kind. The
+ /// glyph comes from `ItemKind::gutter_glyph` (which handles every kind and
+ /// is unit-tested in `item.rs`), so branch rows here prove the wiring.
+ #[test]
+ fn search_text_folds_in_gutter_glyph() {
+ let (handler, _test, rx) = make_handler();
+ let items = vec![
+ ListItem::new_branch("abc".into(), "localbr".into()),
+ ListItem::new_remote_branch("abc".into(), "origin/remotebr".into()),
+ ];
+ handler.on_skeleton(
+ items,
+ vec!["skel-local".into(), "skel-remote".into()],
+ header("hdr"),
+ );
+
+ let received = rx.recv().expect("skeleton batch");
+ // received[0] is the non-selectable header; data rows follow in order.
+ let text = |i: usize| received[i].text().into_owned();
+ assert!(text(1).ends_with('/'), "local branch: {:?}", text(1));
+ assert!(text(2).ends_with('|'), "remote branch: {:?}", text(2));
+ // Branch name stays searchable alongside the folded-in glyph.
+ assert!(text(1).contains("localbr"));
+ assert!(text(2).contains("origin/remotebr"));
+ }
+
+ /// Locks the gutter-sigil filtering contract against skim's default engine —
+ /// an `AndOrEngineFactory` wrapping an `ExactOrFuzzyEngineFactory`, the
+ /// factory `Matcher::create_engine_factory` builds when the picker sets
+ /// neither `--exact` nor `--regex` (skim 4.8 `src/matcher.rs`). `+`/`@` are
+ /// literals that filter to their row kind; `^` and `|` collide with skim's
+ /// prefix-anchor and OR operators and don't.
+ #[test]
+ fn gutter_glyphs_filter_under_skims_default_engine() {
+ struct TextItem(String);
+ impl SkimItem for TextItem {
+ fn text(&self) -> std::borrow::Cow<'_, str> {
+ std::borrow::Cow::Borrowed(&self.0)
+ }
+ }
+
+ // One representative folded `search_text` per gutter kind.
+ let current = "cur /tmp/cur @";
+ let primary = "primary /tmp/primary ^";
+ let linked = "linked /tmp/linked +";
+ let local = "localbr /";
+ let remote = "origin/remotebr |";
+
+ let matches = |query: &str, haystack: &str| -> bool {
+ let factory = AndOrEngineFactory::new(ExactOrFuzzyEngineFactory::builder().build());
+ factory
+ .create_engine(query)
+ .match_item(&TextItem(haystack.to_string()))
+ .is_some()
+ };
+
+ // `+`/`@` are literals — each filters to exactly its row kind.
+ assert!(matches("+", linked), "+ selects the linked worktree");
+ for other in [current, primary, local, remote] {
+ assert!(!matches("+", other), "+ must not match {other:?}");
+ }
+ assert!(matches("@", current), "@ selects the current worktree");
+ for other in [primary, linked, local, remote] {
+ assert!(!matches("@", other), "@ must not match {other:?}");
+ }
+
+ // `^` is skim's prefix anchor: a bare `^` is an empty prefix pattern
+ // that matches every row, so it can't isolate the primary worktree.
+ // Proven by matching rows that contain no literal `^`.
+ for row in [current, linked, local, remote] {
+ assert!(
+ matches("^", row),
+ "^ (prefix anchor) matches all rows — not a filter: {row:?}"
+ );
+ }
+ // A bare `|` is skim's OR separator with empty operands, which matches
+ // nothing — so it can't isolate remote-branch rows (which carry `|`).
+ for row in [remote, current, linked, local] {
+ assert!(
+ !matches("|", row),
+ "| (OR operator) matches nothing — not a filter: {row:?}"
+ );
+ }
+ }
+
/// `stash_warning` accumulates lines in arrival order so the picker can
/// drain them in one shot after skim releases the terminal.
#[test]
diff --git a/tests/integration_tests/switch_picker.rs b/tests/integration_tests/switch_picker.rs
index c1d734f02..d95edc4ed 100644
--- a/tests/integration_tests/switch_picker.rs
+++ b/tests/integration_tests/switch_picker.rs
@@ -602,6 +602,56 @@ fn test_switch_picker_with_branches(mut repo: TestRepo) {
});
}
+/// Typing a gutter glyph filters the picker by row kind. `+` is the linked-
+/// worktree glyph, so it narrows to linked worktrees — excluding the current
+/// worktree (`@`) and branch rows (`/`). This is the end-to-end answer to "why
+/// doesn't `+` select *all* the worktrees?": the current worktree is a
+/// different gutter kind. The `active-worktree` row has no literal `+` in its
+/// name or path, so the match succeeds *only* via the glyph folded into the
+/// search text (`progressive_handler::on_skeleton`) — if the fold regressed,
+/// the list would empty out and the `active-worktree` wait below would time out.
+#[rstest]
+fn test_switch_picker_gutter_glyph_filters_by_kind(mut repo: TestRepo) {
+ repo.remove_fixture_worktrees();
+ // Remove origin so a remote-tracking row doesn't join the list.
+ repo.run_git(&["remote", "remove", "origin"]);
+ repo.add_worktree("active-worktree");
+ // Create a branch without a worktree (a `/` gutter row).
+ let output = repo
+ .git_command()
+ .args(["branch", "orphan-branch"])
+ .run()
+ .unwrap();
+ assert!(output.status.success(), "Failed to create branch");
+
+ let env_vars = repo.test_env_vars();
+ let result = exec_in_pty_capture_before_abort(
+ wt_bin().to_str().unwrap(),
+ &["switch", "--branches"],
+ repo.root_path(),
+ &env_vars,
+ // Type the linked-worktree glyph, then wait for the filtered list to
+ // settle on the one linked worktree before capturing.
+ &[("+", Some("active-worktree"))],
+ );
+
+ assert_valid_abort_exit_code(result.exit_code);
+
+ let (list, _preview) = result.panels();
+ assert!(
+ list.contains("active-worktree"),
+ "`+` keeps the linked worktree:\n{list}"
+ );
+ assert!(
+ !list.contains("@ main"),
+ "`+` filters out the current worktree (`@`):\n{list}"
+ );
+ assert!(
+ !list.contains("orphan-branch"),
+ "`+` filters out branch rows (`/`):\n{list}"
+ );
+}
+
#[rstest]
fn test_switch_picker_preview_panel_uncommitted(mut repo: TestRepo) {
repo.remove_fixture_worktrees();
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index bbb54c561..d7875e463 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -189,6 +189,8 @@ The CI column shows cached PR/MR status when earlier runs (wt list --full[0
Plain digits go to the filter, so a branch name containing a number can be typed directly; the preview tabs move to Alt.
+Typing a gutter sigil filters by row kind: + narrows to linked worktrees and @ to the current worktree. The other sigils don't filter cleanly — ^ and | are skim's prefix-anchor and OR query operators (so ^ matches every row and | none), and / matches most rows because every worktree path contains it.
+
Preview tabs — jump with Alt-1–Alt-5, or cycle with Tab/Shift-Tab:
1. HEAD± — Diff of uncommitted changes