How to Launch Tuicr for the Working Tree: Complete CLI and API Guide

Launch Tuicr in working-tree mode by passing the -w or --working-tree flag to instantly review uncommitted changes without displaying the commit selector UI.

Tuicr is a terminal-based code review tool for Git, Mercurial, and Jujutsu repositories available at agavra/tuicr. When you need to review changes that haven't been committed yet, you can launch Tuicr for the working tree to skip the revision selection interface and jump straight into the diff view. This mode parses your unstaged and staged changes directly through the VCS backend and renders them immediately in the TUI.

Quick Start: Launching Tuicr in Working Tree Mode

To review uncommitted changes in your current repository, use the short or long flag:

# Short form

tuicr -w

# Long form

tuicr --working-tree

# With custom theme

tuicr -w --theme catppuccin-mocha

When you launch Tuicr with the working-tree flag, the application bypasses the commit selector and loads the unified diff of your current changes directly into the diff view.

How the Working Tree Flag Works Internally

Understanding the flag's journey from CLI argument to rendered diff helps explain Tuicr's architecture and assists in troubleshooting potential issues.

CLI Definition in src/cli.rs

The flag is defined using Clap in src/cli.rs at lines 90-98:

#[arg(short = 'w', long = "working-tree", action = ArgAction::SetTrue)]
working_tree: bool,

This sets CliArgs::working_tree to true when present. The flag conflicts with --file and --all-files (enforced via conflicts_with_all), preventing logical contradictions in the review scope.

Propagation Through main.rs

In src/main.rs, the main function parses arguments via parse_cli_args() (line 13). The flag propagates through two critical paths:

1. Direct forwarding: Lines 81-86 pass the value to AppStartupOptions when constructing App::new
2. Auto-enabling logic: Lines 68-71 automatically set working_tree = true if --path is provided without an explicit revision range (-r)

App Initialization and Diff Loading

Inside src/app/init.rs, the App::new constructor stores the working_tree value from AppStartupOptions. Later, App::ensure_diff (implemented in src/app/diff_load.rs) checks this flag to determine the diff source. When true, it calls vcs.get_working_tree_diff() instead of loading a revision range.

VCS Backend Implementation

Each version control backend implements get_working_tree_diff() to return the unified diff of unstaged plus staged changes:

• Git: src/vcs/git/libgit2.rs and src/vcs/git/cli.rs
• Mercurial: src/vcs/hg/mod.rs
• Jujutsu: src/vcs/jj/mod.rs

The backend aggregates both staged and unstaged modifications into a single diff stream that the UI renders in src/ui/diff_view.rs.

Combining Working Tree with Other Options

The working-tree flag interacts with other CLI options in specific ways:

• -r, --revisions (Additive): tuicr -r HEAD~3..HEAD -w shows the revision range plus current working tree changes
• -p, --path (Auto-enables): If used without -r, main.rs automatically enables working-tree mode (lines 68-71)
• --file (Conflicts): Mutually exclusive; cannot review a specific file path and the entire working tree simultaneously
• --all-files (Conflicts): Mutually exclusive with -w

Programmatic Usage in Rust

You can launch Tuicr for the working tree programmatically by constructing AppStartupOptions with working_tree: true:

use tuicr::cli::parse_cli_args;
use tuicr::app::{App, AppStartupOptions};

fn launch_working_tree() -> anyhow::Result<()> {
    // Parse CLI or construct args manually
    let args = parse_cli_args();
    
    // Create app with working-tree enabled
    let mut app = App::new(
        Default::default(), // theme
        None,               // comment types
        false,              // stdout
        AppStartupOptions {
            revisions: None,
            working_tree: true,  // Enable working tree mode
            path_filter: None,
            file_path: None,
            all_files: false,
            git_backend_preference: Default::default(),
            diff_whitespace_mode: Default::default(),
            commit_selection: Default::default(),
            pr_target: None,
            repo_url_override: None,
        },
    )?;

    // App now contains the working tree diff and is ready to run
    Ok(())
}

Summary

• Use tuicr -w or tuicr --working-tree to review uncommitted changes without the commit selector UI
• The flag is defined in src/cli.rs (lines 90-98) and propagates through src/main.rs into AppStartupOptions
• When enabled, src/app/diff_load.rs calls get_working_tree_diff() on the VCS backend instead of loading revision ranges
• You can combine -w with revision ranges (-r) to review both historical commits and current changes
• The flag auto-enables when using --path without --revisions, but conflicts with --file and --all-files

Frequently Asked Questions

Can I review both a commit range and the working tree simultaneously?

Yes. According to the Tuicr source code, the -w flag is additive. When you run tuicr -r HEAD~3..HEAD -w, Tuicr loads the specified revision range and appends the current working tree changes. The UI will display the combined diff, allowing you to review historical context alongside your uncommitted modifications.

Why does Tuicr automatically enable working-tree mode when I use --path?

In src/main.rs (lines 68-71), Tuicr contains logic that detects when you provide a path filter (--path or -p) without specifying a revision range (-r). In this scenario, the application assumes you want to review changes in that path that haven't been committed yet, so it automatically sets working_tree = true. This provides a streamlined workflow for reviewing pending changes in specific directories or files.

What VCS backends support working-tree mode in Tuicr?

Tuicr implements get_working_tree_diff() for Git, Mercurial (hg), and Jujutsu (jj). The Git implementation exists in both src/vcs/git/libgit2.rs and src/vcs/git/cli.rs, while Mercurial and Jujutsu implementations reside in src/vcs/hg/mod.rs and src/vcs/jj/mod.rs respectively. Each backend returns a unified diff containing both staged and unstaged changes for the current repository state.

Is working-tree mode compatible with the --file option?

No. The CLI parser in src/cli.rs explicitly defines --working-tree as mutually exclusive with --file and --all-files using Clap's conflicts_with_all constraint. This prevents ambiguous review scopes—you must choose between reviewing the entire working tree or reviewing a specific file path, as these options represent different selection strategies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}