How to Use tuicr with Git Sparse Checkouts: Choosing Between libgit2 and CLI Backends

tuicr automatically detects sparse-checkout repositories and falls back from the default libgit2 backend to the CLI backend, while allowing explicit control via the backend setting in config.toml.

Managing large repositories with Git sparse checkouts requires tools that understand the sparse-index format. The tuicr terminal UI code reviewer handles these repositories seamlessly by inspecting repository state at startup and selecting the appropriate Git backend implementation to ensure full compatibility.

How tuicr Auto-Detects the Git Backend

When tuicr initializes, the detect_vcs function calls GitBackend::discover to determine which backend implementation to use. By default, tuicr attempts to use the libgit2 backend (GitBackend::Libgit2Backend) for optimal performance.

The discovery logic in src/vcs/git/mod.rs checks repository capabilities before finalizing the backend selection:

// src/vcs/git/mod.rs (excerpt)
// libgit2 doesn't support reftable or split-index repositories,
// so we fallback to cli
if repo_has_sparse_checkout(&repo) {
    return Ok(GitBackend::Cli(...));
}

If the repository uses sparse checkout, reftable, or split-index features, tuicr immediately instantiates the CLI backend (GitBackend::Cli) instead. This fallback occurs at lines 167-169 of the Git module, ensuring that tuicr never attempts to use libgit2 with incompatible repository formats.

Why Sparse Checkouts Require the CLI Backend

The libgit2 library cannot parse the sparse-checkout index format, making it unsuitable for repositories where core.sparseCheckout is enabled or the .git/info/sparse-checkout file exists. During the discovery phase, tuicr explicitly checks for these conditions to prevent runtime errors.

The detection mechanism inspects both the Git configuration and the filesystem:

fn discover(preference: GitBackendPreference, ws: DiffWhitespaceMode) -> Result<Self> {
    // ... open repository with libgit2
    if is_sparse(&repo) {
        // fallback to CLI backend
        return Ok(Self::Cli(...));
    }
    // otherwise keep libgit2
}

When any sparse-checkout indicator is present, tuicr bypasses libgit2 entirely and delegates all Git operations—diff generation, log retrieval, and commit listing—to the system git executable via the CLI backend.

Explicit Backend Configuration

You can override the auto-detection logic by setting the backend key in your tuicr configuration file. The configuration parser in src/config/mod.rs validates this setting against allowed values at lines 392-398:

// src/config/mod.rs (excerpt)
backend: read_enum(table, "backend", &["libgit2", "cli"], &mut warnings),

To force a specific backend, create or edit ~/.config/tuicr/config.toml:

# ~/.config/tuicr/config.toml

backend = "cli"   # or "libgit2"

Setting backend = "cli" forces tuicr to use the Git executable for all operations, eliminating the warning message even in sparse repositories. Conversely, setting backend = "libgit2" instructs tuicr to attempt libgit2 first, though it will still automatically fallback to CLI if a sparse checkout is detected, accompanied by a startup warning.

Runtime Behavior and Startup Warnings

When tuicr detects a sparse checkout during startup, it emits a clear warning to stderr before continuing operation:

Warning: Sparse checkout detected – switching to Git CLI backend

This warning confirms that the system git executable will handle all version control operations, ensuring correct behavior with sparse-checkout semantics. Once the CLI backend is active, commands such as diff viewing, blame annotation, and branch comparison execute through subprocess calls to git rather than through libgit2's Rust bindings.

When to Use Each Backend

libgit2 is the preferred backend for standard repositories due to its pure-Rust implementation and elimination of subprocess overhead. CLI is required for sparse checkouts and recommended for debugging scenarios where you need tuicr's output to match native Git command output exactly.

Scenario	Recommended Backend	Reason
Normal repository (full checkout)	libgit2	Faster execution, no external process spawn
Sparse-checkout enabled repository	CLI (auto-fallback)	libgit2 cannot read sparse index format
Debugging Git behavior	CLI (forced)	Output mirrors native git commands
Eliminating Git dependency	libgit2	Pure Rust solution, no shell required

Practical Configuration Examples

Automatic Fallback (Default Behavior)

In a sparse-checkout repository, tuicr handles backend selection automatically:

# Initialize sparse checkout

git sparse-checkout init --cone
git sparse-checkout set src/

# Run tuicr - automatically detects sparse checkout and uses CLI backend

tuicr

Force CLI Backend Permanently

To suppress the startup warning and always use the Git executable:

# ~/.config/tuicr/config.toml

backend = "cli"

# CLI backend used regardless of repository type

tuicr

Attempt libgit2 with Fallback

To prefer libgit2 but allow automatic CLI fallback for sparse checkouts:

# ~/.config/tuicr/config.toml

backend = "libgit2"

# Attempts libgit2 first; switches to CLI with warning if sparse checkout detected

tuicr

Summary

• tuicr defaults to the libgit2 backend for performance but automatically detects repository features that require the CLI backend.
• Sparse-checkout repositories trigger an automatic fallback to the CLI backend because libgit2 does not support the sparse-index format.
• The backend selection logic resides in src/vcs/git/mod.rs, specifically within the GitBackend::discover function.
• Users can force a specific backend via the backend configuration key in ~/.config/tuicr/config.toml, validated in src/config/mod.rs.
• When auto-fallback occurs, tuicr prints a startup warning indicating the switch to the Git CLI backend.

Frequently Asked Questions

Does tuicr support Git sparse checkouts?

Yes. When tuicr detects a sparse-checkout repository (by checking core.sparseCheckout configuration or the .git/info/sparse-checkout file), it automatically switches to the CLI backend to ensure compatibility. This happens in src/vcs/git/mod.rs during the backend discovery phase.

Can I force tuicr to use libgit2 with a sparse checkout?

You can set backend = "libgit2" in your config.toml, but tuicr will still detect the sparse checkout and fallback to the CLI backend with a warning. The auto-detection logic takes precedence over preferences when repository incompatibilities are detected.

Where is the tuicr configuration file located?

tuicr reads configuration from ~/.config/tuicr/config.toml on Unix-like systems. The backend key accepts "libgit2" or "cli" values, parsed and validated in src/config/mod.rs at lines 392-398.

Which backend provides better performance?

The libgit2 backend generally offers better performance because it avoids the overhead of spawning external processes. However, for sparse-checkout repositories, the CLI backend is required for correct operation, making it the only viable option regardless of performance characteristics.

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