# How to Use tuicr with Git Worktrees and Different Working Directories

> Learn how to use tuicr with Git worktrees and different working directories. tuicr automatically detects worktree directories for live review of changes.

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

---

**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`](https://github.com/agavra/tuicr/blob/main/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:

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

```

This call, located at lines 24-35 of [`src/vcs/git/libgit2.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/local/.../worktree.json) files, as implemented in [`src/persistence/storage.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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:

```bash

# 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`](https://github.com/agavra/tuicr/blob/main/src/cli.rs) (lines 943-989) parses slugs containing the `worktree/<head>` component to locate the correct repository root:

```bash

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

```bash

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

```bash
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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/slug.rs)) for session isolation
- The `DiffSource::WorkingTree` variant in [`src/app/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/app/mod.rs) loads live file changes, enabling real-time review of worktree modifications
- Sessions persist to [`worktree.json`](https://github.com/agavra/tuicr/blob/main/worktree.json) files and automatically refresh when the worktree HEAD advances
- CLI commands in [`src/cli.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/slug.rs). The worktree slug includes the commit SHA (e.g., `worktree/9f2c3d7`), and sessions are stored in separate [`worktree.json`](https://github.com/agavra/tuicr/blob/main/worktree.json) files per [`src/persistence/storage.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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.