Lutra/crates/vcs/src/repo.rs
danny 301443db7d C3: chunk staging, unstaging and revert from the gutter and the diff viewer
- crates/vcs chunk.rs: chunks of a file (buffer text vs index, HEAD vs
  index), a minimal patch applied with git apply --cached, revert as a
  byte edit; token refusal when buffer, index or HEAD changed; CRLF
  (autocrlf and stored), no final newline, BOM, staged renames, first
  commit; binary and untracked refused. Real-git tests + property test.
- engine: git.chunks, git.stageChunk, git.unstageChunk, git.revertChunk
  (revert edits the buffer under the lock, undoable in the editor);
  cmd::git::start_then; git.lineChanges shares the vcs line diff.
- UI: chunk popup on a gutter marker click (Stage / Unstage / Revert /
  Previous / Next), hollow staged markers, vcs.showChunk, diff viewer
  hint, "partly staged" badge in the Changes window.
- Docs: G8 row, Git parity row evidence, ui-parity, architecture.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 12:50:11 +01:00

767 lines
25 KiB
Rust

//! 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, FetchSpec, 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).
pub(crate) const SMALL_CAP: usize = 16 * 1024 * 1024;
/// How many leading bytes [`Repo::show`] checks for NUL, as git does.
pub(crate) 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
}
/// The program that runs (for the remote calls in `remote.rs`).
pub(crate) fn executable(&self) -> &Path {
&self.executable
}
/// 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,
}
/// An object read by [`Repo::read_object`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum Object {
/// It does not exist (or is a tree).
Missing,
/// It is not a blob (a submodule).
NotBlob,
/// It is larger than [`FILE_CAP`].
TooLarge,
/// The blob's bytes as stored.
Blob(Vec<u8>),
}
/// 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 a change made outside this file (`remote.rs`) with the
/// changes made here.
pub(crate) fn mutation_guard(&self) -> MutexGuard<'_, ()> {
self.lock()
}
/// Serialises changes: the guard of [`Repo::mutations`]. A poisoned
/// lock is taken over: the lock guards no data.
pub(crate) fn lock(&self) -> MutexGuard<'_, ()> {
self.mutations
.lock()
.unwrap_or_else(PoisonError::into_inner)
}
/// Runs git in the work tree root.
pub(crate) 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).
pub(crate) 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}"),
Rev::Index => format!(":0:{path}"),
};
Ok(match self.read_object(&object)? {
Object::Missing => Contents::default(),
Object::NotBlob => Contents {
binary: true,
..Contents::default()
},
Object::TooLarge => Contents {
too_large: true,
..Contents::default()
},
Object::Blob(bytes) => decode(bytes),
})
}
/// Reads an object such as `HEAD:<path>` or `:0:<path>` (a root-relative
/// path) as stored.
///
/// # Errors
/// The runner's errors or [`VcsError::BadOutput`].
pub(crate) fn read_object(&self, object: &str) -> Result<Object, VcsError> {
let output = self
.run(
Call::read(&self.root, &["cat-file", "--batch-check"], SMALL_CAP).stdin(
format!(
"{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(Object::Missing);
};
if *size == "missing" || *kind == "missing" || *kind == "tree" {
return Ok(Object::Missing);
}
if *kind != "blob" {
return Ok(Object::NotBlob);
}
let size: usize = size
.parse()
.map_err(|_| VcsError::BadOutput(line.to_string()))?;
if size > FILE_CAP {
return Ok(Object::TooLarge);
}
let output = self
.run(Call::read(&self.root, &["cat-file", "blob", oid], FILE_CAP))?
.checked()?;
Ok(Object::Blob(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())
}
/// The configured `remote.<name>.fetch` refspecs.
///
/// # Errors
/// The runner's errors; no configured remote is an empty list.
fn fetch_specs(&self) -> Result<Vec<FetchSpec>, VcsError> {
let output = self.run(Call::read(
&self.root,
&["config", "-z", "--get-regexp", r"^remote\..*\.fetch$"],
SMALL_CAP,
))?;
if !output.success() {
return Ok(Vec::new());
}
Ok(porcelain::parse_fetch_specs(&output.stdout))
}
/// Checks out a local branch, or creates a local branch from a remote
/// one (`origin/feature` → `feature`). Hooks run (120 s).
///
/// The new branch tracks the remote one when a configured fetch refspec
/// maps a branch to it (the name comes from that refspec, as git
/// derives it). Without one (the remote was removed, or the ref was
/// created by hand) git could not set up tracking and would fail after
/// updating the work tree, so the branch is created with `--no-track`,
/// named after the part behind the first `/`.
///
/// # Errors
/// [`VcsError::InvalidName`], [`VcsError::Git`] for an unknown branch
/// or when git refuses (local changes would be overwritten, the local
/// branch exists already); git's message is passed on.
pub fn checkout(&self, branch: &str) -> Result<(), VcsError> {
check_name(branch)?;
let _guard = self.lock();
let remote_ref = format!("refs/remotes/{branch}");
let local;
let args: Vec<&str> = if self.ref_exists(&format!("refs/heads/{branch}"))? {
vec!["switch", "-q", branch]
} else if self.ref_exists(&remote_ref)? {
let tracked = porcelain::tracking_name(&self.fetch_specs()?, &remote_ref);
let track = if tracked.is_some() {
"--track"
} else {
"--no-track"
};
local = tracked
.or_else(|| branch.split_once('/').map(|(_, rest)| rest.to_string()))
.unwrap_or_default();
check_name(&local)?;
vec!["switch", "-q", "-c", &local, track, branch]
} else {
return Err(VcsError::Git(format!("no branch named {branch}")));
};
self.run(Call::write(&self.root, &args).timeout(HOOK_TIMEOUT))?
.checked()?;
Ok(())
}
/// The full message of the last commit, for prefilling an amend.
///
/// # Returns
/// `None` before the first commit; otherwise the raw message (`%B`)
/// with trailing line breaks removed.
///
/// # Errors
/// The runner's errors or git's refusal.
pub fn last_message(&self) -> Result<Option<String>, VcsError> {
if !self.has_head()? {
return Ok(None);
}
let output = self
.run(Call::read(
&self.root,
&["show", "-s", "--format=%B", "HEAD"],
SMALL_CAP,
))?
.checked()?;
let text = String::from_utf8_lossy(&output.stdout);
Ok(Some(text.trim_end_matches(['\n', '\r']).to_string()))
}
/// 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.
pub(crate) 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()
},
}
}