mod discover;
mod report;
mod run;
mod tracked;
pub(crate) use run::for_git;
use std::io;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
use rayon::prelude::*;
use crate::report::exit;
use crate::scan::PatternSet;
pub use discover::repository_at;
pub use report::{document, render_human, render_json, write_sweep_block};
pub use tracked::{holding_tracked_files, index_listing};
use discover::{Located, Resolution};
use run::{ensure_git_available, run_step};
pub const SCHEMA_VERSION: u32 = 1;
const DOT_GIT: &str = ".git";
pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(300);
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum GitError {
#[error("`git` was not found on PATH — voom delegates git housekeeping to git itself")]
NotInstalled,
#[error("running `git`")]
Spawn {
#[source]
source: io::Error,
},
#[error("resolving `{}`", path.display())]
Root {
path: PathBuf,
#[source]
source: io::Error,
},
#[error("building a worker pool of {jobs} threads")]
ThreadPool {
jobs: usize,
#[source]
source: rayon::ThreadPoolBuildError,
},
}
#[expect(
clippy::struct_excessive_bools,
reason = "these mirror command-line flags, which are bools by nature"
)]
#[derive(Debug)]
pub struct GitPruneOptions {
pub roots: Vec<PathBuf>,
pub dry_run: bool,
pub jobs: Option<usize>,
pub one_file_system: bool,
pub timeout: Duration,
pub exclude: PatternSet,
pub remotes: bool,
pub worktree_expire: String,
pub count_objects: bool,
}
impl Default for GitPruneOptions {
fn default() -> Self {
Self {
roots: Vec::new(),
dry_run: false,
jobs: None,
one_file_system: true,
timeout: DEFAULT_TIMEOUT,
exclude: PatternSet::default(),
remotes: false,
worktree_expire: WORKTREE_PRUNE_EXPIRE.to_owned(),
count_objects: false,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum Skipped {
#[error("a git operation is in progress ({marker})")]
InProgress {
marker: String,
},
#[error("a protected path")]
Protected,
#[error("outside every scan root")]
EscapesRoot,
#[error("voom could not resolve its `.git` file: {detail}")]
Unresolved {
detail: String,
},
}
impl Skipped {
#[must_use]
pub fn is_actionable(&self) -> bool {
match self {
Self::InProgress { .. } | Self::Protected => true,
Self::EscapesRoot | Self::Unresolved { .. } => false,
}
}
#[must_use]
pub fn code(&self) -> &'static str {
match self {
Self::InProgress { .. } => "operation_in_progress",
Self::Protected => "protected",
Self::EscapesRoot => "escapes_root",
Self::Unresolved { .. } => "unresolved",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StepKind {
WorktreePrune,
RemoteList,
RemotePrune,
Gc,
CountObjects,
}
impl StepKind {
#[must_use]
pub fn code(self) -> &'static str {
match self {
Self::WorktreePrune => "worktree_prune",
Self::RemoteList => "remote_list",
Self::RemotePrune => "remote_prune",
Self::Gc => "gc",
Self::CountObjects => "count_objects",
}
}
#[must_use]
pub fn label(self) -> &'static str {
match self {
Self::WorktreePrune => "worktree prune",
Self::RemoteList => "remote",
Self::RemotePrune => "remote prune",
Self::Gc => "gc",
Self::CountObjects => "count-objects",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum StepOutcome {
Succeeded {
summary: String,
},
Failed {
code: Option<i32>,
message: String,
},
TimedOut,
}
#[derive(Debug, Clone)]
pub struct Step {
pub kind: StepKind,
pub remote: Option<String>,
pub command: Vec<String>,
pub outcome: StepOutcome,
}
impl Step {
#[must_use]
pub fn label(&self) -> String {
match &self.remote {
Some(remote) => format!("{} {remote}", self.kind.label()),
None => self.kind.label().to_owned(),
}
}
#[must_use]
pub fn succeeded(&self) -> bool {
matches!(self.outcome, StepOutcome::Succeeded { .. })
}
#[must_use]
pub fn summary(&self) -> Option<&str> {
match &self.outcome {
StepOutcome::Succeeded { summary } if !summary.is_empty() => Some(summary),
_ => None,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Status {
Pruned,
Skipped,
Failed,
}
#[derive(Debug, Clone)]
pub struct Repository {
pub path: PathBuf,
pub skipped: Option<Skipped>,
pub steps: Vec<Step>,
}
impl Repository {
#[must_use]
pub fn status(&self) -> Status {
if self.skipped.is_some() {
return Status::Skipped;
}
if self.steps.iter().all(Step::succeeded) {
Status::Pruned
} else {
Status::Failed
}
}
#[must_use]
pub fn has_pending_work(&self) -> bool {
self.steps.iter().any(|step| {
matches!(step.kind, StepKind::WorktreePrune | StepKind::RemotePrune) && step.summary().is_some()
})
}
#[must_use]
pub fn is_noteworthy(&self, verbose: bool) -> bool {
match self.status() {
Status::Failed => true,
Status::Skipped => verbose || self.skipped.as_ref().is_none_or(Skipped::is_actionable),
Status::Pruned => self.steps.iter().any(|step| step.summary().is_some()),
}
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Totals {
pub repositories: usize,
pub pruned: usize,
pub would_prune: usize,
pub skipped: usize,
pub failed: usize,
}
#[derive(Debug)]
pub struct GitPruneResult {
pub roots: Vec<PathBuf>,
pub repositories: Vec<Repository>,
pub dry_run: bool,
pub elapsed: Duration,
}
impl GitPruneResult {
#[must_use]
pub fn totals(&self) -> Totals {
let mut totals = Totals {
repositories: self.repositories.len(),
..Totals::default()
};
for repository in &self.repositories {
match repository.status() {
Status::Pruned => {
totals.pruned += 1;
totals.would_prune += usize::from(repository.has_pending_work());
}
Status::Skipped => totals.skipped += 1,
Status::Failed => totals.failed += 1,
}
}
totals
}
#[must_use]
pub fn noteworthy(&self, verbose: bool) -> Vec<&Repository> {
self.repositories
.iter()
.filter(|repository| repository.is_noteworthy(verbose))
.collect()
}
pub fn merge(&mut self, other: Self) {
for root in other.roots {
if !self.roots.contains(&root) {
self.roots.push(root);
}
}
for repository in other.repositories {
if !self.repositories.iter().any(|seen| seen.path == repository.path) {
self.repositories.push(repository);
}
}
self.repositories.sort_by(|left, right| left.path.cmp(&right.path));
self.elapsed += other.elapsed;
}
#[must_use]
pub fn exit_code(&self) -> i32 {
if self.totals().failed > 0 {
exit::REMOVAL_FAILED
} else {
exit::SUCCESS
}
}
}
pub fn prune(options: &GitPruneOptions) -> Result<GitPruneResult, GitError> {
let started = Instant::now();
let work_trees = discover::repositories(options);
let mut result = prune_repositories(&work_trees, options)?;
result.elapsed = started.elapsed();
Ok(result)
}
pub fn prune_repositories(work_trees: &[PathBuf], options: &GitPruneOptions) -> Result<GitPruneResult, GitError> {
prune_with(work_trees, options, true)
}
#[must_use]
pub fn prune_during_sweep(work_trees: &[PathBuf], options: &GitPruneOptions) -> Option<GitPruneResult> {
if work_trees.is_empty() {
return None;
}
prune_with(work_trees, options, false).ok()
}
fn prune_with(work_trees: &[PathBuf], options: &GitPruneOptions, own_pool: bool) -> Result<GitPruneResult, GitError> {
let started = Instant::now();
let roots = canonical_roots(&options.roots)?;
let mut result = GitPruneResult {
roots,
repositories: Vec::new(),
dry_run: options.dry_run,
elapsed: Duration::default(),
};
if work_trees.is_empty() {
return Ok(result);
}
ensure_git_available(options.timeout)?;
let resolved = discover::resolve_all(work_trees, &result.roots);
result.repositories = if own_pool {
let jobs = options
.jobs
.map_or_else(crate::limits::default_width, |jobs| jobs.max(1));
rayon::ThreadPoolBuilder::new()
.num_threads(jobs)
.build()
.map_err(|source| GitError::ThreadPool { jobs, source })?
.install(|| visit_all(&resolved, options))
} else {
visit_all(&resolved, options)
};
result.repositories.sort_by(|left, right| left.path.cmp(&right.path));
result.elapsed = started.elapsed();
Ok(result)
}
#[must_use]
pub fn discover_repositories(options: &GitPruneOptions) -> Vec<PathBuf> {
discover::repositories(options)
}
fn visit_all(resolved: &[Resolution], options: &GitPruneOptions) -> Vec<Repository> {
resolved
.par_iter()
.map(|resolution| match resolution {
Resolution::Repository(located) => visit(located, options),
Resolution::Refused(path, skipped) => Repository {
path: path.clone(),
skipped: Some(skipped.clone()),
steps: Vec::new(),
},
})
.collect()
}
fn canonical_roots(roots: &[PathBuf]) -> Result<Vec<PathBuf>, GitError> {
roots
.iter()
.map(|root| {
root.canonicalize().map_err(|source| GitError::Root {
path: root.clone(),
source,
})
})
.collect()
}
fn visit(located: &Located, options: &GitPruneOptions) -> Repository {
let path = located.work_tree().to_path_buf();
let common_dir = located.common_dir().to_path_buf();
if let Some(marker) = discover::in_progress(located.common_dir()) {
let marker = marker
.strip_prefix(&path)
.unwrap_or(&marker)
.display()
.to_string()
.replace(std::path::MAIN_SEPARATOR, "/");
return Repository {
path,
skipped: Some(Skipped::InProgress { marker }),
steps: Vec::new(),
};
}
let deadline = Instant::now() + options.timeout;
let worktree_prune = worktree_prune_args(options.dry_run, &options.worktree_expire);
let borrowed: Vec<&str> = worktree_prune.iter().map(String::as_str).collect();
let mut steps = vec![run_step(
&path,
&common_dir,
StepKind::WorktreePrune,
None,
&borrowed,
deadline,
)];
if options.remotes && steps.iter().all(Step::succeeded) {
prune_remotes(&path, &common_dir, options.dry_run, deadline, &mut steps);
}
if steps.iter().all(Step::succeeded)
&& let Some((kind, args)) = repack_step(options)
{
steps.push(run_step(&path, &common_dir, kind, None, &args, deadline));
}
Repository {
path,
skipped: None,
steps,
}
}
pub const WORKTREE_PRUNE_EXPIRE: &str = "3.months.ago";
fn worktree_prune_args(dry_run: bool, expire: &str) -> Vec<String> {
let mut args = vec!["worktree", "prune", "--expire", expire, "-v"];
if dry_run {
args.insert(2, "-n");
}
args.into_iter().map(ToOwned::to_owned).collect()
}
fn repack_step(options: &GitPruneOptions) -> Option<(StepKind, Vec<&'static str>)> {
match (options.dry_run, options.count_objects) {
(false, _) => Some((StepKind::Gc, vec!["gc", "--auto"])),
(true, true) => Some((StepKind::CountObjects, vec!["count-objects", "-v"])),
(true, false) => None,
}
}
fn prune_remotes(path: &Path, git_dir: &Path, dry_run: bool, deadline: Instant, steps: &mut Vec<Step>) {
let listing = run_step(path, git_dir, StepKind::RemoteList, None, &["remote"], deadline);
let Some(names) = listing.summary().map(remote_names) else {
if !listing.succeeded() {
steps.push(listing);
}
return;
};
for remote in names {
let args = remote_prune_args(dry_run, &remote);
let borrowed: Vec<&str> = args.iter().map(String::as_str).collect();
let step = run_step(path, git_dir, StepKind::RemotePrune, Some(remote), &borrowed, deadline);
let succeeded = step.succeeded();
steps.push(step);
if !succeeded {
return;
}
}
}
fn remote_names(listing: &str) -> Vec<String> {
listing
.lines()
.map(str::trim)
.filter(|line| !line.is_empty())
.map(ToOwned::to_owned)
.collect()
}
fn remote_prune_args(dry_run: bool, remote: &str) -> Vec<String> {
let mut args = vec!["remote".to_owned(), "prune".to_owned()];
if dry_run {
args.push("-n".to_owned());
}
args.push(remote.to_owned());
args
}
#[cfg(test)]
mod tests {
#[test]
fn should_name_only_actionable_skips_in_a_sweep() {
assert!(
Skipped::InProgress {
marker: ".git/rebase-merge".to_owned()
}
.is_actionable()
);
assert!(Skipped::Protected.is_actionable());
assert!(!Skipped::EscapesRoot.is_actionable());
assert!(
!Skipped::Unresolved {
detail: "its gitdir does not resolve".to_owned()
}
.is_actionable()
);
}
use super::*;
#[test]
fn should_repack_only_on_gits_own_thresholds() {
let (kind, args) = repack_step(&GitPruneOptions::default()).expect("a repack step");
assert_eq!(kind, StepKind::Gc);
assert_eq!(args, vec!["gc", "--auto"], "never a bare `gc`");
}
#[test]
fn should_build_no_networked_command_by_default() {
let options = GitPruneOptions::default();
assert!(!options.remotes, "the network step is opt-in");
let mut argv = worktree_prune_args(options.dry_run, &options.worktree_expire);
argv.extend(
repack_step(&options)
.into_iter()
.flat_map(|(_, args)| args.into_iter().map(ToOwned::to_owned)),
);
assert_eq!(
argv,
vec!["worktree", "prune", "--expire", "3.months.ago", "-v", "gc", "--auto"]
);
}
#[test]
fn should_prune_worktrees_on_gits_own_expiry_and_never_on_none() {
assert_eq!(GitPruneOptions::default().worktree_expire, "3.months.ago");
let argv = worktree_prune_args(false, WORKTREE_PRUNE_EXPIRE);
let expiry = argv.iter().position(|arg| arg.as_str() == "--expire");
assert!(expiry.is_some(), "the step always carries an expiry: {argv:?}");
}
#[test]
fn should_withhold_the_object_census_from_a_sweeps_dry_run() {
let sweep = GitPruneOptions {
dry_run: true,
..GitPruneOptions::default()
};
assert!(repack_step(&sweep).is_none());
let subcommand = GitPruneOptions {
dry_run: true,
count_objects: true,
..GitPruneOptions::default()
};
assert_eq!(
repack_step(&subcommand).map(|(kind, _)| kind),
Some(StepKind::CountObjects)
);
}
}