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

374
crates/vcs/src/runner.rs Normal file
View file

@ -0,0 +1,374 @@
//! Runs `git` safely: arguments as an array (never a shell), no terminal or
//! credential prompts, a timeout, capped output, no console window.
//!
//! Every call goes through [`run`], and every process starts in [`spawn`],
//! which puts git (and the hooks it runs) into a kill-on-close group
//! (`lutra-proc`), so no git outlives Lutra.
use std::ffi::OsString;
use std::io::{Read, Write};
use std::path::Path;
use std::process::{Command, ExitStatus, Stdio};
use lutra_proc::Child;
use std::sync::mpsc;
use std::thread;
use std::time::{Duration, Instant};
use crate::VcsError;
/// Default timeout of a git call.
pub const TIMEOUT: Duration = Duration::from_secs(30);
/// Timeout of calls that run the user's hooks (commit, checkout).
pub const HOOK_TIMEOUT: Duration = Duration::from_secs(120);
/// Cap on stderr kept for error messages; the rest is read and dropped.
pub const STDERR_CAP: usize = 16 * 1024;
/// Environment variables that would point git at another repository than
/// the one Lutra asked for, removed from every call.
const SCRUBBED_ENV: &[&str] = &[
"GIT_DIR",
"GIT_WORK_TREE",
"GIT_INDEX_FILE",
"GIT_OBJECT_DIRECTORY",
"GIT_ALTERNATE_OBJECT_DIRECTORIES",
"GIT_COMMON_DIR",
"GIT_NAMESPACE",
"GIT_CEILING_DIRECTORIES",
];
/// One git call.
#[derive(Debug)]
pub struct Call<'a> {
/// Arguments after the global options, e.g. `["status", "-z"]`.
pub args: Vec<OsString>,
/// Working directory.
pub cwd: &'a Path,
/// Bytes written to git's stdin, which is closed afterwards; `None`
/// gives git an empty stdin.
pub stdin: Option<Vec<u8>>,
/// How long git may run before it is killed.
pub timeout: Duration,
/// Most bytes of stdout accepted; more fails with
/// [`VcsError::TooLarge`].
pub stdout_cap: usize,
/// A read that must not take optional locks (`GIT_OPTIONAL_LOCKS=0`),
/// so it never competes with the user's own git for `index.lock`.
pub read_only: bool,
}
impl<'a> Call<'a> {
/// A read-only call with the default timeout and an output cap.
pub fn read(cwd: &'a Path, args: &[&str], stdout_cap: usize) -> Self {
Self {
args: args.iter().map(OsString::from).collect(),
cwd,
stdin: None,
timeout: TIMEOUT,
stdout_cap,
read_only: true,
}
}
/// A call that changes the repository, with the default timeout and a
/// 1 MiB output cap.
pub fn write(cwd: &'a Path, args: &[&str]) -> Self {
Self {
read_only: false,
..Self::read(cwd, args, 1024 * 1024)
}
}
/// Sets stdin.
pub fn stdin(mut self, bytes: Vec<u8>) -> Self {
self.stdin = Some(bytes);
self
}
/// Sets the timeout.
pub fn timeout(mut self, timeout: Duration) -> Self {
self.timeout = timeout;
self
}
}
/// What git printed and how it ended.
#[derive(Debug)]
pub struct Output {
/// Exit status.
pub status: ExitStatus,
/// Everything git wrote to stdout (at most the call's cap).
pub stdout: Vec<u8>,
/// The start of stderr, at most [`STDERR_CAP`] bytes.
pub stderr: Vec<u8>,
}
impl Output {
/// Whether git exited with status 0.
pub fn success(&self) -> bool {
self.status.success()
}
/// git's message for a failure: stderr, or stdout when stderr is
/// empty (hooks often print to stdout), trimmed and capped at
/// [`STDERR_CAP`] bytes on a character boundary.
pub fn message(&self) -> String {
let source = if self.stderr.iter().all(u8::is_ascii_whitespace) {
&self.stdout
} else {
&self.stderr
};
let text = String::from_utf8_lossy(source);
let text = text.trim();
let mut end = text.len().min(STDERR_CAP);
while !text.is_char_boundary(end) {
end -= 1;
}
let mut message = text.get(..end).unwrap_or_default().to_string();
if end < text.len() {
message.push_str("\n…");
}
if message.is_empty() {
message = format!("git failed ({})", self.status);
}
message
}
/// `Ok(self)` on exit status 0, else [`VcsError::Git`] with
/// [`Output::message`].
///
/// # Errors
/// See above.
pub fn checked(self) -> Result<Self, VcsError> {
if self.success() {
Ok(self)
} else {
Err(VcsError::Git(self.message()))
}
}
}
/// Starts `command` in a kill-on-close group. The one place where Lutra's
/// git processes start.
///
/// # Errors
/// The operating system's error, or setting up the group failed.
pub fn spawn(command: Command) -> std::io::Result<Child> {
lutra_proc::spawn(command)
}
/// Kills its child when dropped before it was reaped, so no git outlives a
/// call that failed or timed out.
struct Reaper(Option<Child>);
impl Reaper {
/// Waits until the child exits or `deadline` passes.
///
/// # Returns
/// The exit status, or `None` at the deadline (the child is killed
/// when the reaper drops).
fn wait_until(&mut self, deadline: Instant) -> Option<ExitStatus> {
let child = self.0.as_mut()?;
let mut pause = Duration::from_millis(1);
loop {
match child.try_wait() {
Ok(Some(status)) => {
self.0 = None;
return Some(status);
}
Ok(None) => {}
Err(_) => return None,
}
let now = Instant::now();
if now >= deadline {
return None;
}
thread::sleep(pause.min(deadline - now));
pause = (pause * 2).min(Duration::from_millis(20));
}
}
}
impl Drop for Reaper {
/// Kills and reaps the child. Failures are ignored: the child may have
/// exited meanwhile, and nothing else can be done about a process that
/// cannot be killed.
fn drop(&mut self) {
if let Some(child) = self.0.as_mut() {
let _ = child.kill();
let _ = child.wait();
}
}
}
/// Reads `reader` to its end on a new thread, keeping at most `cap` bytes.
///
/// # Parameters
/// - `fail_over_cap`: stop at once and report `Err(())` when more than
/// `cap` bytes arrive (stdout), instead of reading the rest and
/// dropping it (stderr).
fn collect(
mut reader: impl Read + Send + 'static,
cap: usize,
fail_over_cap: bool,
) -> mpsc::Receiver<Result<Vec<u8>, ()>> {
let (tx, rx) = mpsc::channel();
thread::spawn(move || {
let mut kept = Vec::new();
let mut chunk = [0u8; 64 * 1024];
let result = loop {
match reader.read(&mut chunk) {
Ok(0) => break Ok(kept),
Ok(n) => {
let room = cap.saturating_sub(kept.len());
if n > room && fail_over_cap {
break Err(());
}
kept.extend_from_slice(chunk.get(..n.min(room)).unwrap_or_default());
}
Err(e) if e.kind() == std::io::ErrorKind::Interrupted => {}
Err(_) => break Ok(kept),
}
};
let _ = tx.send(result);
});
rx
}
/// Runs git once.
///
/// # Parameters
/// - `executable`: the git program.
/// - `call`: arguments, working directory, stdin, timeout and cap.
///
/// Global options on every call: `--no-pager`, `--literal-pathspecs`
/// (paths are never patterns), `-c core.quotepath=false`,
/// `-c color.ui=false`. Environment: `GIT_TERMINAL_PROMPT=0`,
/// `GCM_INTERACTIVE=never`, `GIT_OPTIONAL_LOCKS=0` for reads, and the
/// variables that redirect git to another repository removed.
///
/// # Errors
/// [`VcsError::Spawn`], [`VcsError::Timeout`] (git is killed),
/// [`VcsError::TooLarge`] (git is killed). A non-zero exit status is not an
/// error here; see [`Output::checked`].
pub fn run(executable: &Path, call: Call<'_>) -> Result<Output, VcsError> {
let mut command = Command::new(executable);
command
.args([
"--no-pager",
"--literal-pathspecs",
"-c",
"core.quotepath=false",
"-c",
"color.ui=false",
])
.args(&call.args)
.current_dir(call.cwd)
.env("GIT_TERMINAL_PROMPT", "0")
.env("GCM_INTERACTIVE", "never")
.stdin(if call.stdin.is_some() {
Stdio::piped()
} else {
Stdio::null()
})
.stdout(Stdio::piped())
.stderr(Stdio::piped());
for name in SCRUBBED_ENV {
command.env_remove(name);
}
if call.read_only {
command.env("GIT_OPTIONAL_LOCKS", "0");
}
hide_console(&mut command);
let deadline = Instant::now() + call.timeout;
let mut child = spawn(command).map_err(|e| VcsError::Spawn(e.to_string()))?;
let stdout = child.stdout.take();
let stderr = child.stderr.take();
let stdin = child.stdin.take();
let mut reaper = Reaper(Some(child));
if let (Some(mut pipe), Some(bytes)) = (stdin, call.stdin) {
thread::spawn(move || {
let _ = pipe.write_all(&bytes);
});
}
let (Some(stdout), Some(stderr)) = (stdout, stderr) else {
return Err(VcsError::Spawn("no pipes".into()));
};
let out_rx = collect(stdout, call.stdout_cap, true);
let err_rx = collect(stderr, STDERR_CAP, false);
let timeout = || VcsError::Timeout {
seconds: call.timeout.as_secs(),
};
let remaining = || deadline.saturating_duration_since(Instant::now());
let stdout = match out_rx.recv_timeout(remaining()) {
Ok(Ok(bytes)) => bytes,
Ok(Err(())) => {
return Err(VcsError::TooLarge {
limit: call.stdout_cap,
});
}
Err(_) => return Err(timeout()),
};
let status = reaper.wait_until(deadline).ok_or_else(timeout)?;
let stderr = err_rx
.recv_timeout(remaining().max(Duration::from_millis(200)))
.ok()
.and_then(Result::ok)
.unwrap_or_default();
Ok(Output {
status,
stdout,
stderr,
})
}
/// Keeps git from opening a console window on Windows.
#[cfg(windows)]
fn hide_console(command: &mut Command) {
use std::os::windows::process::CommandExt;
command.creation_flags(0x0800_0000);
}
/// Nothing to do outside Windows.
#[cfg(not(windows))]
fn hide_console(_command: &mut Command) {}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
fn output(stdout: &[u8], stderr: &[u8]) -> Output {
let status = Command::new(if cfg!(windows) { "cmd" } else { "false" })
.args(if cfg!(windows) {
&["/C", "exit 1"][..]
} else {
&[][..]
})
.status()
.unwrap();
Output {
status,
stdout: stdout.to_vec(),
stderr: stderr.to_vec(),
}
}
#[test]
fn message_prefers_stderr_and_falls_back_to_stdout() {
assert_eq!(output(b"out", b" err \n").message(), "err");
assert_eq!(output(b"hook said no\n", b"\n").message(), "hook said no");
assert!(output(b"", b"").message().starts_with("git failed"));
}
#[test]
fn message_is_capped_on_a_char_boundary() {
let long = "é".repeat(STDERR_CAP);
let message = output(b"", long.as_bytes()).message();
assert!(message.len() <= STDERR_CAP + "\n…".len());
assert!(message.ends_with('…'));
}
}