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

23
crates/vcs/Cargo.toml Normal file
View file

@ -0,0 +1,23 @@
[package]
name = "lutra-vcs"
description = "Git through the user's installed git command"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 3
[dependencies]
lutra-proc.workspace = true
thiserror = "2.0.21"
[lints]
workspace = true
[dev-dependencies]
proptest.workspace = true
tempfile.workspace = true

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
)
}
}

32
crates/vcs/src/lib.rs Normal file
View file

@ -0,0 +1,32 @@
//! Git for Lutra (layer L3), through the user's installed `git` command
//! (owner decision D20).
//!
//! - [`Git::detect`] finds git (the `git.executable` setting or `PATH`) and
//! checks it is at least [`MIN_VERSION`].
//! - [`Git::open`] opens the repository containing a project folder.
//! - [`Repo`] runs status, stage, unstage, commit, show, branches,
//! checkout and branch creation. Calls that change the repository are
//! serialised per repository.
//! - [`RepoWatch`] notices changes inside `.git` (HEAD, index, refs).
//!
//! Every call goes through [`runner::run`]: arguments as an array, never a
//! shell; no terminal or credential prompts; a timeout; capped output;
//! machine-readable output only (porcelain v2, `-z`, NUL-separated
//! formats). No network operation exists here.
//!
//! Calls block for as long as git runs, so the engine runs them on their
//! own threads, off its lock.
mod error;
pub mod porcelain;
mod repo;
pub mod runner;
mod watch;
pub use error::VcsError;
pub use porcelain::{FileState, FileStatus, Head, Status, Version};
pub use repo::{
Branch, Branches, CommitInfo, Contents, FILE_CAP, Git, MIN_VERSION, Repo, Rev, STATUS_CAP,
decode,
};
pub use watch::{RepoWatch, fingerprint};

430
crates/vcs/src/porcelain.rs Normal file
View file

