fix: warn when --config path doesn't exist, fix shell quoting in docs (#895)

* fix: warn when --config path doesn't exist, fix shell quoting in docs

Bug fixes from adversarial testing:

1. --config path warning: When users pass --config with a non-existent
   file path, wt now warns instead of silently falling back to defaults.
   Note: WORKTRUNK_CONFIG_PATH env var doesn't trigger this warning since
   it's commonly used for test isolation with intentionally absent paths.

2. Shell quoting in docs: Template variables are automatically shell-escaped,
   so user-added quotes cause issues with special characters. Fixed examples
   in hook docs and tips-patterns that incorrectly showed quoted variables.

Also adds:
- Test verifying --squash is correctly ignored with --no-commit
- Tests for ANSI escape sequence handling in branch names

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: skip ANSI branch name test on Windows

Git for Windows with MSYS2 bash behaves differently and may accept
branch names containing control characters. The test verifies Unix git
behavior, so restrict it to Unix platforms.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: max-sixty

.claude-plugin/skills/worktrunk/reference/hook.md

@@ -48,7 +48,7 @@ Triggers on all switch results: creating new worktrees, switching to existing on
 
 ```toml
 [post-switch]
-tmux = "[ -n \"$TMUX\" ] && tmux rename-window '{{ branch | sanitize }}'"
+tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
 ```
 
 ### pre-commit
@@ -223,6 +223,8 @@ Hash any string, including concatenations:
 dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"
 ```
 
+Variables are shell-escaped automatically — quotes around `{{ ... }}` are unnecessary and can cause issues with special characters.
+
 ### Worktrunk functions
 
 Templates also support functions for dynamic lookups:
@@ -378,9 +380,9 @@ Different actions for production vs staging:
 
 ```toml
 post-merge = """
-if [ "{{ target }}" = "main" ]; then
+if [ {{ target }} = main ]; then
     npm run deploy:production
-elif [ "{{ target }}" = "staging" ]; then
+elif [ {{ target }} = staging ]; then
     npm run deploy:staging
 fi
 """

.claude-plugin/skills/worktrunk/reference/tips-patterns.md

@@ -212,8 +212,8 @@ Each worktree gets its own tmux session with a multi-pane layout. Sessions are n
 # .config/wt.toml
 [post-create]
 tmux = """
-S="{{ branch | sanitize }}"
-W="{{ worktree_path }}"
+S={{ branch | sanitize }}
+W={{ worktree_path }}
 tmux new-session -d -s "$S" -c "$W" -n dev
 
 # Create 4-pane layout: shell | backend / claude | frontend
@@ -231,7 +231,7 @@ echo "✓ Session '$S' — attach with: tmux attach -t $S"
 """
 
 [pre-remove]
-tmux = "tmux kill-session -t '{{ branch | sanitize }}' 2>/dev/null || true"
+tmux = "tmux kill-session -t {{ branch | sanitize }} 2>/dev/null || true"
 ```
 
 `pre-remove` stops all services when the worktree is removed.

docs/content/hook.md

@@ -56,7 +56,7 @@ Triggers on all switch results: creating new worktrees, switching to existing on
 
 ```toml
 [post-switch]
-tmux = "[ -n \"$TMUX\" ] && tmux rename-window '{{ branch | sanitize }}'"
+tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
 ```
 
 ### pre-commit
@@ -231,6 +231,8 @@ Hash any string, including concatenations:
 dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"
 ```
 
+Variables are shell-escaped automatically — quotes around `{{ ... }}` are unnecessary and can cause issues with special characters.
+
 ### Worktrunk functions
 
 Templates also support functions for dynamic lookups:
@@ -386,9 +388,9 @@ Different actions for production vs staging:
 
 ```toml
 post-merge = """
-if [ "{{ target }}" = "main" ]; then
+if [ {{ target }} = main ]; then
     npm run deploy:production
-elif [ "{{ target }}" = "staging" ]; then
+elif [ {{ target }} = staging ]; then
     npm run deploy:staging
 fi
 """

docs/content/tips-patterns.md

@@ -224,8 +224,8 @@ Each worktree gets its own tmux session with a multi-pane layout. Sessions are n
 # .config/wt.toml
 [post-create]
 tmux = """
-S="{{ branch | sanitize }}"
-W="{{ worktree_path }}"
+S={{ branch | sanitize }}
+W={{ worktree_path }}
 tmux new-session -d -s "$S" -c "$W" -n dev
 
 # Create 4-pane layout: shell | backend / claude | frontend
@@ -243,7 +243,7 @@ echo "✓ Session '$S' — attach with: tmux attach -t $S"
 """
 
 [pre-remove]
-tmux = "tmux kill-session -t '{{ branch | sanitize }}' 2>/dev/null || true"
+tmux = "tmux kill-session -t {{ branch | sanitize }} 2>/dev/null || true"
 ```
 
 `pre-remove` stops all services when the worktree is removed.

