Skip to content

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.rs
index 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 hints
diff --git a/src/commands/worktree/switch.rs b/src/commands/worktree/switch.rs
index 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 fails
if 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 and
diff --git a/src/git/repository/config.rs b/src/git/repository/config.rs
index 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_count
pub 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.rs
index 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 wt config shell install");
- }
-
#[test]
fn test_git_subcommand_warning() {
let warning = git_subcommand_warning();
diff --git a/src/output/shell_integration.rs b/src/output/shell_integration.rs
index 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 hint
if 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 hint
if 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 wt config shell install");
+ // Below the escalation threshold — base message only.
+ assert_snapshot!(
+ shell_integration_hint(0),
+ @"To enable automatic cd, run wt config shell install"
+ );
+ assert_snapshot!(
+ shell_integration_hint(4),
+ @"To enable automatic cd, run wt config shell install"
+ );
+
+ // At and above the escalation threshold — append diagnostic suggestion.
+ assert_snapshot!(
+ shell_integration_hint(5),
+ @"To enable automatic cd, run wt config shell install; if this keeps appearing, run wt config show to diagnose"
+ );
+ assert_snapshot!(
+ shell_integration_hint(10),
+ @"To enable automatic cd, run wt config shell install; if this keeps appearing, run wt config show to diagnose"
+ );
}
#[test]