//! 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 { 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, 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, /// 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), } /// 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, } /// Local and remote branches. #[derive(Debug, Clone, Default, PartialEq, Eq)] pub struct Branches { /// The checked-out branch; `None` when detached. pub current: Option, /// Local branches, sorted by name. pub local: Vec, /// Remote-tracking branches, sorted by name, without `origin/HEAD`. pub remote: Vec, } /// 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::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 { 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 { 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, 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 { 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 { 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 { 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 { 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 { 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:` or `:0:` (a root-relative /// path) as stored. /// /// # Errors /// The runner's errors or [`VcsError::BadOutput`]. pub(crate) fn read_object(&self, object: &str) -> Result { 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 { 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 { Ok(self .run(Call::read( &self.root, &["show-ref", "--verify", "--quiet", refname], 4096, ))? .success()) } /// The configured `remote..fetch` refspecs. /// /// # Errors /// The runner's errors; no configured remote is an empty list. fn fetch_specs(&self) -> Result, 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, 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) -> 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() }, } }