@ -0,0 +1,430 @@
//! Parsers for git's machine-readable output: `git status --porcelain=v2
//! -z --branch`, `git --version` and `git for-each-ref` with NUL-separated
//! fields. Every input is untrusted: malformed records are skipped or
//! reported as [`VcsError::BadOutput`], never a panic (property-tested).
use crate::VcsError;
/// The state of a file on one side (index or work tree).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum FileState {
/// No change.
Unmodified,
/// Content or type changed.
Modified,
/// New in the index.
Added,
/// Deleted.
Deleted,
/// Renamed (index side only in porcelain v2).
Renamed,
/// Copied.
Copied,
/// Not tracked.
Untracked,
/// Ignored (only when ignored files are asked for).
Ignored,
/// Unmerged: a conflict waits for resolution.
Conflicted,
}
impl FileState {
/// The contract's name: `unmodified`, `modified`, `added`, `deleted`,
/// `renamed`, `copied`, `untracked`, `ignored` or `conflicted`.
pub fn as_str(self) -> &'static str {
match self {
Self::Unmodified => "unmodified",
Self::Modified => "modified",
Self::Added => "added",
Self::Deleted => "deleted",
Self::Renamed => "renamed",
Self::Copied => "copied",
Self::Untracked => "untracked",
Self::Ignored => "ignored",
Self::Conflicted => "conflicted",
}
}
/// The state of one letter of porcelain v2's `XY` field.
fn from_code(code: u8) -> Self {
match code {
b'M' | b'T' => Self::Modified,
b'A' => Self::Added,
b'D' => Self::Deleted,
b'R' => Self::Renamed,
b'C' => Self::Copied,
b'U' => Self::Conflicted,
b'?' => Self::Untracked,
b'!' => Self::Ignored,
_ => Self::Unmodified,
}
}
}
/// One changed, untracked or conflicted file.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FileStatus {
/// Path with `/` separators (relative to the repository root as git
/// prints it; [`crate::Repo::status`] makes it project-relative).
pub path: String,
/// The path before a rename or copy.
pub orig_path: Option<String>,
/// State in the index (staged).
pub index: FileState,
/// State in the work tree (not staged).
pub worktree: FileState,
}
/// Where HEAD points.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Head {
/// The current branch; `None` when detached.
pub branch: Option<String>,
/// HEAD is detached.
pub detached: bool,
/// The commit of HEAD; `None` before the first commit.
pub head: Option<String>,
/// The upstream branch, e.g. `origin/main`.
pub upstream: Option<String>,
/// Commits ahead of the upstream.
pub ahead: Option<u64>,
/// Commits behind the upstream.
pub behind: Option<u64>,
}
/// A parsed `git status`.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Status {
/// Branch information.
pub head: Head,
/// Files with a change, in git's order.
pub files: Vec<FileStatus>,
}
/// Text of a path from git, which on Unix may hold bytes that are not
/// UTF-8; those become U+FFFD.
fn path_text(bytes: &[u8]) -> String {
String::from_utf8_lossy(bytes).into_owned()
}
/// Splits `record` at the first `fields` spaces: the fields, then the
/// rest (the path, which may contain spaces).
fn split_fields(record: &[u8], fields: usize) -> Option<(Vec<&[u8]>, &[u8])> {
let mut parts = record.splitn(fields + 1, |b| *b == b' ');
let head: Vec<&[u8]> = parts.by_ref().take(fields).collect();
let rest = parts.next()?;
(head.len() == fields).then_some((head, rest))
}
/// The two states of an `XY` field.
fn xy(field: &[u8]) -> Option<(FileState, FileState)> {
match field {
[x, y] => Some((FileState::from_code(*x), FileState::from_code(*y))),
_ => None,
}
}
/// Applies one `# branch.*` header to `head`.
fn header(head: &mut Head, record: &[u8]) {
let text = String::from_utf8_lossy(record);
let Some(rest) = text.strip_prefix("# ") else {
return;
};
let (key, value) = rest.split_once(' ').unwrap_or((rest, ""));
match key {
"branch.oid" if value != "(initial)" && !value.is_empty() => {
head.head = Some(value.to_string());
}
"branch.head" => {
if value == "(detached)" {
head.detached = true;
head.branch = None;
} else if !value.is_empty() {
head.branch = Some(value.to_string());
}
}
"branch.upstream" if !value.is_empty() => head.upstream = Some(value.to_string()),
"branch.ab" => {
let mut parts = value.split(' ');
head.ahead = parts
.next()
.and_then(|a| a.strip_prefix('+'))
.and_then(|a| a.parse().ok());
head.behind = parts
.next()
.and_then(|b| b.strip_prefix('-'))
.and_then(|b| b.parse().ok());
}
_ => {}
}
}
/// Parses `git status --porcelain=v2 -z --branch` output.
///
/// Records of unknown types are skipped (newer git versions may add some).
///
/// # Errors
/// [`VcsError::BadOutput`] for a changed-file record without its fields or
/// a rename without its original path.
pub fn parse_status(bytes: &[u8]) -> Result<Status, VcsError> {
let mut status = Status::default();
let mut records = bytes.split(|b| *b == 0).filter(|r| !r.is_empty());
let bad = |record: &[u8]| VcsError::BadOutput(format!("status record {:?}", path_text(record)));
while let Some(record) = records.next() {
match record.first() {
Some(b'#') => header(&mut status.head, record),
Some(b'1') => {
let (fields, path) = split_fields(record, 8).ok_or_else(|| bad(record))?;
let (index, worktree) = fields
.get(1)
.and_then(|f| xy(f))
.ok_or_else(|| bad(record))?;
status.files.push(FileStatus {
path: path_text(path),
orig_path: None,
index,
worktree,
});
}
Some(b'2') => {
let (fields, path) = split_fields(record, 9).ok_or_else(|| bad(record))?;
let (index, worktree) = fields
.get(1)
.and_then(|f| xy(f))
.ok_or_else(|| bad(record))?;
let orig = records.next().ok_or_else(|| bad(record))?;
status.files.push(FileStatus {
path: path_text(path),
orig_path: Some(path_text(orig)),
index,
worktree,
});
}
Some(b'u') => {
let (_, path) = split_fields(record, 10).ok_or_else(|| bad(record))?;
status.files.push(FileStatus {
path: path_text(path),
orig_path: None,
index: FileState::Conflicted,
worktree: FileState::Conflicted,
});
}
Some(kind @ (b'?' | b'!')) => {
let path = record.get(2..).ok_or_else(|| bad(record))?;
let state = FileState::from_code(*kind);
status.files.push(FileStatus {
path: path_text(path),
orig_path: None,
index: state,
worktree: state,
});
}
_ => {}
}
}
Ok(status)
}
/// A git version as three numbers.
pub type Version = (u32, u32, u32);
/// Parses `git --version` output such as `git version 2.47.1.windows.1`
/// or `git version 2.39.5 (Apple Git-154)`.
///
/// # Returns
/// The version, or `None` if the text has none. A missing patch number
/// counts as 0.
pub fn parse_version(text: &str) -> Option<Version> {
let rest = text.trim().strip_prefix("git version ")?;
let number = rest.split_whitespace().next()?;
let mut parts = number.split('.').map(|p| {
let digits: String = p.chars().take_while(char::is_ascii_digit).collect();
digits.parse::<u32>().ok()
});
let major = parts.next().flatten()?;
let minor = parts.next().flatten()?;
let patch = parts.next().flatten().unwrap_or(0);
Some((major, minor, patch))
}
/// A branch from `git for-each-ref`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RefEntry {
/// The full ref name, e.g. `refs/heads/main`.
pub refname: String,
/// The commit it points to.
pub head: String,
/// Its upstream, short form (`origin/main`), if any.
pub upstream: Option<String>,
/// It is the checked-out branch.
pub current: bool,
/// It is a symbolic ref (such as `refs/remotes/origin/HEAD`).
pub symbolic: bool,
}
/// The `--format` that [`parse_refs`] reads.
pub const REF_FORMAT: &str = "%(refname)%00%(objectname)%00%(upstream:short)%00%(HEAD)%00%(symref)";
/// Parses `git for-each-ref --format=REF_FORMAT` output: one ref per line,
/// fields separated by NUL. Ref names cannot hold line breaks or NUL
/// (`git check-ref-format`), so the split is safe. Lines with too few
/// fields are skipped.
pub fn parse_refs(bytes: &[u8]) -> Vec<RefEntry> {
bytes
.split(|b| *b == b'\n')
.filter_map(|line| {
let mut fields = line.split(|b| *b == 0).map(path_text);
let refname = fields.next().filter(|r| !r.is_empty())?;
let head = fields.next()?;
let upstream = fields.next().filter(|u| !u.is_empty());
let current = fields.next()? == "*";
let symbolic = fields.next().is_some_and(|s| !s.trim().is_empty());
Some(RefEntry {
refname,
head,
upstream,
current,
symbolic,
})
})
.collect()
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::indexing_slicing)]
use proptest::prelude::*;
use super::*;
#[test]
fn parses_headers_and_every_record_type() {
let out = b"# branch.oid 1234abcd\0# branch.head main\0# branch.upstream origin/main\0# branch.ab +2 -3\0\
1 .M N... 100644 100644 100644 aaa bbb src/a file.php\0\
2 R. N... 100644 100644 100644 aaa bbb R100 new name.php\0old name.php\0\
u UU N... 100644 100644 100644 100644 a b c conflict.php\0\
? new dir/x.php\0! vendor/y.php\0";
let status = parse_status(out).unwrap();
assert_eq!(
status.head,
Head {
branch: Some("main".into()),
detached: false,
head: Some("1234abcd".into()),
upstream: Some("origin/main".into()),
ahead: Some(2),
behind: Some(3),
}
);
let files: Vec<_> = status
.files
.iter()
.map(|f| {
(
f.path.as_str(),
f.orig_path.as_deref(),
f.index.as_str(),
f.worktree.as_str(),
)
})
.collect();
assert_eq!(
files,
vec![
("src/a file.php", None, "unmodified", "modified"),
(
"new name.php",
Some("old name.php"),
"renamed",
"unmodified"
),
("conflict.php", None, "conflicted", "conflicted"),
("new dir/x.php", None, "untracked", "untracked"),
("vendor/y.php", None, "ignored", "ignored"),
]
);
}
#[test]
fn initial_and_detached_heads() {
let initial = parse_status(b"# branch.oid (initial)\0# branch.head main\0").unwrap();
assert_eq!(initial.head.head, None);
assert_eq!(initial.head.branch.as_deref(), Some("main"));
let detached = parse_status(b"# branch.oid abc\0# branch.head (detached)\0").unwrap();
assert!(detached.head.detached);
assert_eq!(detached.head.branch, None);
}
#[test]
fn invalid_utf8_paths_become_replacement_characters() {
let status = parse_status(b"? caf\xe9.php\0").unwrap();
assert_eq!(status.files[0].path, "caf\u{fffd}.php");
}
#[test]
fn malformed_records_are_errors_not_panics() {
assert!(parse_status(b"1 .M\0").is_err());
assert!(parse_status(b"2 R. N... 1 1 1 a b R100 new").is_err());
assert!(parse_status(b"z unknown\0").unwrap().files.is_empty());
}
#[test]
fn versions() {
assert_eq!(
parse_version("git version 2.47.1.windows.1\n"),
Some((2, 47, 1))
);
assert_eq!(
parse_version("git version 2.39.5 (Apple Git-154)"),
Some((2, 39, 5))
);
assert_eq!(parse_version("git version 2.30"), Some((2, 30, 0)));
assert_eq!(parse_version("hello"), None);
}
#[test]
fn refs() {
let refs = parse_refs(
b"refs/heads/main\0abc\0origin/main\0*\0\nrefs/remotes/origin/HEAD\0abc\0\0 \0refs/remotes/origin/main\nbroken\n",
);
assert_eq!(refs.len(), 2);
assert!(refs[0].current);
assert_eq!(refs[0].upstream.as_deref(), Some("origin/main"));
assert!(refs[1].symbolic);
}
proptest! {
#[test]
fn status_parser_never_panics(bytes in proptest::collection::vec(any::<u8>(), 0..512)) {
let _ = parse_status(&bytes);
}
#[test]
fn status_parser_survives_record_shaped_noise(
parts in proptest::collection::vec(
prop_oneof![
Just(b"1 ".to_vec()),
Just(b"2 ".to_vec()),
Just(b"u ".to_vec()),
Just(b"? ".to_vec()),
Just(b"# branch.ab ".to_vec()),
Just(b"# branch.head ".to_vec()),
Just(vec![0u8]),
Just(b" ".to_vec()),
proptest::collection::vec(any::<u8>(), 0..8),
],
0..48,
)
) {
let bytes: Vec<u8> = parts.concat();
let _ = parse_status(&bytes);
}
#[test]
fn version_and_ref_parsers_never_panic(bytes in proptest::collection::vec(any::<u8>(), 0..256)) {
let _ = parse_version(&String::from_utf8_lossy(&bytes));
let _ = parse_refs(&bytes);
}
}
}