src/cli/mod.rs

@@ -1086,7 +1086,7 @@ Triggers on all switch results: creating new worktrees, switching to existing on
 
 ```toml
 [post-switch]
-tmux = "[ -n \"$TMUX\" ] && tmux rename-window '{{ branch | sanitize }}'"
+tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
 ```
 
 ### pre-commit
@@ -1261,6 +1261,8 @@ Hash any string, including concatenations:
 dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"
 ```
 
+Variables are shell-escaped automatically — quotes around `{{ ... }}` are unnecessary and can cause issues with special characters.
+
 ### Worktrunk functions
 
 Templates also support functions for dynamic lookups:
@@ -1416,9 +1418,9 @@ Different actions for production vs staging:
 
 ```toml
 post-merge = """
-if [ "{{ target }}" = "main" ]; then
+if [ {{ target }} = main ]; then
     npm run deploy:production
-elif [ "{{ target }}" = "staging" ]; then
+elif [ {{ target }} = staging ]; then
     npm run deploy:staging
 fi
 """

src/config/user/mod.rs

@@ -152,6 +152,17 @@ impl UserConfig {
             }
 
             builder = builder.add_source(File::from(config_path.clone()));
+        } else if let Some(config_path) = config_path.as_ref()
+            && path::is_config_path_explicit()
+        {
+            // Warn if user explicitly specified a config path that doesn't exist
+            crate::styling::eprintln!(
+                "{}",
+                crate::styling::warning_message(format!(
+                    "Config file not found: {}",
+                    config_path.display()
+                ))
+            );
         }
 
         // Add environment variables with WORKTRUNK prefix

src/config/user/path.rs

@@ -17,6 +17,15 @@ pub fn set_config_path(path: PathBuf) {
     CONFIG_PATH.set(path).ok();
 }
 
+/// Check if the config path was explicitly specified via --config CLI flag.
+///
+/// Returns true only if --config flag was used. Environment variable
+/// (WORKTRUNK_CONFIG_PATH) is not considered "explicit" because it's commonly
+/// used for test/CI isolation with intentionally non-existent paths.
+pub fn is_config_path_explicit() -> bool {
+    CONFIG_PATH.get().is_some()
+}
+
 /// Get the user config file path.
 ///
 /// Priority:

tests/integration_tests/config_show.rs

@@ -1,5 +1,6 @@
 use crate::common::{
-    TestRepo, repo, set_temp_home_env, setup_snapshot_settings_with_home, temp_home, wt_command,
+    TestRepo, repo, set_temp_home_env, setup_snapshot_settings, setup_snapshot_settings_with_home,
+    temp_home, wt_command,
 };
 use insta_cmd::assert_cmd_snapshot;
 use rstest::rstest;
@@ -1750,3 +1751,20 @@ command = "llm -m gpt-4"
         migration_file
     );
 }
+
+/// Test that explicitly specified --config path that doesn't exist shows a warning
+#[rstest]
+fn test_explicit_config_path_not_found_shows_warning(repo: TestRepo) {
+    let settings = setup_snapshot_settings(&repo);
+    settings.bind(|| {
+        let mut cmd = wt_command();
+        repo.configure_wt_cmd(&mut cmd);
+        cmd.arg("--config")
+            .arg("/nonexistent/worktrunk/config.toml")
+            .arg("list")
+            .current_dir(repo.root_path());
+
+        // Should show warning about missing config file but still succeed
+        assert_cmd_snapshot!(cmd);
+    });
+}

tests/integration_tests/merge.rs

@@ -2015,3 +2015,27 @@ fn test_step_rebase_accepts_tag(mut repo: TestRepo) {
         Some(&feature_wt)
     ));
 }
