# How to Configure the Git Backend in Tuicr

> Configure the Git backend in Tuicr using libgit2 for performance or cli for compatibility. Learn how to set up your Git backend via config.toml or the command line.

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

---

**Tuicr supports two Git backends—`libgit2` for performance and `cli` for compatibility—that you can configure via [`config.toml`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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:

```toml

# $XDG_CONFIG_HOME/tuicr/config.toml

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

```

The configuration parsing logic resides in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs), which makes the `backend` value available to the application. In [`src/vcs/git/mod.rs`](https://github.com/agavra/tuicr/blob/main/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:

```bash

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

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

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