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

> Instantly review uncommitted changes with Tuicr. Learn how to launch Tuicr in working-tree mode using the CLI and API for a faster workflow.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-01

---

**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:

```bash

# 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`](https://github.com/agavra/tuicr/blob/main/src/cli.rs)

The flag is defined using Clap in [`src/cli.rs`](https://github.com/agavra/tuicr/blob/main/src/cli.rs) at lines 90-98:

```rust
#[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`](https://github.com/agavra/tuicr/blob/main/main.rs)

In [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/libgit2.rs) and [`src/vcs/git/cli.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/cli.rs)
- **Mercurial**: [`src/vcs/hg/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/hg/mod.rs)
- **Jujutsu**: [`src/vcs/jj/mod.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`:

```rust
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`](https://github.com/agavra/tuicr/blob/main/src/cli.rs) (lines 90-98) and propagates through [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs) into `AppStartupOptions`
- When enabled, [`src/app/diff_load.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/libgit2.rs) and [`src/vcs/git/cli.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/cli.rs), while Mercurial and Jujutsu implementations reside in [`src/vcs/hg/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/hg/mod.rs) and [`src/vcs/jj/mod.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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.