How to Configure the Git Backend in Tuicr

Tuicr supports two Git backends—libgit2 for performance and cli for compatibility—that you can configure via config.toml or the --backend command-line flag.

Tuicr, the terminal-based code review tool, provides flexible Git integration through pluggable backend implementations. Depending on your repository structure and performance requirements, you can switch between a high-performance native library or a command-line fallback. This guide covers the configuration mechanisms in agavra/tuicr that control Git backend selection.

Available Git Backend Options

Tuicr implements two distinct strategies for Git operations:

• libgit2 — The default backend that uses the git2 Rust library for direct repository access. This option provides the fastest performance for standard Git workflows and is the preferred choice for most repositories.

• cli — A fallback backend that shells out to the Git CLI (git …). Tuicr automatically selects this option when it detects repository configurations that the libgit2 backend cannot handle, such as sparse checkouts.

Configuring the Backend via config.toml

Tuicr loads user preferences from a configuration file at startup. By default, it searches for config.toml at $XDG_CONFIG_HOME/tuicr/config.toml on Linux/macOS or %APPDATA%\tuicr\config.toml on Windows.

To explicitly set your preferred backend, add the backend key to this file:

# $XDG_CONFIG_HOME/tuicr/config.toml

backend = "cli"      # Options: "libgit2" or "cli"

The configuration parsing logic resides in src/config/mod.rs, which makes the backend value available to the application. In src/vcs/git/mod.rs, the GitBackendPreference::from_config function (lines 413–419) processes this entry to determine which implementation to instantiate.

Overriding with Command-Line Flags

You can override the configuration file setting for a single session using the --backend flag. This is useful for testing different backends without modifying persistent configuration:

# Force the CLI backend for this run

tuicr --backend cli

# Force libgit2 backend

tuicr --backend libgit2

The argument parsing logic that handles the --backend flag is implemented in src/main.rs alongside other CLI options.

Automatic Backend Selection and Sparse Checkout Detection

When no explicit backend is configured, Tuicr automatically selects the appropriate implementation based on repository characteristics. The detection logic in src/vcs/mod.rs (specifically the detect_vcs() function at lines 324–340) inspects the repository state before constructing the backend.

If Tuicr detects sparse checkout configuration—indicated by the presence of core.sparsecheckout or index.sparse in the Git config—it forces the CLI backend and emits a startup warning. This safety mechanism ensures compatibility with advanced Git features that libgit2 may not support. You can observe this behavior in the test derives_git_repo_mode_from_config at lines 400–405 in src/vcs/git/mod.rs.

To verify which backend Tuicr has selected, run the application with the --verbose flag:

tuicr --verbose

# Output example:

#   Detected Git repo at /path/to/repo

#   Using Git backend: cli   # Automatically selected due to sparse checkout

Summary

• Tuicr provides two Git backends: libgit2 (default, high-performance) and cli (compatibility fallback).
• Configuration file location: $XDG_CONFIG_HOME/tuicr/config.toml (Linux/macOS) or %APPDATA%\tuicr\config.toml (Windows).
• Key configuration: Set backend = "cli" or backend = "libgit2" in config.toml.
• Command override: Use --backend cli or --backend libgit2 for temporary changes.
• Automatic fallback: Repositories with sparse checkout automatically trigger the CLI backend unless explicitly overridden in configuration.

Frequently Asked Questions

What is the default Git backend in Tuicr?

The default backend is libgit2, which utilizes the git2 Rust library for high-performance Git operations. However, if Tuicr detects a sparse checkout configuration in the repository, it automatically switches to the cli backend to ensure compatibility.

How do I force Tuicr to use the Git CLI backend?

You can force the CLI backend by either adding backend = "cli" to your config.toml file or by launching Tuicr with the --backend cli command-line flag. The flag overrides the configuration file for that specific session.

Why does Tuicr switch to the CLI backend automatically?

Tuicr switches to the CLI backend automatically when it detects repository configurations that require features not supported by libgit2, specifically sparse checkouts (identified by core.sparsecheckout or index.sparse settings). This automatic fallback prevents errors when working with partially checked-out repositories.

Where is the Tuicr configuration file located?

Tuicr searches for config.toml in your system's configuration directory. On Linux and macOS, this is $XDG_CONFIG_HOME/tuicr/config.toml (typically ~/.config/tuicr/config.toml). On Windows, the path is %APPDATA%\tuicr\config.toml.

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