M4.1: Git backend through the installed git

New crate lutra-vcs (L3): a safe git runner (argument arrays, no prompts,
GIT_OPTIONAL_LOCKS=0 for reads, timeouts 30 s / 120 s for hooks, output
caps, one spawn function for H1's kill-on-close helper), porcelain v2 / -z
parsers (property-tested), Repo operations (status, stage, unstage before
the first commit, commit and amend, show at HEAD/index, branches, checkout
with remote tracking, branch creation checked by check-ref-format) and a
.git poll (RepoWatch).

Engine: git.status, git.stage, git.unstage, git.commit, git.show,
git.branches, git.checkout, git.createBranch on pending outcomes, off the
engine lock; gitChanged after changes and debounced 300 ms on .git or
project changes; setting git.executable (section Git).

Tests against real temp repositories, engine tests through run_waiting,
docs (architecture, gaps G8, Git parity row, roadmap M4 row).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-25 13:23:13 +01:00
parent cd8c34b094
commit 13e7b0aa12
28 changed files with 3485 additions and 9 deletions

60
crates/vcs/src/error.rs Normal file
View file

@ -0,0 +1,60 @@
//! Errors of the Git backend.
/// Why a Git operation failed.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum VcsError {
/// No usable `git` was found: the setting names a missing file, or
/// `git` is not on `PATH`.
#[error("git was not found ({0})")]
NotFound(String),
/// The installed git is older than [`crate::MIN_VERSION`].
#[error("git {found} is too old; Lutra needs git {min} or newer")]
TooOld {
/// The version that was found.
found: String,
/// The minimum version.
min: String,
},
/// `git` could not be started.
#[error("git could not be started: {0}")]
Spawn(String),
/// git did not finish within the timeout and was stopped.
#[error("git did not finish within {seconds} s and was stopped")]
Timeout {
/// The timeout in seconds.
seconds: u64,
},
/// git wrote more than the output cap.
#[error("git's output is larger than {limit} bytes")]
TooLarge {
/// The cap in bytes.
limit: usize,
},
/// git refused or failed; the message is git's own (capped).
#[error("{0}")]
Git(String),
/// git's output could not be understood.
#[error("unexpected output from git: {0}")]
BadOutput(String),
/// A path from the caller is empty, absolute, leaves the project or
/// holds a character git cannot take.
#[error("invalid path: {0}")]
InvalidPath(String),
/// A branch name or revision from the caller is not valid.
#[error("invalid branch name: {0}")]
InvalidName(String),
/// A commit message is empty.
#[error("the commit message is empty")]
EmptyMessage,
}
impl VcsError {
/// Whether the error is the caller's fault (bad path, name or message)
/// rather than a failure of git.
pub fn is_invalid_input(&self) -> bool {
matches!(
self,
Self::InvalidPath(_) | Self::InvalidName(_) | Self::EmptyMessage
)
}
}