# How to Use tuicr with Git Sparse Checkouts: Choosing Between libgit2 and CLI Backends > Learn how to use tuicr with Git sparse checkouts, comparing libgit2 and CLI backends. Get explicit control over your Git sparse checkout experience with tuicr. - Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr) - Tags: how-to-guide - Published: 2026-08-07 --- **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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/mod.rs) checks repository capabilities before finalizing the backend selection: ```rust // 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: ```rust fn discover(preference: GitBackendPreference, ws: DiffWhitespaceMode) -> Result { // ... 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`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) validates this setting against allowed values at lines 392-398: ```rust // 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`: ```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: ```bash # 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: ```toml # ~/.config/tuicr/config.toml backend = "cli" ``` ```bash # CLI backend used regardless of repository type tuicr ``` ### Attempt libgit2 with Fallback To prefer libgit2 but allow automatic CLI fallback for sparse checkouts: ```toml # ~/.config/tuicr/config.toml backend = "libgit2" ``` ```bash # 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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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.