feat: basic gix clean

Author: Byron

.gitignore

@@ -6,9 +6,15 @@ target/
 
 # repositories used for local testing
 /tests/fixtures/repos
+$/tests/fixtures/repos/
+
 /tests/fixtures/commit-graphs/
+$/tests/fixtures/commit-graphs/
 
 **/generated-do-not-edit/
 
 # Cargo lock files of fuzz targets - let's have the latest versions of everything under test
 **/fuzz/Cargo.lock
+
+# newer Git sees these as precious, older Git falls through to the pattern above
+$**/fuzz/Cargo.lock

Cargo.toml

@@ -129,7 +129,7 @@ prodash-render-line = ["prodash/render-line", "prodash-render-line-crossterm", "
 cache-efficiency-debug = ["gix-features/cache-efficiency-debug"]
 
 ##  A way to enable most `gitoxide-core` tools found in `ein tools`, namely `organize` and `estimate hours`.
-gitoxide-core-tools = ["gitoxide-core/organize", "gitoxide-core/estimate-hours", "gitoxide-core-tools-archive"]
+gitoxide-core-tools = ["gitoxide-core/organize", "gitoxide-core/estimate-hours", "gitoxide-core-tools-archive", "gitoxide-core-tools-clean"]
 
 ## A program to perform analytics on a `git` repository, using an auto-maintained sqlite database
 gitoxide-core-tools-query = ["gitoxide-core/query"]
@@ -140,6 +140,9 @@ gitoxide-core-tools-corpus = ["gitoxide-core/corpus"]
 ## A sub-command to generate archive from virtual worktree checkouts.
 gitoxide-core-tools-archive = ["gitoxide-core/archive"]
 
+## A sub-command to clean the worktree from untracked and ignored files.
+gitoxide-core-tools-clean = ["gitoxide-core/clean"]
+
 #! ### Building Blocks for mutually exclusive networking
 #! Blocking and async features are mutually exclusive and cause a compile-time error. This also means that `cargo … --all-features` will fail.
 #! Within each section, features can be combined.

gitoxide-core/Cargo.toml

@@ -28,6 +28,9 @@ corpus = [ "dep:rusqlite", "dep:sysinfo", "organize", "dep:crossbeam-channel", "
 ## The ability to create archives from virtual worktrees, similar to `git archive`.
 archive = ["dep:gix-archive-for-configuration-only", "gix/worktree-archive"]
 
+## The ability to clean a repository, similar to `git clean`.
+clean = [ "gix/dirwalk" ]
+
 #! ### Mutually Exclusive Networking
 #! If both are set, _blocking-client_ will take precedence, allowing `--all-features` to be used.
 

gitoxide-core/src/repository/clean.rs

@@ -0,0 +1,220 @@
+use crate::OutputFormat;
+
+pub struct Options {
+    pub debug: bool,
+    pub format: OutputFormat,
+    pub execute: bool,
+    pub ignored: bool,
+    pub precious: bool,
+    pub directories: bool,
+    pub skip_hidden_nonbare_repositories: bool,
+}
+pub(crate) mod function {
+    use crate::repository::clean::Options;
+    use crate::OutputFormat;
+    use anyhow::bail;
+    use gix::bstr::BString;
+    use gix::dir::entry::{Kind, Status};
+    use gix::dir::walk::EmissionMode::CollapseDirectory;
+    use gix::dir::walk::ForDeletionMode::*;
+    use std::borrow::Cow;
+
+    pub fn clean(
+        repo: gix::Repository,
+        out: &mut dyn std::io::Write,
+        err: &mut dyn std::io::Write,
+        patterns: Vec<BString>,
+        Options {
+            debug,
+            format,
+            execute,
+            ignored,
+            precious,
+            directories,
+            skip_hidden_nonbare_repositories,
+        }: Options,
+    ) -> anyhow::Result<()> {
+        if format != OutputFormat::Human {
+            bail!("JSON output isn't implemented yet");
+        }
+        let Some(workdir) = repo.work_dir() else {
+            bail!("Need a worktree to clean, this is a bare repository");
+        };
+
+        let index = repo.index()?;
+        let has_patterns = !patterns.is_empty();
+        let mut collect = gix::dir::walk::delegate::Collect::default();
+        let emission_mode = CollapseDirectory;
+        let options = repo
+            .dirwalk_options()?
+            .emit_pruned(true)
+            .emit_ignored((ignored || precious).then_some(emission_mode))
+            .for_deletion(
+                if (ignored || precious) && directories && skip_hidden_nonbare_repositories {
+                    FindRepositoriesInIgnoredDirectories
+                } else {
+                    IgnoredDirectoriesCanHideNestedRepositories
+                }
+                .into(),
+            )
+            .emit_untracked(emission_mode)
+            .emit_empty_directories(true);
+        repo.dirwalk(&index, patterns, options, &mut collect)?;
+
+        let entries = collect.into_entries_by_path();
+        let mut entries_to_clean = 0;
+        let mut skipped_directories = 0;
+        let mut pruned_entries = 0;
+        for (entry, dir_status) in entries.into_iter() {
+            if dir_status.is_some() {
+                if debug {
+                    writeln!(
+                        err,
+                        "DBG: prune '{}' {:?} as parent dir is used instead",
+                        entry.rela_path, entry.status
+                    )
+                    .ok();
+                }
+                continue;
+            }
+
+            pruned_entries += usize::from(entry.pathspec_match.is_none());
+            if entry.status.is_pruned() || entry.pathspec_match.is_none() {
+                continue;
+            }
+            let disk_kind = entry.disk_kind.expect("present if not pruned");
+            match disk_kind {
+                Kind::File | Kind::Symlink => {}
+                Kind::EmptyDirectory | Kind::Directory | Kind::Repository => {
+                    let keep = directories
+                        || entry
+                            .pathspec_match
+                            .map_or(false, |m| m != gix::dir::entry::PathspecMatch::Always);
+                    if !keep {
+                        skipped_directories += 1;
+                        if debug {
+                            writeln!(err, "DBG: prune '{}' as -d is missing", entry.rela_path).ok();
+                        }
+                        continue;
+                    }
+                }
+            };
+
+            let keep = entry
+                .pathspec_match
+                .map_or(true, |m| m != gix::dir::entry::PathspecMatch::Excluded);
+            if !keep {
+                if debug {
+                    writeln!(err, "DBG: prune '{}' as it is excluded by pathspec", entry.rela_path).ok();
+                }
+                continue;
+            }
+
+            let keep = match entry.status {
+                Status::DotGit | Status::Pruned | Status::TrackedExcluded => {
+                    unreachable!("Pruned aren't emitted")
+                }
+                Status::Tracked => {
+                    unreachable!("tracked aren't emitted")
+                }
+                Status::Ignored(gix::ignore::Kind::Expendable) => ignored,
+                Status::Ignored(gix::ignore::Kind::Precious) => precious,
+                Status::Untracked => true,
+            };
+            if !keep {
+                if debug {
+                    writeln!(err, "DBG: prune '{}' as -x or -p is missing", entry.rela_path).ok();
+                }
+                continue;
+            }
+
+            if disk_kind == gix::dir::entry::Kind::Repository {
+                writeln!(
+                    err,
+                    "{maybe} skip repository {}",
+                    entry.rela_path,
+                    maybe = if execute { "Will" } else { "Would" }
+                )?;
+                continue;
+            }
+            writeln!(
+                out,
+                "{maybe} {}{} {status}",
+                entry.rela_path,
+                disk_kind.is_dir().then_some("/").unwrap_or_default(),
+                status = match entry.status {
+                    Status::Ignored(kind) => {
+                        Cow::Owned(format!(
+                            "({})",
+                            match kind {
+                                gix::ignore::Kind::Precious => "$",
+                                gix::ignore::Kind::Expendable => "❌",
+                            }
+                        ))
+                    }
+                    Status::Untracked => {
+                        "".into()
+                    }
+                    status =>
+                        if debug {
+                            format!("(DBG: {status:?})").into()
+                        } else {
+                            "".into()
+                        },
+                },
+                maybe = if execute { "removing" } else { "WOULD remove" },
+            )?;
+
+            if execute {
+                let path = workdir.join(gix::path::from_bstr(entry.rela_path));
+                if disk_kind.is_dir() {
+                    std::fs::remove_dir_all(path)?;
+                } else {
+                    std::fs::remove_file(path)?;
+                }
+            } else {
+                entries_to_clean += 1;
+            }
+        }
+        if !execute {
+            let mut messages = Vec::new();
+            messages.extend(
+                (skipped_directories > 0)
+                    .then(|| format!("Ignored {skipped_directories} directories - use -d to show")),
+            );
+            messages.extend(
+                (pruned_entries > 0 && has_patterns).then(|| {
+                    format!("try to adjust your pathspec to reveal some of the {pruned_entries} pruned entries")
+                }),
+            );
+            let make_msg = || -> String {
+                if messages.is_empty() {
+                    return String::new();
+                }
+                format!(" ({})", messages.join("; "))
+            };
+            if entries_to_clean > 0 {
+                if skip_hidden_nonbare_repositories {
+                    writeln!(
+                        err,
+                        "\nWARNING: would STILL remove all BARE repositories that are hidden inside of ignored directories{}", make_msg()
+                    )?;
+                } else {
+                    writeln!(
+                        err,
+                        "\nWARNING: would remove all repositories that are hidden inside of ignored directories{}",
+                        make_msg()
+                    )?;
+                }
+            } else {
+                let msg = if ignored {
+                    "No untracked or ignored files to clean"
+                } else {
+                    "No untracked files to clean - use -x or -p to show more"
+                };
+                writeln!(err, "{msg}{}", make_msg())?;
+            }
+        }
+        Ok(())
+    }
+}

gitoxide-core/src/repository/mod.rs

@@ -24,6 +24,10 @@ pub mod config;
 mod credential;
 pub use credential::function as credential;
 pub mod attributes;
+#[cfg(feature = "clean")]
+pub mod clean;
+#[cfg(feature = "clean")]
+pub use clean::function::clean;
 #[cfg(feature = "blocking-client")]
 pub mod clone;
 pub mod exclude;

src/plumbing/main.rs

@@ -146,6 +146,40 @@ pub fn main() -> Result<()> {
     }
 
     match cmd {
+        #[cfg(feature = "gitoxide-core-tools-clean")]
+        Subcommands::Clean(crate::plumbing::options::clean::Command {
+            debug,
+            execute,
+            ignored,
+            precious,
+            directories,
+            pathspec,
+            skip_hidden_nonbare_repositories,
+        }) => prepare_and_run(
+            "clean",
+            trace,
+            verbose,
+            progress,
+            progress_keep_open,
+            None,
+            move |_progress, out, err| {
+                core::repository::clean(
+                    repository(Mode::Lenient)?,
+                    out,
+                    err,
+                    pathspec,
+                    core::repository::clean::Options {
+                        debug,
+                        format,
+                        execute,
+                        ignored,
+                        precious,
+                        directories,
+                        skip_hidden_nonbare_repositories,
+                    },
+                )
+            },
+        ),
         Subcommands::Status(crate::plumbing::options::status::Platform {
             statistics,
             submodules,

src/plumbing/options/mod.rs

@@ -81,6 +81,8 @@ pub enum Subcommands {
     /// Subcommands for creating worktree archives
     #[cfg(feature = "gitoxide-core-tools-archive")]
     Archive(archive::Platform),
+    #[cfg(feature = "gitoxide-core-tools-clean")]
+    Clean(clean::Command),
     /// Subcommands for interacting with commit-graphs
     #[clap(subcommand)]
     CommitGraph(commitgraph::Subcommands),
@@ -478,6 +480,36 @@ pub mod mailmap {
     }
 }
 
+pub mod clean {
+    use gitoxide::shared::CheckPathSpec;
+    use gix::bstr::BString;
+
+    #[derive(Debug, clap::Parser)]
+    pub struct Command {
+        /// Print additional debug information to help understand decisions it made.
+        #[arg(long)]
+        pub debug: bool,
+        /// Actually perform the operation, which deletes files on disk without chance of recovery.
+        #[arg(long, short = 'e')]
+        pub execute: bool,
+        /// Remove ignored (and expendable) files.
+        #[arg(long, short = 'x')]
+        pub ignored: bool,
+        /// Remove precious files.
+        #[arg(long, short = 'p')]
+        pub precious: bool,
+        /// Remove whole directories.
+        #[arg(long, short = 'd')]
+        pub directories: bool,
+        /// Enter ignored directories to skip repositories contained within.
+        #[arg(long)]
+        pub skip_hidden_nonbare_repositories: bool,
+        /// The git path specifications to list attributes for, or unset to read from stdin one per line.
+        #[clap(value_parser = CheckPathSpec)]
+        pub pathspec: Vec<BString>,
+    }
+}
+
 pub mod odb {
     #[derive(Debug, clap::Subcommand)]
     pub enum Subcommands {