Skip to content

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

fix(help): silence user-config side effects on `wt step --help` (#2179)

Maximilian Roos56b00c849607
diff --git a/src/commands/alias.rs b/src/commands/alias.rs
index ed81c9b14..ae171b77a 100644
--- a/src/commands/alias.rs
+++ b/src/commands/alias.rs
@@ -435,6 +435,10 @@ enum AliasSource {
/// running outside a repository: user-config aliases still list,
/// project-config aliases just get skipped.
pub(crate) fn augment_step_help(help: &str) -> String {
+ // Help must not emit deprecation/unknown-field warnings or write `.new`
+ // migration files as a side effect of rendering the alias list.
+ worktrunk::config::suppress_warnings();
+
let aliases = load_aliases_for_listing();
if aliases.is_empty() {
return help.to_string();
@@ -519,11 +523,12 @@ fn render_aliases_section(entries: &[(String, CommandConfig, AliasSource)]) -> S
/// separately preserves the individual command text; merging them would
/// reduce to an uninformative step count when both are unnamed singles.
///
-/// Project config is parsed directly from TOML here instead of going through
-/// `ProjectConfig::load`, which emits deprecation/unknown-field warnings as a
-/// side effect. Help is an informational surface that should stay quiet —
-/// users see those warnings from `wt config show` and execution paths. The
-/// `aliases` table has no deprecated forms, so skipping the migration is safe.
+/// The caller (`augment_step_help`) latches `suppress_warnings()` before
+/// reaching here so the standard `UserConfig::load()` stays quiet: no
+/// deprecation warnings, no `.new` file writes, no approved-commands copy.
+/// Project config is parsed directly from TOML rather than via
+/// `ProjectConfig::load` because the `aliases` table has no deprecated forms
+/// — skipping the migration avoids the unrelated warnings entirely.
///
/// Tolerates missing or unloadable config: this is a discovery surface, not
/// an execution surface, so we'd rather show the built-in commands than
diff --git a/src/config/deprecation.rs b/src/config/deprecation.rs
index cbb3d162f..ba24e85f2 100644
--- a/src/config/deprecation.rs
+++ b/src/config/deprecation.rs
@@ -44,14 +44,21 @@ static WARNED_DEPRECATED_PATHS: LazyLock<Mutex<HashSet<PathBuf>>> =
static DEPRECATION_HINT_EMITTED: OnceLock<()> = OnceLock::new();
/// Latch that silences config deprecation/unknown-field warnings for the rest
-/// of the process. Set by shell completion and picker paths, where stderr
-/// output would appear above the user's prompt or TUI.
+/// of the process, and also suppresses `.new` migration file writes and the
+/// `approved-commands` → `approvals.toml` copy. Set by shell completion,
+/// picker, statusline, and help paths — surfaces where stderr output would
+/// appear above the user's prompt or TUI and filesystem side effects would
+/// surprise users who only asked to render output.
static SUPPRESS_WARNINGS: OnceLock<()> = OnceLock::new();
pub fn suppress_warnings() {
let _ = SUPPRESS_WARNINGS.set(());
}
+fn warnings_suppressed() -> bool {
+ SUPPRESS_WARNINGS.get().is_some()
+}
+
/// Pre-compiled regexes for deprecated variable word-boundary matching.
/// Compiled once on first use, shared across all calls to normalize/replace.
static DEPRECATED_VAR_REGEXES: LazyLock<Vec<(Regex, &'static str)>> = LazyLock::new(|| {
@@ -1220,14 +1227,21 @@ pub fn check_and_migrate(
// Copy approved-commands to approvals.toml before generating the migration
// file that removes them from config.toml. Without this, applying the
// migration (`mv config.toml.new config.toml`) would lose approval data.
- if info.deprecations.approved_commands {
+ // Skip when warnings are suppressed — help/completion/picker surfaces
+ // must not mutate the filesystem.
+ if info.deprecations.approved_commands && !warnings_suppressed() {
info.approvals_copied_to = copy_approved_commands_to_approvals_file(path);
}
+ // Writes are suppressed alongside warnings on passive display surfaces
+ // (help, completion, picker, statusline). The next config-modifying
+ // command will re-detect and write the migration file.
+ let should_write = !should_skip_write && !warnings_suppressed();
+
// For non-config-show commands, emit per-kind warnings but skip the diff.
// The diff is reserved for `wt config show`, where the user has opted into details.
if emit_inline_warnings {
- if SUPPRESS_WARNINGS.get().is_none() {
+ if !warnings_suppressed() {
eprint!("{}", format_deprecation_warnings(&info));
if DEPRECATION_HINT_EMITTED.set(()).is_ok() {
eprintln!(
@@ -1254,7 +1268,7 @@ pub fn check_and_migrate(
// Still write migration file if needed (first time only)
// The file is needed for `wt config update` / `wt config show` to work
- if !should_skip_write {
+ if should_write {
info.migration_path =
write_migration_file(path, content, &info.deprecations, repo, &template_strings);
}
@@ -1268,7 +1282,7 @@ pub fn check_and_migrate(
// Silent mode for `wt config show` - just write migration file and return info
// The caller will use format_deprecation_details() to add output to its buffer
- if !should_skip_write {
+ if should_write {
info.migration_path =
write_migration_file(path, content, &info.deprecations, repo, &template_strings);
}
@@ -1603,7 +1617,7 @@ pub fn warn_unknown_fields<C: WorktrunkConfig>(
unknown_keys: &HashMap<String, toml::Value>,
label: &str,
) {
- if unknown_keys.is_empty() || SUPPRESS_WARNINGS.get().is_some() {
+ if unknown_keys.is_empty() || warnings_suppressed() {
return;
}
diff --git a/tests/integration_tests/step_alias.rs b/tests/integration_tests/step_alias.rs
index 3910cb55a..ad4bad9f4 100644
--- a/tests/integration_tests/step_alias.rs
+++ b/tests/integration_tests/step_alias.rs
@@ -1113,6 +1113,39 @@ deploy = "make deploy BRANCH={{ branch }}"
));
}
+/// `wt step --help` must not emit deprecation warnings or write `.new`
+/// migration files when the user config contains deprecated patterns —
+/// help is a discovery surface, not an execution surface, and the user
+/// will see those warnings from `wt config show` and normal commands.
+#[cfg(not(windows))]
+#[rstest]
+fn test_step_help_silent_with_deprecated_user_config(repo: TestRepo) {
+ // Deprecated `main_worktree` template variable — migrated to `repo`.
+ repo.write_test_config(
+ r#"worktree-path = "../{{ main_worktree }}.{{ branch }}"
+"#,
+ );
+ let migration_file = repo.test_config_path().with_extension("toml.new");
+
+ let output = repo.wt_command().args(["step", "--help"]).output().unwrap();
+
+ assert!(
+ output.status.success(),
+ "step --help should succeed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert_eq!(
+ stderr, "",
+ "step --help must emit no stderr on deprecated user config"
+ );
+ assert!(
+ !migration_file.exists(),
+ "step --help must not write .new migration file at {}",
+ migration_file.display()
+ );
+}
+
/// Declining approval prevents alias execution
#[rstest]
fn test_alias_approval_decline(mut repo: TestRepo) {