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:
parent
cd8c34b094
commit
13e7b0aa12
28 changed files with 3485 additions and 9 deletions
60
crates/vcs/src/error.rs
Normal file
60
crates/vcs/src/error.rs
Normal 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
32
crates/vcs/src/lib.rs
Normal 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
430
crates/vcs/src/porcelain.rs
Normal 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
666
crates/vcs/src/repo.rs
Normal 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
374
crates/vcs/src/runner.rs
Normal 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
150
crates/vcs/src/watch.rs
Normal 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);
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue