writing-user-outputs

Output System Architecture

Shell Integration

Worktrunk uses file-based directive passing for shell integration:

1. Shell wrapper creates a temp file via mktemp
2. Shell wrapper sets WORKTRUNK_DIRECTIVE_FILE env var to the file path
3. wt writes shell commands (like cd '/path') to that file
4. Shell wrapper sources the file after wt exits

When WORKTRUNK_DIRECTIVE_FILE is not set (direct binary call), commands execute directly and shell integration hints are shown.

Output Functions

The output system handles shell integration automatically. Just call output functions — they do the right thing regardless of whether shell integration is active.

// NEVER DO THIS - don't check mode in command code
if is_shell_integration_active() {
    // different behavior
}

// ALWAYS DO THIS - just call output functions
eprintln!("{}", success_message("Created worktree"));
output::change_directory(&path)?;  // Writes to directive file if set, else no-op

Printing output:

Use eprintln! and println! from worktrunk::styling (re-exported from anstream for automatic color support and TTY detection):

use worktrunk::styling::{eprintln, println, stderr};

// Status messages to stderr
eprintln!("{}", success_message("Created worktree"));

// Primary output to stdout (tables, JSON, pipeable)
println!("{}", table_output);

// Flush before interactive prompts
stderr().flush()?;

Shell integration functions (src/output/global.rs):

Function	Purpose
change_directory(path)	Shell cd after wt exits (writes to directive file if set)
execute(command)	Shell command after wt exits
terminate_output()	Reset ANSI state on stderr
is_shell_integration_active()	Check if directive file set (rarely needed)
pre_hook_display_path(path)	Compute display path for pre-hooks
post_hook_display_path(path)	Compute display path for post-hooks

Message formatting functions (worktrunk::styling):

Function	Symbol	Color
success_message()	✓	green
progress_message()	◎	cyan
info_message()	○	symbol dim, text plain
warning_message()	▲	yellow
hint_message()	↳	dim
error_message()	✗	red
prompt_message()	❯	cyan

Section headings (worktrunk::styling):

use worktrunk::styling::format_heading;

// Plain heading
format_heading("BINARIES", None)  // => "BINARIES" (cyan)

// Heading with suffix
format_heading("USER CONFIG", Some("@ ~/.config/wt.toml"))
// => "USER CONFIG @ ~/.config/wt.toml" (title cyan, suffix plain)

stdout vs stderr

Decision principle: If this command is piped, what should the receiving program get?

• stdout → Data for pipes, scripts, eval (tables, JSON, shell code)
• stderr → Status for the human watching (progress, success, errors, hints)
• directive file → Shell commands executed after wt exits (cd, exec)

Examples:

• wt list → table/JSON to stdout (for grep, jq, scripts)
• wt config shell init → shell code to stdout (for eval)
• wt switch → status messages only (nothing to pipe)

Security

WORKTRUNK_DIRECTIVE_FILE is automatically removed from spawned subprocesses (via shell_exec::Cmd). This prevents hooks from writing to the directive file.

Windows Compatibility (Git Bash / MSYS2)

On Windows with Git Bash, mktemp returns POSIX-style paths like /tmp/tmp.xxx. The native Windows binary (wt.exe) needs a Windows path to write to the directive file.

No explicit path conversion is needed. MSYS2 automatically converts POSIX paths in environment variables when spawning native Windows binaries — shell wrappers can use $directive_file directly. See: https://www.msys2.org/docs/filesystem-paths/

---

CLI Output Formatting Standards

User Message Principles

Output messages should acknowledge user-supplied arguments (flags, options, values) by reflecting those choices in the message text.

// User runs: wt switch --create feature --base=main
// GOOD - acknowledges the base branch
"Created new worktree for feature from main @ /path/to/worktree"
// BAD - ignores the base argument
"Created new worktree for feature @ /path/to/worktree"

Avoid "you/your" pronouns: Messages should refer to things directly, not address the user. Imperatives like "Run", "Use", "Add" are fine — they're concise CLI idiom.

// BAD - "Use 'wt merge' to rebase your changes onto main"
// GOOD - "Use 'wt merge' to rebase onto main"

Avoid redundant parenthesized content: Parenthesized text should add new information, not restate what's already said.

// BAD - parentheses restate "no changes"
"No changes after squashing 3 commits (commits resulted in no net changes)"
// GOOD - clear and concise
"No changes after squashing 3 commits"
// GOOD - parentheses add supplementary info
"Committing with default message... (3 files, +45, -12)"

Two types of parenthesized content with different styling:

1. Stats parentheses → Gray ([90m bright-black): Supplementary numerical info that could be omitted without losing meaning.

   ✓ Merged to main (1 commit, 1 file, +1)
   ◎ Squashing 2 commits into a single commit (2 files, +2)...
   

2. Reason parentheses → Message color: Explains WHY an action is happening; integral to understanding.

   ◎ Removing feature worktree & branch in background (same commit as main, _)
   

Stats are truly optional context. Reasons answer "why is this safe/happening?" and belong with the main message. Symbols within reason parentheses still render in their native styling (see "Symbol styling" below).

Show path when hooks run in a different directory: When hooks run in a worktree other than the user's current (or eventual) location, show the path. Use the appropriate helper function:

1. Pre-hooks and manual wt hook — User is at cwd, no cd happens. Use output::pre_hook_display_path(hooks_run_at). Examples: pre-commit, pre-merge, pre-remove, manual wt hook post-merge.

2. Post-hooks — User will cd to destination if shell integration is active. Use output::post_hook_display_path(destination). Examples: pre-start, post-switch, post-start, post-merge (after removal).

// Pre-hooks: user is at cwd, no cd happens
run_hook_with_filter(..., crate::output::pre_hook_display_path(ctx.worktree_path))?;

// Post-hooks: user will cd to destination if shell integration active
ctx.spawn_post_start_commands(crate::output::post_hook_display_path(&destination))?;

Avoid pronouns with cross-message referents: Hints appear as separate messages from errors. Don't use pronouns like "it" that refer to something mentioned in the error message.

// BAD - "it" refers to branch name in error message
// Error: "Branch 'feature' not found"
// Hint:  "Use --create to create it"
// GOOD - self-contained hint
// Error: "Branch 'feature' not found"
// Hint:  "Use --create to create a new branch"

Heading Case

Use sentence case for help text headings: "Configuration files", "JSON output", "LLM commit messages".

Message Consistency Patterns

Use consistent punctuation and structure for related messages.

Ampersand for combined actions: Use & when a single operation does multiple things:

"Removing feature worktree & branch in background"
"Commands approved & saved to config"

Semicolon for joining clauses: Use semicolons to connect related information:

"Removing feature worktree in background; retaining branch (--no-delete-branch)"
"Branch unmerged; to delete, run <underline>wt remove -D</>"  // hint uses underline
"{tool} not authenticated; run <bold>{tool} auth login</>"       // warning uses bold

Explicit flag acknowledgment: Show flags in parentheses when they change behavior:

// GOOD - shows the flag explicitly
"Removing feature worktree in background; retaining branch (--no-delete-branch)"
// BAD - doesn't acknowledge user's explicit choice
"Removing feature worktree in background; retaining branch"

Flag locality: Place flag indicators adjacent to the concept they modify. Flags should appear immediately after the noun/action they affect, not at the end of the message:

// GOOD - (--force) is adjacent to "worktree" which it modifies
"Removing feature worktree (--force) & branch in background (same commit as main, _)"
// BAD - (--force) at end, disconnected from the worktree removal it enables
"Removing feature worktree & branch in background (same commit as main, _) (--force)"

This principle ensures readers can immediately understand what each annotation modifies.

Parallel structure: Related messages should follow the same pattern:

// GOOD - parallel structure with integration reason explaining branch deletion
// Target branch is bold; symbol uses its standard styling (dim for _ and ⊂)
"Removing feature worktree & branch in background (same commit as <bold>main</>, <dim>_</>)"  // Integrated
"Removing feature worktree in background; retaining unmerged branch"                          // Unmerged
"Removing feature worktree in background; retaining branch (--no-delete-branch)"              // User flag

Symbol styling: Symbols are atomic with their color — the styling is part of the symbol's identity, not a presentation choice. Each symbol has a defined appearance that must be preserved in all contexts:

• _ and ⊂ — dim (integration/safe-to-delete indicators)
• +N and -N — green/red (diff indicators)

When a symbol appears in a colored message (cyan progress, green success), close the message color before the symbol so it renders in its native styling. This requires breaking out of the message color and reopening it after the symbol. See FlagNote in src/output/handlers.rs for an example — it handles flag acknowledgment notes (like integra

---

Content truncated.