Getting Started¶

Stable v1 Contract¶

The stable v1 line defines Excise’s command-line tool, configuration, and versioned JSON report formats. Read the Permanent Deletion Contract before making a scan or deletion plan.

Requirements and Support¶

• Rust 1.98 or newer when building from source.
• A terminal with color and separate-screen support for the interactive interface.
• Linux, macOS, or Windows.

The repository pins Rust 1.98 in rust-toolchain.toml. Release binaries do not require a local Rust installation.

File-system limitations are documented in Support.

Install Excise¶

git clone https://github.com/findyourexit/excise.git
cd excise
cargo build --release --locked
./target/release/excise /path/to/inspect

cargo install --path . --locked

cargo install excise --version 1.3.0 --locked
excise --version

brew tap findyourexit/tap https://github.com/findyourexit/homebrew-tap.git
brew install findyourexit/tap/excise
brew fetch --force --retry findyourexit/tap/excise
brew test findyourexit/tap/excise
excise --version

nix build
./result/bin/excise /path/to/inspect

First Safe Session¶

Create a disposable fixture, then inspect it:

mkdir -p /tmp/excise-demo/subdirectory
printf 'sample\n' > /tmp/excise-demo/file.txt
printf 'nested\n' > /tmp/excise-demo/subdirectory/nested.txt
excise /tmp/excise-demo

Use a temporary directory appropriate to your platform on Windows.

• Confirm that the selected scan root is disposable.
• Keep deletion confirmation enabled.
• Open a stored folder page with Enter before attempting deletion.
• Review the escaped target name and identity before accepting a plan.
• Treat a partial result as a signal to rescan before acting again.

When a real file or directory appears in the map, select it and press Backspace to begin a permanent deletion plan. During the first scan, Enter opens a directory that already has a partial stored page and prioritizes its existing scan work. Once a complete result publishes, opening a directory reads a fixed page of direct contents immediately.

The scan root, a filesystem or drive root, and the virtual Shared allocation summary cannot be deletion targets. An incomplete map or approximate space estimate neither weakens nor blocks the planner’s separate live identity checks.

Files and directories with safe printable names accept Enter or Y. Planning runs in the background with a fixed limit while confirmation stays in front of the map until you accept or cancel it. After acceptance, the map remains available while one worker rechecks and deletes each reviewed entry. Hostile or untypeable names require a generated challenge. --disable-delete-confirmation enables a visible, session-only reduced confirmation mode that accepts Enter or Y for all entries except hostile names.

The default view uses allocated space. Pass --apparent-size when logical file length is the intended comparison.

Interactive Terminal¶

The interactive interface requires standard input and output connected to a terminal, terminal color and control support, a separate screen, and a window at least 32 x 8. Smaller windows show a resize message. If a terminal cannot provide those capabilities, use table or JSON mode instead. --ascii changes symbols and borders but does not remove the terminal requirement.

Noninteractive Use¶

excise --format table /path/to/inspect

excise --format json --output scan.json /path/to/inspect

Table and JSON modes run without a terminal, raw mode, or separate screen. Use them for redirected output, shell pipelines, continuous integration, or terminals without interactive support. --output FILE writes the report instead of standard output and works only with table or JSON mode. A nonzero exit can still produce a useful bounded report. See Reports & JSON Formats for outcome classes and document state.

Scope: Boundaries and Exclusions¶

Excise stays on the starting file system by default. A directory on another file system is shown as a boundary and is not traversed. Use --cross-filesystems only when traversal across mounts is intended; it broadens the scan scope.

excise --exclude .git/ --exclude target/ /path/to/inspect

Exclusions use ordered gitignore-style patterns rooted at the scan path. An excluded entry is shown as a zero-byte scoped record with its reason, and its descendants are not traversed. Link targets are never traversed. On Windows this also applies to junction and reparse targets. Check these scope rules before treating a missing path as a read failure.

Native Paths and Display¶

Excise uses a reversible escaped display form for interactive and text output. Newlines, tabs, terminal controls, bidirectional controls, backslashes, invalid UTF-8 on Unix, and ill-formed UTF-16 on Windows are escaped so a name cannot inject terminal control. display_path is for people, not a byte-exact shell argument.

JSON keeps path lossless in a platform-specific encoding while display_path remains escaped:

See Reports & JSON Formats and the native path format when consuming reports.

Windows Notes¶

# Windows path syntax
target\release\excise.exe C:\path\to\inspect

Windows does not provide allocated-space snapshots, so allocated and reclaimable upper bounds can be unknown. Pass --apparent-size when logical file lengths are the intended comparison. Deletion uses verified handles, but access rules and another process’s sharing mode can still make an entry fail. Close applications, sync clients, indexers, or antivirus software before a fresh scan and retry. Junction and reparse targets are not followed.

Next Steps¶

• Configure persistent defaults.
• Read the Permanent Deletion Contract before destructive use.
• Open ? in the interactive interface for context-sensitive controls.
• See Support for safe troubleshooting and bug reports. Never publish an unintended-deletion path in a public issue.