666
crates/vcs/src/repo.rs Normal file
View file

@ -0,0 +1,666 @@
//! The installed git ([`Git`]) and a repository opened through it
//! ([`Repo`]): status, staging, commits, file contents and branches.
//!
//! Paths in and out of [`Repo`] are relative to the project root (the
//! folder the repository was opened from) with `/` separators, as
//! everywhere in Lutra; the repository root may lie above it. Files outside
//! the project are left out of [`Repo::status`].
use std::path::{Path, PathBuf};
use std::sync::{Mutex, MutexGuard, PoisonError};
use crate::VcsError;
use crate::porcelain::{self, FileStatus, Head, REF_FORMAT, Status, Version};
use crate::runner::{self, Call, HOOK_TIMEOUT};
/// Oldest supported git: 2.30 (porcelain v2 headers, `--pathspec-from-file`
/// for every command used, `switch`, `--end-of-options`).
pub const MIN_VERSION: Version = (2, 30, 0);
/// Cap on `git status` output.
pub const STATUS_CAP: usize = 64 * 1024 * 1024;
/// Cap on one file's contents from [`Repo::show`].
pub const FILE_CAP: usize = 32 * 1024 * 1024;
/// Cap on other read output (refs, rev-parse).
const SMALL_CAP: usize = 16 * 1024 * 1024;
/// How many leading bytes [`Repo::show`] checks for NUL, as git does.
const BINARY_PROBE: usize = 8000;
/// The installed git, checked to be recent enough.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Git {
/// The program that runs.
executable: PathBuf,
/// Its version.
version: Version,
}
impl Git {
/// Finds git and checks its version.
///
/// # Parameters
/// - `setting`: the `git.executable` setting; empty means `git` from
/// `PATH`.
///
/// # Errors
/// [`VcsError::NotFound`] when git cannot be started,
/// [`VcsError::TooOld`] below [`MIN_VERSION`],
/// [`VcsError::BadOutput`] when `git --version` prints no version, or
/// the runner's errors.
pub fn detect(setting: &str) -> Result<Self, VcsError> {
let setting = setting.trim();
let executable = PathBuf::from(if setting.is_empty() { "git" } else { setting });
let cwd = std::env::temp_dir();
let output = runner::run(&executable, Call::read(&cwd, &["--version"], 4096))
.map_err(|e| match e {
VcsError::Spawn(detail) => {
VcsError::NotFound(format!("{}: {detail}", executable.display()))
}
other => other,
})?
.checked()?;
let text = String::from_utf8_lossy(&output.stdout);
let version = porcelain::parse_version(&text)
.ok_or_else(|| VcsError::BadOutput(text.trim().to_string()))?;
if version < MIN_VERSION {
return Err(VcsError::TooOld {
found: format!("{}.{}.{}", version.0, version.1, version.2),
min: format!("{}.{}.{}", MIN_VERSION.0, MIN_VERSION.1, MIN_VERSION.2),
});
}
Ok(Self {
executable,
version,
})
}
/// The version found.
pub fn version(&self) -> Version {
self.version
}
/// Opens the repository that contains `dir` (a nested repository wins
/// over a parent one, as git decides).
///
/// # Returns
/// `None` when `dir` is not inside a work tree.
///
/// # Errors
/// [`VcsError::Git`] when git refuses for another reason (an unsafe
/// owner, a broken repository), or the runner's errors.
pub fn open(&self, dir: &Path) -> Result<Option<Repo>, VcsError> {
let output = runner::run(
&self.executable,
Call::read(
dir,
&[
"rev-parse",
"--show-toplevel",
"--absolute-git-dir",
"--git-common-dir",
"--show-prefix",
],
SMALL_CAP,
),
)?;
if !output.success() {
let message = output.message();
if message.contains("not a git repository") || message.contains("work tree") {
return Ok(None);
}
return Err(VcsError::Git(message));
}
let text = String::from_utf8_lossy(&output.stdout);
let mut lines = text.split('\n').map(|l| l.trim_end_matches('\r'));
let mut next = || {
lines
.next()
.ok_or_else(|| VcsError::BadOutput(text.to_string()))
};
let root = PathBuf::from(next()?);
let git_dir = PathBuf::from(next()?);
let common = PathBuf::from(next()?);
let prefix = next().unwrap_or_default().to_string();
let common_dir = if common.is_absolute() {
common
} else {
dir.join(common)
};
Ok(Some(Repo {
git: self.clone(),
root,
git_dir,
common_dir,
prefix,
mutations: Mutex::new(()),
}))
}
}
/// Which version of a file [`Repo::show`] returns.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Rev {
/// The last commit.
Head,
/// The staged version.
Index,
}
/// A file's contents at a [`Rev`].
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Contents {
/// The text (UTF-8, BOM removed); `None` when the file does not exist
/// there, is binary or too large.
pub text: Option<String>,
/// The contents are binary (a NUL byte in the first 8000 bytes, not
/// UTF-8, or a submodule).
pub binary: bool,
/// The file is larger than [`FILE_CAP`].
pub too_large: bool,
}
/// A branch.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Branch {
/// Short name: `main`, `origin/main`.
pub name: String,
/// The commit it points to.
pub head: String,
/// Its upstream (local branches only).
pub upstream: Option<String>,
}
/// Local and remote branches.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Branches {
/// The checked-out branch; `None` when detached.
pub current: Option<String>,
/// Local branches, sorted by name.
pub local: Vec<Branch>,
/// Remote-tracking branches, sorted by name, without `origin/HEAD`.
pub remote: Vec<Branch>,
}
/// A commit just made.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CommitInfo {
/// Its full hash.
pub commit: String,
/// Its subject line.
pub summary: String,
}
/// A repository, opened from a project folder.
#[derive(Debug)]
pub struct Repo {
/// The git that runs.
git: Git,
/// The work tree's root.
root: PathBuf,
/// The repository directory (`.git`, or a linked work tree's own).
git_dir: PathBuf,
/// The directory shared by all work trees (refs, packed-refs).
common_dir: PathBuf,
/// The project folder relative to [`Repo::root`], `""` or ending in `/`.
prefix: String,
/// Held by every call that changes the repository, so they never race.
mutations: Mutex<()>,
}
impl Repo {
/// The work tree's root as git printed it.
pub fn root(&self) -> &Path {
&self.root
}
/// The repository directory.
pub fn git_dir(&self) -> &Path {
&self.git_dir
}
/// The common directory (refs).
pub fn common_dir(&self) -> &Path {
&self.common_dir
}
/// The project folder relative to the root, `""` or ending in `/`.
pub fn prefix(&self) -> &str {
&self.prefix
}
/// Serialises changes: the guard of [`Repo::mutations`]. A poisoned
/// lock is taken over: the lock guards no data.
fn lock(&self) -> MutexGuard<'_, ()> {
self.mutations
.lock()
.unwrap_or_else(PoisonError::into_inner)
}
/// Runs git in the work tree root.
fn run(&self, call: Call<'_>) -> Result<runner::Output, VcsError> {
runner::run(&self.git.executable, call)
}
/// Turns a project-relative path from a caller into a root-relative
/// one.
///
/// # Errors
/// [`VcsError::InvalidPath`] for an empty or absolute path, `..`, or
/// NUL and line breaks.
pub fn to_repo_path(&self, path: &str) -> Result<String, VcsError> {
let invalid = || VcsError::InvalidPath(path.to_string());
if path.contains(['\0', '\n', '\r']) || Path::new(path).is_absolute() {
return Err(invalid());
}
let normal = path.replace('\\', "/");
if normal.starts_with('/') {
return Err(invalid());
}
let mut parts = Vec::new();
for part in normal.split('/') {
match part {
"" | "." => {}
".." => return Err(invalid()),
_ => parts.push(part),
}
}
if parts.is_empty() {
return Err(invalid());
}
Ok(format!("{}{}", self.prefix, parts.join("/")))
}
/// Turns a root-relative path from git into a project-relative one;
/// `None` for paths outside the project.
pub fn from_repo_path(&self, path: &str) -> Option<String> {
path.strip_prefix(self.prefix.as_str())
.filter(|p| !p.is_empty())
.map(str::to_string)
}
/// Paths for `--pathspec-from-file=- --pathspec-file-nul`.
fn pathspec(&self, paths: &[String]) -> Result<Vec<u8>, VcsError> {
let mut bytes = Vec::new();
for path in paths {
bytes.extend_from_slice(self.to_repo_path(path)?.as_bytes());
bytes.push(0);
}
Ok(bytes)
}
/// The status of the work tree: branch information and every changed,
/// staged, untracked or conflicted file inside the project (untracked
/// directories are listed file by file; ignored files are not listed).
///
/// # Errors
/// The runner's errors ([`VcsError::TooLarge`] past [`STATUS_CAP`]),
/// git's refusal, or [`VcsError::BadOutput`].
pub fn status(&self) -> Result<Status, VcsError> {
let output = self
.run(Call::read(
&self.root,
&[
"status",
"--porcelain=v2",
"-z",
"--branch",
"--untracked-files=all",
],
STATUS_CAP,
))?
.checked()?;
let mut status = porcelain::parse_status(&output.stdout)?;
status.files = status
.files
.into_iter()
.filter_map(|file| {
let path = self.from_repo_path(&file.path)?;
let orig_path = file
.orig_path
.as_deref()
.and_then(|p| self.from_repo_path(p));
Some(FileStatus {
path,
orig_path,
..file
})
})
.collect();
Ok(status)
}
/// Branch information only, without scanning for untracked files; for
/// change events.
///
/// # Errors
/// As [`Repo::status`].
pub fn head(&self) -> Result<Head, VcsError> {
let output = self
.run(Call::read(
&self.root,
&[
"status",
"--porcelain=v2",
"-z",
"--branch",
"--untracked-files=no",
],
STATUS_CAP,
))?
.checked()?;
Ok(porcelain::parse_status(&output.stdout)?.head)
}
/// Whether HEAD points to a commit (false before the first commit).
fn has_head(&self) -> Result<bool, VcsError> {
let output = self.run(Call::read(
&self.root,
&["rev-parse", "--verify", "--quiet", "HEAD^{commit}"],
4096,
))?;
Ok(output.success())
}
/// Stages the paths (new, changed and deleted files alike).
///
/// # Errors
/// [`VcsError::InvalidPath`], or git's refusal (a path that matches
/// nothing).
pub fn stage(&self, paths: &[String]) -> Result<(), VcsError> {
if paths.is_empty() {
return Ok(());
}
let spec = self.pathspec(paths)?;
let _guard = self.lock();
self.run(
Call::write(
&self.root,
&["add", "-A", "--pathspec-from-file=-", "--pathspec-file-nul"],
)
.stdin(spec),
)?
.checked()?;
Ok(())
}
/// Unstages the paths: the index takes HEAD's version again, or, before
/// the first commit, the paths leave the index (`git rm --cached`). The
/// work tree is not touched. For a staged rename pass both paths.
///
/// # Errors
/// [`VcsError::InvalidPath`], or git's refusal.
pub fn unstage(&self, paths: &[String]) -> Result<(), VcsError> {
if paths.is_empty() {
return Ok(());
}
let spec = self.pathspec(paths)?;
let _guard = self.lock();
let args: &[&str] = if self.has_head()? {
&[
"reset",
"-q",
"HEAD",
"--pathspec-from-file=-",
"--pathspec-file-nul",
]
} else {
&[
"rm",
"--cached",
"-r",
"-q",
"--ignore-unmatch",
"--pathspec-from-file=-",
"--pathspec-file-nul",
]
};
self.run(Call::write(&self.root, args).stdin(spec))?
.checked()?;
Ok(())
}
/// Commits what is staged. Hooks run as configured; their output on
/// failure is the error message (capped at 16 KiB). Lines starting
/// with `#` are kept (`--cleanup=whitespace`).
///
/// # Parameters
/// - `message`: the commit message; must not be blank.
/// - `amend`: replace the last commit instead.
///
/// # Errors
/// [`VcsError::EmptyMessage`], [`VcsError::Timeout`] after 120 s, or
/// git's refusal (nothing staged, no identity, a failing hook).
pub fn commit(&self, message: &str, amend: bool) -> Result<CommitInfo, VcsError> {
if message.trim().is_empty() {
return Err(VcsError::EmptyMessage);
}
let mut args = vec!["commit", "-q", "--cleanup=whitespace", "-F", "-"];
if amend {
args.push("--amend");
}
let _guard = self.lock();
self.run(
Call::write(&self.root, &args)
.stdin(message.as_bytes().to_vec())
.timeout(HOOK_TIMEOUT),
)?
.checked()?;
let output = self
.run(Call::read(
&self.root,
&["show", "-s", "--format=%H%x00%s", "HEAD"],
SMALL_CAP,
))?
.checked()?;
let text = String::from_utf8_lossy(&output.stdout);
let (commit, summary) = text.trim_end().split_once('\0').unwrap_or((&text, ""));
Ok(CommitInfo {
commit: commit.trim().to_string(),
summary: summary.to_string(),
})
}
/// A file's contents at HEAD or in the index, as stored (no smudge
/// filters or line-ending conversion run, so an LFS file shows its
/// pointer and nothing reaches the network).
///
/// # Errors
/// [`VcsError::InvalidPath`], or the runner's errors.
pub fn show(&self, path: &str, rev: Rev) -> Result<Contents, VcsError> {
let path = self.to_repo_path(path)?;
let object = match rev {
Rev::Head => format!("HEAD:{path}\n"),
Rev::Index => format!(":0:{path}\n"),
};
let output = self
.run(
Call::read(&self.root, &["cat-file", "--batch-check"], SMALL_CAP)
.stdin(object.into_bytes()),
)?
.checked()?;
let line = String::from_utf8_lossy(&output.stdout);
let fields: Vec<&str> = line.trim_end().rsplitn(3, ' ').collect();
let [size, kind, oid] = fields.as_slice() else {
return Ok(Contents::default());
};
if *size == "missing" || *kind == "missing" || *kind == "tree" {
return Ok(Contents::default());
}
if *kind != "blob" {
return Ok(Contents {
binary: true,
..Contents::default()
});
}
let size: usize = size
.parse()
.map_err(|_| VcsError::BadOutput(line.to_string()))?;
if size > FILE_CAP {
return Ok(Contents {
too_large: true,
..Contents::default()
});
}
let output = self
.run(Call::read(&self.root, &["cat-file", "blob", oid], FILE_CAP))?
.checked()?;
Ok(decode(output.stdout))
}
/// Local and remote-tracking branches.
///
/// # Errors
/// The runner's errors or git's refusal.
pub fn branches(&self) -> Result<Branches, VcsError> {
let format = format!("--format={REF_FORMAT}");
let output = self
.run(Call::read(
&self.root,
&[
"for-each-ref",
&format,
"--sort=refname",
"refs/heads",
"refs/remotes",
],
SMALL_CAP,
))?
.checked()?;
let mut branches = Branches::default();
for entry in porcelain::parse_refs(&output.stdout) {
if let Some(name) = entry.refname.strip_prefix("refs/heads/") {
if entry.current {
branches.current = Some(name.to_string());
}
branches.local.push(Branch {
name: name.to_string(),
head: entry.head,
upstream: entry.upstream,
});
} else if let Some(name) = entry.refname.strip_prefix("refs/remotes/")
&& !entry.symbolic
{
branches.remote.push(Branch {
name: name.to_string(),
head: entry.head,
upstream: None,
});
}
}
Ok(branches)
}
/// Whether `refname` exists.
fn ref_exists(&self, refname: &str) -> Result<bool, VcsError> {
Ok(self
.run(Call::read(
&self.root,
&["show-ref", "--verify", "--quiet", refname],
4096,
))?
.success())
}
/// Checks out a local branch, or creates a local branch tracking a
/// remote one (`origin/feature` → `feature`). Hooks run (120 s).
///
/// # Errors
/// [`VcsError::InvalidName`], [`VcsError::Git`] for an unknown branch
/// or when git refuses (local changes would be overwritten); git's
/// message is passed on.
pub fn checkout(&self, branch: &str) -> Result<(), VcsError> {
check_name(branch)?;
let _guard = self.lock();
let args: Vec<&str> = if self.ref_exists(&format!("refs/heads/{branch}"))? {
vec!["switch", "-q", branch]
} else if self.ref_exists(&format!("refs/remotes/{branch}"))? {
vec!["switch", "-q", "--track", branch]
} else {
return Err(VcsError::Git(format!("no branch named {branch}")));
};
self.run(Call::write(&self.root, &args).timeout(HOOK_TIMEOUT))?
.checked()?;
Ok(())
}
/// Creates a branch.
///
/// # Parameters
/// - `name`: the new branch's name, validated with
/// `git check-ref-format --branch`.
/// - `from`: where it starts; `None` means HEAD.
/// - `checkout`: check it out as well.
///
/// # Errors
/// [`VcsError::InvalidName`] for a bad name or start, or git's refusal
/// (the branch exists).
pub fn create_branch(
&self,
name: &str,
from: Option<&str>,
checkout: bool,
) -> Result<(), VcsError> {
check_name(name)?;
let from = from
.map(str::trim)
.filter(|f| !f.is_empty())
.unwrap_or("HEAD");
check_name(from)?;
let output = self.run(Call::read(
&self.root,
&["check-ref-format", "--branch", name],
4096,
))?;
if !output.success() || String::from_utf8_lossy(&output.stdout).trim() != name {
return Err(VcsError::InvalidName(name.to_string()));
}
let _guard = self.lock();
let args: &[&str] = if checkout {
&["switch", "-q", "-c", name, from]
} else {
&["branch", "--end-of-options", name, from]
};
self.run(Call::write(&self.root, args).timeout(HOOK_TIMEOUT))?
.checked()?;
Ok(())
}
}
/// Rejects branch names and revisions git could read as an option or
/// that hold control characters.
fn check_name(name: &str) -> Result<(), VcsError> {
if name.is_empty() || name.starts_with('-') || name.chars().any(char::is_control) {
return Err(VcsError::InvalidName(name.to_string()));
}
Ok(())
}
/// Turns blob bytes into [`Contents`]: binary when a NUL byte is in the
/// first 8000 bytes or the bytes are not UTF-8; a UTF-8 BOM is dropped.
pub fn decode(mut bytes: Vec<u8>) -> Contents {
let probe = bytes
.get(..BINARY_PROBE.min(bytes.len()))
.unwrap_or_default();
if probe.contains(&0) {
return Contents {
binary: true,
..Contents::default()
};
}
if bytes.starts_with(b"\xEF\xBB\xBF") {
bytes.drain(..3);
}
match String::from_utf8(bytes) {
Ok(text) => Contents {
text: Some(text),
..Contents::default()
},
Err(_) => Contents {
binary: true,
..Contents::default()
},
}
}

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('…'));
}
}

150
crates/vcs/src/watch.rs Normal file
View file

@ -0,0 +1,150 @@
//! Notices changes inside the repository directory (HEAD, the index,
//! branches), which the project watcher never reports because `.git` is
//! hidden from it.
//!
//! A background thread compares size and modification time of a few files
//! (`HEAD`, `index`, `MERGE_HEAD`, `ORIG_HEAD`, `packed-refs`) and of the
//! refs under `refs/heads` and `refs/remotes` (at most [`MAX_ENTRIES`])
//! every interval. Polling a handful of `stat` calls is cheaper and more
//! predictable than OS notifications on a directory whose object store
//! churns during every commit.
use std::collections::hash_map::DefaultHasher;
use std::hash::{Hash, Hasher};
use std::path::{Path, PathBuf};
use std::sync::mpsc::{self, Receiver, RecvTimeoutError, Sender};
use std::thread;
use std::time::Duration;
/// Most ref files looked at per poll.
pub const MAX_ENTRIES: usize = 4096;
/// What the owner tells the polling thread.
enum Control {
/// Take the current state as the new baseline without reporting it
/// (after Lutra's own change, which reports itself).
Rebase,
}
/// A running poll of one repository directory; stops when dropped.
#[derive(Debug)]
pub struct RepoWatch {
/// Commands to the thread; dropping it stops the thread.
control: Sender<Control>,
/// One message per detected change.
changes: Receiver<()>,
}
impl RepoWatch {
/// Starts polling.
///
/// # Parameters
/// - `git_dir`: the repository directory (HEAD, index).
/// - `common_dir`: the shared directory (refs, packed-refs).
/// - `interval`: time between polls.
pub fn start(git_dir: &Path, common_dir: &Path, interval: Duration) -> Self {
let (control, control_rx) = mpsc::channel();
let (changes_tx, changes) = mpsc::channel();
let git_dir = git_dir.to_path_buf();
let common_dir = common_dir.to_path_buf();
thread::Builder::new()
.name("lutra-git-watch".into())
.spawn(move || poll(&git_dir, &common_dir, interval, &control_rx, &changes_tx))
.ok();
Self { control, changes }
}
/// Whether a change was seen since the last call.
pub fn changed(&self) -> bool {
let mut any = false;
while self.changes.try_recv().is_ok() {
any = true;
}
any
}
/// Takes the current state as the baseline, so a change Lutra made
/// itself is not reported again. A stopped thread is ignored.
pub fn rebase(&self) {
let _ = self.control.send(Control::Rebase);
}
}
/// The polling loop; ends when the [`RepoWatch`] is dropped or nobody
/// receives its changes. A thread that failed to start leaves the watch
/// silent, which only costs the automatic refresh.
fn poll(
git_dir: &Path,
common_dir: &Path,
interval: Duration,
control: &Receiver<Control>,
changes: &Sender<()>,
) {
let mut last = fingerprint(git_dir, common_dir);
loop {
match control.recv_timeout(interval) {
Ok(Control::Rebase) => last = fingerprint(git_dir, common_dir),
Err(RecvTimeoutError::Disconnected) => return,
Err(RecvTimeoutError::Timeout) => {
let now = fingerprint(git_dir, common_dir);
if now != last {
last = now;
if changes.send(()).is_err() {
return;
}
}
}
}
}
}
/// A hash of the size and modification time of the watched files.
pub fn fingerprint(git_dir: &Path, common_dir: &Path) -> u64 {
let mut hasher = DefaultHasher::new();
for name in ["HEAD", "index", "MERGE_HEAD", "ORIG_HEAD"] {
stamp(&git_dir.join(name), &mut hasher);
}
stamp(&common_dir.join("packed-refs"), &mut hasher);
let mut budget = MAX_ENTRIES;
for dir in ["refs/heads", "refs/remotes"] {
walk(&common_dir.join(dir), &mut hasher, &mut budget);
}
hasher.finish()
}
/// Hashes the path, size and modification time of one file (a missing
/// file hashes as missing).
fn stamp(path: &Path, hasher: &mut impl Hasher) {
path.hash(hasher);
match std::fs::metadata(path) {
Ok(meta) => {
meta.len().hash(hasher);
meta.modified().ok().hash(hasher);
}
Err(_) => 0xdead_u64.hash(hasher),
}
}
/// Hashes every file below `dir`, depth first in name order, until the
/// budget runs out. Unreadable directories are skipped.
fn walk(dir: &Path, hasher: &mut impl Hasher, budget: &mut usize) {
let Ok(entries) = std::fs::read_dir(dir) else {
return;
};
let mut paths: Vec<(PathBuf, bool)> = entries
.filter_map(Result::ok)
.map(|e| (e.path(), e.file_type().is_ok_and(|t| t.is_dir())))
.collect();
paths.sort();
for (path, is_dir) in paths {
if *budget == 0 {
return;
}
*budget -= 1;
if is_dir {
walk(&path, hasher, budget);
} else {
stamp(&path, hasher);
}
}
}

