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>
430 lines
14 KiB
Rust
430 lines
14 KiB
Rust
//! 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);
|
|
}
|
|
}
|
|
}
|