+
+// =============================================================================
+// Behavior verification: --squash with --no-commit
+// =============================================================================
+
+/// Verify that `--squash` is correctly ignored when `--no-commit` is passed.
+///
+/// This is expected behavior: squashing creates a single commit from multiple
+/// commits. If `--no-commit` is passed, there's no commit to create, so squash
+/// has no effect. The merge proceeds as a fast-forward to the target.
+#[rstest]
+fn test_merge_squash_ignored_with_no_commit(repo_with_multi_commit_feature: TestRepo) {
+    let repo = &repo_with_multi_commit_feature;
+    let feature_wt = &repo.worktrees["feature"];
+
+    // With --no-commit, squash has no effect - the merge fast-forwards
+    // to main without creating any new commits
+    assert_cmd_snapshot!(make_snapshot_cmd(
+        repo,
+        "merge",
+        &["main", "--squash", "--no-commit", "--no-remove"],
+        Some(feature_wt)
+    ));
+}

tests/integration_tests/security.rs

@@ -432,3 +432,109 @@ fn test_execute_flag_with_directive_like_branch_name(repo: TestRepo) {
         "Malicious code was executed alongside legitimate -x command!"
     );
 }
+
+// =============================================================================
+// ANSI escape sequence handling in branch names
+// =============================================================================
+
+/// Test that git rejects branch names containing ANSI escape sequences.
+///
+/// ANSI escape sequences could theoretically corrupt terminal output if they
+/// appeared in branch names displayed by `wt list`. However, git blocks this
+/// at the ref validation level: control characters (bytes < 0x20 or 0x7F)
+/// are rejected by git check-ref-format rule 4.
+///
+/// The escape character (`\x1b` = 27) is a control character, so git rejects it.
+///
+/// Note: Git for Windows with MSYS2 bash behaves differently and may accept
+/// these branch names, so this test is Unix-only.
+#[rstest]
+#[cfg(unix)]
+fn test_git_rejects_ansi_escape_in_branch_names(repo: TestRepo) {
+    let shell_cmd = r#"git branch $'feature-\x1b[31mRED\x1b[0m-test'"#;
+
+    let output = Command::new("bash")
+        .args(["-c", shell_cmd])
+        .current_dir(repo.root_path())
+        .output()
+        .unwrap();
+
+    assert!(
+        !output.status.success(),
+        "Expected git to reject ANSI escape sequences in branch name"
+    );
+
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("not a valid branch name") || stderr.contains("invalid"),
+        "Expected git to complain about invalid branch name, got: {}",
+        stderr
+    );
+}
+
+/// Test that manually created refs with ANSI escapes are ignored by git.
+///
+/// Even if an attacker bypasses git's normal validation and creates a ref file
+/// directly in .git/refs/heads/ with ANSI codes in the filename, git ignores it.
+#[rstest]
+#[cfg(unix)]
+fn test_git_ignores_malformed_refs_with_ansi(repo: TestRepo) {
+    let shell_cmd = r#"
+        commit_sha=$(git rev-parse HEAD)
+        printf "$commit_sha" > '.git/refs/heads/feature-'$'\x1b''[31mRED'$'\x1b''[0m-test'
+        "#;
+
+    let create_result = Command::new("bash")
+        .args(["-c", shell_cmd])
+        .current_dir(repo.root_path())
+        .output()
+        .unwrap();
+
+    assert!(
+        create_result.status.success(),
+        "Failed to create malformed ref file: {}",
+        String::from_utf8_lossy(&create_result.stderr)
+    );
+
+    // Git should ignore the malformed ref
+    let branch_output = repo.git_output(&["branch", "-a"]);
+    assert!(
+        !branch_output.contains("RED"),
+        "Malformed ref with ANSI escape should not appear in branch list"
+    );
+
+    // wt list should also not show it
+    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());
+        assert_cmd_snapshot!(cmd);
+    });
+}
+
+/// Test that literal escape-like text in branch names displays safely.
+///
+/// Branch names like "fix-backslash-x1b-test" contain literal characters
+/// (not actual escape codes). Git allows this and they should display literally.
+#[rstest]
+fn test_literal_escape_like_branch_names_displayed_safely(repo: TestRepo) {
+    let branch_name = "fix-backslash-x1b-test";
+
+    let result = repo.git_command().args(["branch", branch_name]).output();
+
+    if let Ok(output) = result
+        && output.status.success()
+    {
+        let mut settings = setup_snapshot_settings(&repo);
+        settings.add_filter(r"\b[0-9a-f]{7,40}\b", "[SHA]");
+
+        settings.bind(|| {
+            let mut cmd = wt_command();
+            repo.configure_wt_cmd(&mut cmd);
+            cmd.args(["list", "--branches"])
+                .current_dir(repo.root_path());
+            assert_cmd_snapshot!(cmd);
+        });
+    }
+}