How to Use tuicr with Git Worktrees and Different Working Directories

tuicr treats Git worktrees as first-class diff sources, automatically detecting worktree directories and enabling live review of working tree changes through the relativeworktrees libgit2 extension and worktree/<head> slug identifiers.

The agavra/tuicr repository provides a terminal-based code review tool that fully supports Git worktrees and alternate working directories. When you launch tuicr within a worktree, it automatically recognizes the directory structure and enables real-time diff tracking without requiring additional configuration. This guide explains how tuicr leverages libgit2 extensions and session slugging to seamlessly integrate with modern Git worktree workflows.

How tuicr Detects Git Worktrees

Under the hood, tuicr relies on a Git backend powered by libgit2 to discover repository metadata regardless of whether you are in the main checkout or a linked worktree. The detection logic resides in src/vcs/git/libgit2.rs, where the backend explicitly enables the relativeworktrees extension to support modern Git 2.48+ worktree configurations.

When detect_vcs() initializes the repository context, it calls Libgit2Backend::discover_from() to read the repository metadata. For worktrees created with worktree.useRelativePaths (the default in recent Git versions), the system invokes:

git2::opts::set_extensions(&["relativeworktrees"])

This call, located at lines 24-35 of src/vcs/git/libgit2.rs, allows libgit2 to open worktrees that use relative path configurations, ensuring tuicr can access the repository index and working tree files from any worktree directory.

Slug Format and Session Management

Once tuicr identifies a worktree, it generates a unique slug that encodes the diff source. According to the implementation in src/slug.rs (lines 135-158), worktree slugs follow the format:

agavra/tuicr@main/worktree/9f2c3d7

This structure combines the repository identifier, current branch name, and the HEAD commit SHA. The slug serves three critical functions:

• Session persistence: Worktree sessions are stored in local/.../worktree.json files, as implemented in src/persistence/storage.rs (lines 1167-1192)
• CLI targeting: You can reference the worktree directly using the slug in non-interactive commands
• Export metadata: Markdown exports include the session slug in the header for traceability

When the worktree HEAD advances, tuicr automatically refreshes the session or discards stale data if the branch diverges, ensuring you always review the correct commit state.

Live DiffSource and Real-Time Updates

The core abstraction enabling worktree support is the DiffSource enum defined in src/app/mod.rs. When operating in a worktree, tuicr uses DiffSource::WorkingTree or DiffSource::WorkingTreeAndCommits, both of which return true from includes_worktree_changes() (lines 614-620).

This boolean flag signals the UI to load live working tree files rather than static snapshots. Consequently, every time the interface refreshes—or when you manually trigger a reload with :e—tuicr recomputes the diff by calling get_working_tree_diff() on the VCS backend. This architecture means modifications made to files in the worktree while tuicr is running appear instantly in the review interface.

Launching tuicr in a Worktree Directory

To start a review session within a worktree, simply navigate to the worktree directory and launch the application:

# Create a worktree (Git 2.48+ automatically sets the relativeworktrees flag)

git worktree add -q ../tuicr-wt

# Change into the worktree directory

cd ../tuicr-wt

# Launch tuicr – it will automatically detect the worktree

tuicr

Upon startup, tuicr displays the session slug (e.g., agavra/tuicr@main/worktree/9f2c3d7) and loads the current working tree changes. Any comments you add are persisted to the worktree-specific session file.

Targeting Worktrees from Other Directories

You can interact with a worktree session from anywhere in your filesystem using the CLI and the worktree slug. The command-line handler in src/cli.rs (lines 943-989) parses slugs containing the worktree/<head> component to locate the correct repository root:

# From any directory, add a comment to a specific worktree

tuicr review add \
    --repo agavra/tuicr@main/worktree/9f2c3d7 \
    --file src/app/mod.rs \
    --line 618 \
    -m "Explain why worktree changes are included here"

This capability allows you to script interactions with worktrees without changing your current working directory.

Switching Between Main Checkout and Worktrees

Because tuicr maintains separate sessions for the main checkout and each worktree, you can run multiple review contexts simultaneously. Open one terminal in your main repository and another in the worktree:

# Terminal 1: Main checkout

tuicr   # shows main repo diff source

# Terminal 2: Worktree directory

cd ../tuicr-wt
tuicr   # shows worktree diff source

In the main checkout terminal, pressing :e reloads the interface to reflect any changes committed or modified in the worktree, provided the diff source includes working tree changes.

Exporting Worktree Sessions

Worktree sessions export identically to standard sessions. When you run :clip within tuicr, the generated markdown includes the worktree slug in the header:

tuicr :clip   # copies markdown to clipboard

# Output includes:

# ## Session: agavra/tuicr@main/worktree/9f2c3d7

This ensures exported reviews maintain context about which worktree and commit state they reference.

Summary

• tuicr enables the relativeworktrees libgit2 extension in src/vcs/git/libgit2.rs to support Git 2.48+ worktrees with relative paths
• Worktrees generate unique slugs in the format repo@branch/worktree/<head> (defined in src/slug.rs) for session isolation
• The DiffSource::WorkingTree variant in src/app/mod.rs loads live file changes, enabling real-time review of worktree modifications
• Sessions persist to worktree.json files and automatically refresh when the worktree HEAD advances
• CLI commands in src/cli.rs accept worktree slugs for remote interaction without directory switching

Frequently Asked Questions

Does tuicr require special configuration to recognize Git worktrees?

No configuration is required. When you launch tuicr inside a worktree directory, Libgit2Backend::discover_from() automatically detects the repository structure. The backend enables the relativeworktrees extension by calling git2::opts::set_extensions(&["relativeworktrees"]) at lines 24-35 of src/vcs/git/libgit2.rs, which handles modern Git worktrees that use relative paths by default.

How does tuicr handle session conflicts between the main repository and worktrees?

tuicr isolates sessions using the slug system defined in src/slug.rs. The worktree slug includes the commit SHA (e.g., worktree/9f2c3d7), and sessions are stored in separate worktree.json files per src/persistence/storage.rs. If the worktree HEAD changes, tuicr either refreshes the existing session or creates a new one, preventing conflicts with the main checkout or other worktrees.

Can I review changes in a worktree while simultaneously reviewing the main repository?

Yes. Because each worktree generates a distinct slug and maintains separate session persistence, you can run multiple tuicr instances simultaneously—one in the main checkout and others in various worktrees. The includes_worktree_changes() method in src/app/mod.rs ensures each instance tracks only the relevant working tree changes for its specific directory.

Why does tuicr use the relativeworktrees extension specifically?

Git 2.48+ creates worktrees using relative paths by default for portability. Without enabling the relativeworktrees extension, libgit2 cannot open these repositories. The code at src/vcs/git/libgit2.rs#L24-L35 explicitly activates this extension to ensure tuicr can access the repository metadata regardless of whether the worktree uses absolute or relative path references.

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