479
crates/vcs/tests/repo.rs Normal file
View file

@ -0,0 +1,479 @@
//! The Git backend against real repositories created in temp folders:
//! an initial repository without HEAD, commits, renames, CRLF, untracked
//! files, a detached HEAD, Unicode paths, a file over the cap, binary
//! files, a failing hook, branches and a project inside a repository.
//! Every test skips with a message when git is not installed.
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::panic,
clippy::indexing_slicing
)]
use std::path::Path;
use std::process::Command;
use std::time::{Duration, Instant};
use lutra_vcs::{FILE_CAP, FileState, Git, Repo, RepoWatch, Rev, VcsError};
/// The installed git, or `None` (with a message) when there is none.
fn installed() -> Option<Git> {
match Git::detect("") {
Ok(git) => Some(git),
Err(e) => {
eprintln!("skipped: no usable git installed ({e})");
None
}
}
}
/// Runs git in `dir` for test setup and asserts it succeeded.
fn git(dir: &Path, args: &[&str]) -> String {
let out = Command::new("git")
.args(args)
.current_dir(dir)
.env_remove("GIT_DIR")
.env_remove("GIT_WORK_TREE")
.env_remove("GIT_INDEX_FILE")
.output()
.unwrap();
assert!(
out.status.success(),
"git {args:?}: {}",
String::from_utf8_lossy(&out.stderr)
);
String::from_utf8_lossy(&out.stdout).trim().to_string()
}
/// A new repository on branch `main` with a local identity, no signing,
/// no line-ending conversion and its own hooks folder.
fn init(dir: &Path) {
git(dir, &["init", "-q", "-b", "main"]);
for (key, value) in [
("user.name", "Lutra Test"),
("user.email", "test@lutra.invalid"),
("commit.gpgsign", "false"),
("core.autocrlf", "false"),
("core.hooksPath", ".git/hooks"),
] {
git(dir, &["config", key, value]);
}
}
/// Writes a file, creating its folders.
fn write(dir: &Path, path: &str, text: impl AsRef<[u8]>) {
let full = dir.join(path);
std::fs::create_dir_all(full.parent().unwrap()).unwrap();
std::fs::write(full, text).unwrap();
}
/// Opens the repository at `dir`.
fn open(git: &Git, dir: &Path) -> Repo {
git.open(dir).unwrap().expect("a repository")
}
/// The states of `path` in a status, or `None` if it is not listed.
fn states(repo: &Repo, path: &str) -> Option<(FileState, FileState)> {
repo.status()
.unwrap()
.files
.into_iter()
.find(|f| f.path == path)
.map(|f| (f.index, f.worktree))
}
#[test]
fn folders_outside_a_repository_have_none() {
let Some(cli) = installed() else { return };
let dir = tempfile::tempdir().unwrap();
assert!(cli.open(dir.path()).unwrap().is_none());
}
#[test]
fn a_missing_executable_is_not_found() {
let err = Git::detect("C:/no/such/git-binary-for-lutra").unwrap_err();
assert!(matches!(err, VcsError::NotFound(_)), "{err:?}");
}
#[test]
fn initial_repository_stages_unstages_and_commits() {
let Some(cli) = installed() else { return };
let dir = tempfile::tempdir().unwrap();
init(dir.path());
write(dir.path(), "src/a.php", "<?php\necho 1;\n");
let repo = open(&cli, dir.path());
let status = repo.status().unwrap();
assert_eq!(status.head.branch.as_deref(), Some("main"));
assert_eq!(status.head.head, None);
assert!(!status.head.detached);
assert_eq!(
states(&repo, "src/a.php"),
Some((FileState::Untracked, FileState::Untracked))
);
repo.stage(&["src/a.php".into()]).unwrap();
assert_eq!(
states(&repo, "src/a.php"),
Some((FileState::Added, FileState::Unmodified))
);
assert_eq!(
repo.show("src/a.php", Rev::Index).unwrap().text.as_deref(),
Some("<?php\necho 1;\n")
);
assert_eq!(repo.show("src/a.php", Rev::Head).unwrap().text, None);
repo.unstage(&["src/a.php".into()]).unwrap();
assert_eq!(
states(&repo, "src/a.php"),
Some((FileState::Untracked, FileState::Untracked))
);
repo.stage(&["src/a.php".into()]).unwrap();
assert_eq!(repo.commit(" \n", false), Err(VcsError::EmptyMessage));
let commit = repo.commit("#1 first commit\n\nbody", false).unwrap();
assert_eq!(commit.summary, "#1 first commit");
assert_eq!(commit.commit, git(dir.path(), &["rev-parse", "HEAD"]));
let status = repo.status().unwrap();
assert!(status.files.is_empty(), "{:?}", status.files);
assert_eq!(status.head.head.as_deref(), Some(commit.commit.as_str()));
}
#[test]
fn modified_deleted_renamed_and_amended() {
let Some(cli) = installed() else { return };
let dir = tempfile::tempdir().unwrap();
init(dir.path());
write(dir.path(), "a.php", "<?php // a\n");
write(
dir.path(),
"old.php",
"<?php // a file long enough to be found as a rename\n",
);
write(dir.path(), "gone.php", "<?php // gone\n");
git(dir.path(), &["add", "-A"]);
git(dir.path(), &["commit", "-q", "-m", "base"]);
let repo = open(&cli, dir.path());
write(dir.path(), "a.php", "<?php // changed\n");
std::fs::remove_file(dir.path().join("gone.php")).unwrap();
std::fs::rename(dir.path().join("old.php"), dir.path().join("new.php")).unwrap();
assert_eq!(
states(&repo, "a.php"),
Some((FileState::Unmodified, FileState::Modified))
);
assert_eq!(
states(&repo, "gone.php"),
Some((FileState::Unmodified, FileState::Deleted))
);
repo.stage(&[
"a.php".into(),
"gone.php".into(),
"old.php".into(),
"new.php".into(),
])
.unwrap();
let status = repo.status().unwrap();
let renamed = status.files.iter().find(|f| f.path == "new.php").unwrap();
assert_eq!(renamed.index, FileState::Renamed);
assert_eq!(renamed.orig_path.as_deref(), Some("old.php"));
assert_eq!(
states(&repo, "gone.php"),
Some((FileState::Deleted, FileState::Unmodified))
);
assert_eq!(
repo.show("a.php", Rev::Head).unwrap().text.as_deref(),
Some("<?php // a\n")
);
assert_eq!(
repo.show("a.php", Rev::Index).unwrap().text.as_deref(),
Some("<?php // changed\n")
);
repo.unstage(&["new.php".into(), "old.php".into()]).unwrap();
assert_eq!(
states(&repo, "new.php"),
Some((FileState::Untracked, FileState::Untracked))
);
let first = repo.commit("second", false).unwrap();
let amended = repo.commit("second, amended", true).unwrap();
assert_ne!(first.commit, amended.commit);
assert_eq!(amended.summary, "second, amended");
assert_eq!(git(dir.path(), &["rev-list", "--count", "HEAD"]), "2");
}
#[test]
fn crlf_work_trees_with_autocrlf_are_clean() {
let Some(cli) = installed() else { return };
let dir = tempfile::tempdir().unwrap();
init(dir.path());
git(dir.path(), &["config", "core.autocrlf", "true"]);
write(dir.path(), "crlf.php", "<?php\r\necho 1;\r\n");
git(dir.path(), &["add", "-A"]);
git(dir.path(), &["commit", "-q", "-m", "crlf"]);
let repo = open(&cli, dir.path());
assert!(repo.status().unwrap().files.is_empty());
assert_eq!(
repo.show("crlf.php", Rev::Head).unwrap().text.as_deref(),
Some("<?php\necho 1;\n"),
"the blob as stored, without line-ending conversion"
);
}
#[test]
fn unicode_and_space_paths_round_trip() {
let Some(cli) = installed() else { return };
let dir = tempfile::tempdir().unwrap();
init(dir.path());
let name = "Ünïcode dir/€ file \"quoted\" ü.php";
let name = if cfg!(windows) {
"Ünïcode dir/€ file 'quoted' ü.php"
} else {
name
};
write(dir.path(), name, "<?php\n");
let repo = open(&cli, dir.path());
assert_eq!(
states(&repo, name),
Some((FileState::Untracked, FileState::Untracked))
);
repo.stage(&[name.to_string()]).unwrap();
assert_eq!(
states(&repo, name),
Some((FileState::Added, FileState::Unmodified))
);
#[cfg(unix)]
{
use std::os::unix::ffi::OsStrExt;
write(dir.path(), "star*.php", "<?php\n");
write(dir.path(), "starX.php", "<?php\n");
repo.stage(&["star*.php".into()]).unwrap();
assert_eq!(
states(&repo, "starX.php"),
Some((FileState::Untracked, FileState::Untracked)),
"paths are literal, not patterns"
);
let raw = std::ffi::OsStr::from_bytes(b"caf\xe9.php");
std::fs::write(dir.path().join(raw), "<?php\n").unwrap();
assert_eq!(
states(&repo, "caf\u{fffd}.php"),
Some((FileState::Untracked, FileState::Untracked)),
"a non-UTF-8 name is listed lossily instead of failing the status"
);
}
assert_eq!(
repo.show(name, Rev::Index).unwrap().text.as_deref(),
Some("<?php\n")
);
}
#[test]
fn detached_head_and_branches() {
let Some(cli) = installed() else { return };
let dir = tempfile::tempdir().unwrap();
init(dir.path());
write(dir.path(), "a.php", "<?php // main\n");
git(dir.path(), &["add", "-A"]);
git(dir.path(), &["commit", "-q", "-m", "base"]);
let repo = open(&cli, dir.path());
repo.create_branch("feature/x", None, false).unwrap();
for bad in ["bad..name", "-x", "@{-1}", "with space", ""] {
let err = repo.create_branch(bad, None, false).unwrap_err();
assert!(matches!(err, VcsError::InvalidName(_)), "{bad}: {err:?}");
}
assert!(repo.create_branch("feature/x", None, false).is_err());
let branches = repo.branches().unwrap();
assert_eq!(branches.current.as_deref(), Some("main"));
let names: Vec<_> = branches.local.iter().map(|b| b.name.as_str()).collect();
assert_eq!(names, vec!["feature/x", "main"]);
repo.checkout("feature/x").unwrap();
assert_eq!(
repo.status().unwrap().head.branch.as_deref(),
Some("feature/x")
);
write(dir.path(), "a.php", "<?php // feature\n");
repo.stage(&["a.php".into()]).unwrap();
repo.commit("feature", false).unwrap();
repo.checkout("main").unwrap();
write(dir.path(), "a.php", "<?php // dirty on main\n");
let err = repo.checkout("feature/x").unwrap_err();
assert!(
matches!(&err, VcsError::Git(m) if m.contains("overwritten")),
"{err:?}"
);
assert!(matches!(
repo.checkout("nope").unwrap_err(),
VcsError::Git(_)
));
git(dir.path(), &["checkout", "-q", "--", "a.php"]);
repo.create_branch("topic", Some("feature/x"), true)
.unwrap();
assert_eq!(repo.branches().unwrap().current.as_deref(), Some("topic"));
git(dir.path(), &["checkout", "-q", "--detach", "HEAD"]);
let head = repo.head().unwrap();
assert!(head.detached);
assert_eq!(head.branch, None);
assert!(head.head.is_some());
assert_eq!(repo.branches().unwrap().current, None);
}
#[test]
fn remote_branches_are_listed_and_checked_out_as_tracking_branches() {
let Some(cli) = installed() else { return };
let upstream = tempfile::tempdir().unwrap();
init(upstream.path());
write(upstream.path(), "a.php", "<?php\n");
git(upstream.path(), &["add", "-A"]);
git(upstream.path(), &["commit", "-q", "-m", "base"]);
git(upstream.path(), &["branch", "remote-only"]);
let clone = tempfile::tempdir().unwrap();
git(
clone.path(),
&["clone", "-q", upstream.path().to_str().unwrap(), "."],
);
let repo = open(&cli, clone.path());
let branches = repo.branches().unwrap();
let remote: Vec<_> = branches.remote.iter().map(|b| b.name.as_str()).collect();
assert_eq!(remote, vec!["origin/main", "origin/remote-only"]);
assert_eq!(branches.local[0].upstream.as_deref(), Some("origin/main"));
let status = repo.status().unwrap();
assert_eq!(status.head.upstream.as_deref(), Some("origin/main"));
assert_eq!((status.head.ahead, status.head.behind), (Some(0), Some(0)));
repo.checkout("origin/remote-only").unwrap();
let branches = repo.branches().unwrap();
assert_eq!(branches.current.as_deref(), Some("remote-only"));
}
#[test]
fn large_and_binary_files() {
let Some(cli) = installed() else { return };
let dir = tempfile::tempdir().unwrap();
init(dir.path());
write(dir.path(), "big.txt", vec![b'a'; FILE_CAP + 1]);
write(dir.path(), "image.png", b"\x89PNG\r\n\x1a\n\0\0\0");
write(dir.path(), "latin1.php", b"<?php // caf\xe9\n");
write(dir.path(), "bom.php", b"\xEF\xBB\xBF<?php\n");
git(dir.path(), &["add", "-A"]);
let repo = open(&cli, dir.path());
let big = repo.show("big.txt", Rev::Index).unwrap();
assert!(big.too_large && big.text.is_none());
let image = repo.show("image.png", Rev::Index).unwrap();
assert!(image.binary && image.text.is_none());
assert!(repo.show("latin1.php", Rev::Index).unwrap().binary);
assert_eq!(
repo.show("bom.php", Rev::Index).unwrap().text.as_deref(),
Some("<?php\n")
);
assert_eq!(
repo.show("src", Rev::Index).unwrap().text,
None,
"a missing path"
);
}
#[test]
fn a_failing_hook_reports_its_output() {
let Some(cli) = installed() else { return };
let dir = tempfile::tempdir().unwrap();
init(dir.path());
write(
dir.path(),
".git/hooks/pre-commit",
"#!/bin/sh\necho 'lint failed: bad.php line 3' >&2\nexit 1\n",
);
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
let hook = dir.path().join(".git/hooks/pre-commit");
std::fs::set_permissions(hook, std::fs::Permissions::from_mode(0o755)).unwrap();
}
write(dir.path(), "a.php", "<?php\n");
let repo = open(&cli, dir.path());
repo.stage(&["a.php".into()]).unwrap();
let err = repo.commit("blocked", false).unwrap_err();
assert!(
matches!(&err, VcsError::Git(m) if m.contains("lint failed: bad.php line 3")),
"{err:?}"
);
assert_eq!(repo.status().unwrap().head.head, None, "nothing committed");
}
#[test]
fn nothing_staged_is_refused_with_gits_message() {
let Some(cli) = installed() else { return };
let dir = tempfile::tempdir().unwrap();
init(dir.path());
let repo = open(&cli, dir.path());
assert!(matches!(
repo.commit("empty", false).unwrap_err(),
VcsError::Git(_)
));
}
#[test]
fn a_project_inside_a_repository_sees_its_own_files() {
let Some(cli) = installed() else { return };
let dir = tempfile::tempdir().unwrap();
init(dir.path());
write(dir.path(), "outside.php", "<?php\n");
write(dir.path(), "app/inside.php", "<?php\n");
let project = dir.path().join("app");
let repo = open(&cli, &project);
assert_eq!(repo.prefix(), "app/");
let paths: Vec<_> = repo
.status()
.unwrap()
.files
.into_iter()
.map(|f| f.path)
.collect();
assert_eq!(paths, vec!["inside.php"]);
repo.stage(&["inside.php".into()]).unwrap();
assert_eq!(
states(&repo, "inside.php"),
Some((FileState::Added, FileState::Unmodified))
);
for bad in ["../outside.php", "/etc/passwd", "", "a\nb"] {
let err = repo.stage(&[bad.into()]).unwrap_err();
assert!(matches!(err, VcsError::InvalidPath(_)), "{bad}: {err:?}");
}
}
#[test]
fn the_watch_sees_outside_changes_and_skips_rebased_ones() {
let Some(cli) = installed() else { return };
let dir = tempfile::tempdir().unwrap();
init(dir.path());
write(dir.path(), "a.php", "<?php\n");
let repo = open(&cli, dir.path());
let watch = RepoWatch::start(repo.git_dir(), repo.common_dir(), Duration::from_millis(20));
std::thread::sleep(Duration::from_millis(60));
assert!(!watch.changed());
git(dir.path(), &["add", "-A"]);
let deadline = Instant::now() + Duration::from_secs(5);
while !watch.changed() {
assert!(Instant::now() < deadline, "the change was not seen");
std::thread::sleep(Duration::from_millis(10));
}
git(dir.path(), &["commit", "-q", "-m", "x"]);
watch.rebase();
std::thread::sleep(Duration::from_millis(100));
let _ = watch.changed();
git(dir.path(), &["branch", "other"]);
let deadline = Instant::now() + Duration::from_secs(5);
while !watch.changed() {
assert!(Instant::now() < deadline, "the new branch was not seen");
std::thread::sleep(Duration::from_millis(10));
}
}