Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
feat(hints): track shown count and escalate shell-integration hint at 5+ (#2603)
Maximilian Roos95a4176c8057
diff --git a/src/cli/config.rs b/src/cli/config.rsindex 13a3af601..473f23120 100644--- a/src/cli/config.rs+++ b/src/cli/config.rs@@ -782,7 +782,7 @@ $ wt config state logs clear/// One-time hints shown in this repo#[command(after_long_help = r#"Some hints show once per repo on first use, then are recorded in git config-as `worktrunk.hints.<name> = true`.+as `worktrunk.hints.<name>`, a count of times the hint has been shown.## Current hintsdiff --git a/src/commands/worktree/switch.rs b/src/commands/worktree/switch.rsindex a6104cc0e..2d4e13e45 100644--- a/src/commands/worktree/switch.rs+++ b/src/commands/worktree/switch.rs@@ -1359,7 +1359,7 @@ pub fn run_switch(// Best-effort: don't fail switch if offer failsif change_dir && !is_shell_integration_active() {let skip_prompt = execute.is_some();- let _ = prompt_shell_integration(config, binary_name, skip_prompt);+ let _ = prompt_shell_integration(&repo, config, binary_name, skip_prompt);}// Build template vars for base/target context (used by both hooks anddiff --git a/src/git/repository/config.rs b/src/git/repository/config.rsindex 2f3add7dc..2b73e3ad7 100644--- a/src/git/repository/config.rs+++ b/src/git/repository/config.rs@@ -215,7 +215,10 @@ impl Repository {/// Check if a hint has been shown in this repo.///- /// Hints are stored as `worktrunk.hints.<name> = true`.+ /// Hints are stored as `worktrunk.hints.<name> = <count>` (an integer+ /// representing how many times the hint has been shown). The presence of+ /// the key — regardless of value — means the hint has been shown at least+ /// once./// TODO: Could move to global git config if we accumulate more global hints.pub fn has_shown_hint(&self, name: &str) -> bool {self.config_last(&format!("worktrunk.hints.{name}"))@@ -224,9 +227,37 @@ impl Repository {.is_some()}- /// Mark a hint as shown in this repo.+ /// Return how many times a hint has been shown in this repo.+ ///+ /// Returns `0` when the key is missing. Legacy `"true"` values (written+ /// before the counter migration) parse as `0`, so the next+ /// [`mark_hint_shown`] increments them to `1` — the same as a fresh hint.+ /// This loses the "user has seen this before" signal for legacy entries,+ /// which is acceptable: the only consumer of the count is the+ /// shell-integration escalation at 5+, and a legacy user merely starts+ /// their counter from zero. `has_shown_hint` still returns `true` so any+ /// "first time" branches still skip.+ ///+ /// [`mark_hint_shown`]: Self::mark_hint_shown+ pub fn hint_count(&self, name: &str) -> u32 {+ self.config_last(&format!("worktrunk.hints.{name}"))+ .ok()+ .flatten()+ .and_then(|s| s.parse::<u32>().ok())+ .unwrap_or(0)+ }++ /// Mark a hint as shown in this repo, incrementing its display counter.+ ///+ /// The first call writes `1`; subsequent calls increment. Legacy `"true"`+ /// values (written before the counter migration) and any unparsable+ /// content are treated as `0`, so the next call resets to `1` — see+ /// [`hint_count`] for the rationale.+ ///+ /// [`hint_count`]: Self::hint_countpub fn mark_hint_shown(&self, name: &str) -> anyhow::Result<()> {- self.set_config_value(&format!("worktrunk.hints.{name}"), "true")+ let next = self.hint_count(name).saturating_add(1);+ self.set_config_value(&format!("worktrunk.hints.{name}"), &next.to_string())}/// Clear a hint so it will show again.@@ -613,4 +644,57 @@ mod tests {assert!(output.contains("worktrunk.state.feature.marker"));assert!(output.contains("worktrunk.state.bugfix.marker"));}++ /// `mark_hint_shown` writes 1 on first call and increments on each+ /// subsequent call. `hint_count` returns 0 for missing keys and the+ /// current count otherwise; `clear_hint` resets the counter back to 0.+ #[test]+ fn test_hint_count_increments_and_clears() {+ let test = TestRepo::with_initial_commit();+ let repo = Repository::at(test.root_path()).unwrap();++ // Missing key -> 0, and "shown" predicate is false.+ assert_eq!(repo.hint_count("escalating"), 0);+ assert!(!repo.has_shown_hint("escalating"));++ // First mark records 1.+ repo.mark_hint_shown("escalating").unwrap();+ assert_eq!(repo.hint_count("escalating"), 1);+ assert!(repo.has_shown_hint("escalating"));++ // Subsequent marks increment.+ repo.mark_hint_shown("escalating").unwrap();+ assert_eq!(repo.hint_count("escalating"), 2);+ repo.mark_hint_shown("escalating").unwrap();+ assert_eq!(repo.hint_count("escalating"), 3);++ // Clearing resets the counter (no `(--unset)` survivors poisoning future reads).+ assert!(repo.clear_hint("escalating").unwrap());+ assert_eq!(repo.hint_count("escalating"), 0);+ assert!(!repo.has_shown_hint("escalating"));+ }++ /// Legacy `worktrunk.hints.<name> = "true"` values (written before the+ /// counter migration) parse as 0, so `mark_hint_shown` resets them to 1.+ /// This is the documented migration choice — a legacy user starts their+ /// counter from zero, but `has_shown_hint` continues to report `true` so+ /// any "first-time only" branches still treat them as having seen it.+ #[test]+ fn test_hint_count_legacy_true_resets_to_one() {+ let test = TestRepo::with_initial_commit();+ let repo = Repository::at(test.root_path()).unwrap();++ // Simulate a pre-migration repo by writing the literal "true" value.+ repo.set_config("worktrunk.hints.legacy", "true").unwrap();+ assert!(repo.has_shown_hint("legacy"));+ assert_eq!(repo.hint_count("legacy"), 0);++ // Next mark normalises to 1 (not 2 — legacy "shown once" is dropped).+ repo.mark_hint_shown("legacy").unwrap();+ assert_eq!(repo.hint_count("legacy"), 1);++ // From there, normal increment behaviour resumes.+ repo.mark_hint_shown("legacy").unwrap();+ assert_eq!(repo.hint_count("legacy"), 2);+ }}diff --git a/src/output/handlers.rs b/src/output/handlers.rsindex 439cb0495..9bbe39937 100644--- a/src/output/handlers.rs+++ b/src/output/handlers.rs@@ -36,7 +36,7 @@ use worktrunk::styling::{use super::shell_integration::{compute_shell_warning_reason, explicit_path_hint, git_subcommand_warning,- shell_integration_hint, should_show_explicit_path_hint,+ print_shell_integration_hint, should_show_explicit_path_hint,};// ============================================================================@@ -591,7 +591,7 @@ fn print_switch_message_if_changed(if should_show_explicit_path_hint() {eprintln!("{}", hint_message(explicit_path_hint(&dest_branch)));} else {- eprintln!("{}", hint_message(shell_integration_hint()));+ print_shell_integration_hint(&repo);}}Ok(())@@ -1736,12 +1736,6 @@ mod tests {assert_eq!(result, target);}- #[test]- fn test_shell_integration_hint() {- let hint = shell_integration_hint();- assert_snapshot!(hint, @"To enable automatic cd, run [4mwt config shell install[24m");- }-#[test]fn test_git_subcommand_warning() {let warning = git_subcommand_warning();diff --git a/src/output/shell_integration.rs b/src/output/shell_integration.rsindex 4440687e1..ca9f72bd3 100644--- a/src/output/shell_integration.rs+++ b/src/output/shell_integration.rs@@ -62,6 +62,7 @@ use std::io::IsTerminal;use color_print::cformat;use worktrunk::config::UserConfig;+use worktrunk::git::Repository;use worktrunk::path::format_path_for_display;use worktrunk::shell::{Shell, current_shell, extract_filename_from_path};use worktrunk::styling::{@@ -73,12 +74,39 @@ use crate::commands::configure_shell::{scan_shell_configs,};+/// Git config key tracking how many times the shell-integration install hint+/// has been shown to this user. Stored as an integer count via the generic+/// hints API; reaching 5 escalates the hint with a `wt config show` pointer.+pub(crate) const SHELL_INTEGRATION_HINT: &str = "shell-integration";+/// Shell integration install hint message.-// TODO(hints-count): After showing this hint 5+ times, suggest `wt config show` for diagnostics.-// This requires changing the hints infrastructure to track counts rather than booleans.-// See `Repository::mark_hint_shown()` and `list_shown_hints()` in src/git/repository/mod.rs.-pub(crate) fn shell_integration_hint() -> String {- cformat!("To enable automatic cd, run <underline>wt config shell install</>")+///+/// `count` is how many times the hint has previously been shown (i.e., the+/// current value of `worktrunk.hints.shell-integration`, before incrementing+/// for this display). After 5+ prior shows, append a diagnostic suggestion+/// pointing at `wt config show` so users who keep seeing this can investigate+/// why their shell wrapper isn't intercepting.+pub(crate) fn shell_integration_hint(count: u32) -> String {+ if count >= 5 {+ cformat!(+ "To enable automatic cd, run <underline>wt config shell install</>; if this keeps appearing, run <underline>wt config show</> to diagnose"+ )+ } else {+ cformat!("To enable automatic cd, run <underline>wt config shell install</>")+ }+}++/// Print the shell-integration install hint and bump its display counter.+///+/// Reads the current count from `worktrunk.hints.shell-integration`, formats+/// the hint (escalating at 5+), prints it, and persists `count + 1` so the+/// next display sees an updated value. The persist step is best-effort — if+/// `git config` fails, only the escalation is delayed, never the hint+/// itself, so we deliberately ignore the error.+pub(crate) fn print_shell_integration_hint(repo: &Repository) {+ let count = repo.hint_count(SHELL_INTEGRATION_HINT);+ eprintln!("{}", hint_message(shell_integration_hint(count)));+ let _ = repo.mark_hint_shown(SHELL_INTEGRATION_HINT);}/// Hint when shell integration is installed but shell needs restart.@@ -360,8 +388,12 @@ pub fn print_shell_install_result(/// Called after `wt switch` when shell integration is NOT active./// See module documentation for the complete decision flow.///+/// `repo` is threaded through so the install hint can read and bump+/// `worktrunk.hints.shell-integration`.+////// Returns `Ok(true)` if installed, `Ok(false)` otherwise.pub fn prompt_shell_integration(+ repo: &Repository,config: &mut UserConfig,binary_name: &str,skip_prompt: bool,@@ -379,13 +411,17 @@ pub fn prompt_shell_integration(// Only prompt if current shell is supported (so they benefit immediately)let shell_env = std::env::var("SHELL").ok();if current_shell().is_none() {- let msg = match &shell_env {- Some(path) => shell_integration_unsupported_shell(path),+ match &shell_env {+ Some(path) => {+ eprintln!(+ "{}",+ hint_message(shell_integration_unsupported_shell(path))+ );+ }// $SHELL not set: could be Windows PowerShell, or unusual Unix setup- // Point them to manual installation- None => shell_integration_hint(),- };- eprintln!("{}", hint_message(msg));+ // Point them to manual installation (and count it as a shown install hint)+ None => print_shell_integration_hint(repo),+ }return Ok(false);};@@ -396,7 +432,7 @@ pub fn prompt_shell_integration(// No config files exist - show install hintif scan.configured.is_empty() {- eprintln!("{}", hint_message(shell_integration_hint()));+ print_shell_integration_hint(repo);return Ok(false);}@@ -419,7 +455,7 @@ pub fn prompt_shell_integration(// Can't or shouldn't prompt - show install hintif config.skip_shell_integration_prompt || !is_tty || skip_prompt {- eprintln!("{}", hint_message(shell_integration_hint()));+ print_shell_integration_hint(repo);return Ok(false);}@@ -436,7 +472,7 @@ pub fn prompt_shell_integration(if !confirmed {// Only skip future prompts after explicit decline (not Ctrl+C)let _ = config.set_skip_shell_integration_prompt(None);- eprintln!("{}", hint_message(shell_integration_hint()));+ print_shell_integration_hint(repo);return Ok(false);}@@ -570,8 +606,25 @@ mod tests {#[test]fn test_shell_integration_hint() {- let hint = shell_integration_hint();- assert_snapshot!(hint, @"To enable automatic cd, run [4mwt config shell install[24m");+ // Below the escalation threshold — base message only.+ assert_snapshot!(+ shell_integration_hint(0),+ @"To enable automatic cd, run [4mwt config shell install[24m"+ );+ assert_snapshot!(+ shell_integration_hint(4),+ @"To enable automatic cd, run [4mwt config shell install[24m"+ );++ // At and above the escalation threshold — append diagnostic suggestion.+ assert_snapshot!(+ shell_integration_hint(5),+ @"To enable automatic cd, run [4mwt config shell install[24m; if this keeps appearing, run [4mwt config show[24m to diagnose"+ );+ assert_snapshot!(+ shell_integration_hint(10),+ @"To enable automatic cd, run [4mwt config shell install[24m; if this keeps appearing, run [4mwt config show[24m to diagnose"+ );}#[test]