Git Basics: Preview Untracked Cleanup with git clean

Build leftovers and local notes can both be untracked. Before removing anything, inspect exactly which paths Git would select. Every git clean invocation here is a dry run; assertions confirm the fixture files still exist.

Prepare a scratch directory

Tested on Linux with Git 2.52.0 and GNU Bash 5.2.37. You need the named runtime, Bash, a text editor, and the standard mktemp, rm, and rmdir utilities. The script creates a second temporary fixture directory and removes only that directory through its exit trap. Run it in a normal Bash terminal, outside any Git hook or Git wrapper. No global Git configuration is changed.

Keep using the same terminal. Stop if setup fails, before saving the source:

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save this as demonstrate-clean-preview.sh:

#!/usr/bin/env bash
set -euo pipefail
export LC_ALL=C
fixture_dir="$(mktemp -d)"
trap 'rm -rf -- "$fixture_dir"' EXIT
export GIT_CONFIG_NOSYSTEM=1
export GIT_CONFIG_GLOBAL=/dev/null
unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE
git init -q -b main "$fixture_dir/repo"
cd -- "$fixture_dir/repo"
git config user.name 'Practice Author'
git config user.email 'practice@example.invalid'
printf 'build/\n' > .gitignore
printf 'tracked\n' > source.txt
git add .
git commit -qm 'Ignore build output'
mkdir build
printf 'generated\n' > build/output.txt
printf 'notes\n' > notes.txt
printf 'Ordinary untracked paths:\n'
git clean -nd
printf 'Ignored paths only:\n'
git clean -ndX
printf 'All untracked paths:\n'
git clean -ndx
printf 'One explicit path:\n'
git clean -n -- notes.txt
test -f notes.txt
test -f build/output.txt
test -f source.txt
printf 'All fixture files remain\n'

Run it:

bash demonstrate-clean-preview.sh

Observed output:

Ordinary untracked paths:
Would remove notes.txt
Ignored paths only:
Would remove build/
All untracked paths:
Would remove build/
Would remove notes.txt
One explicit path:
Would remove notes.txt
All fixture files remain

Read the result

-n previews without deleting. -d includes untracked directories. Uppercase -X selects ignored paths only, while lowercase -x includes ignored paths along with other untracked paths. The final invocation restricts the preview to an explicit path. These differences matter when ignored output and personal files share a checkout.

Apply it carefully

A dry run is a report at that moment, not a transaction or a recovery mechanism. Files can change before a later cleanup. Git generally cannot restore deleted untracked content, so save anything valuable elsewhere first. This tutorial deliberately provides no force-delete command. Nested repositories have extra protection and are outside this small fixture. The script’s exit trap removes only its own temporary practice directory.

The official reference describes the API and its options. The checks above cover the specific fixture, not every possible input or environment.

Clean up

Remove the source and then the empty practice directory:

rm -- demonstrate-clean-preview.sh
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

If the directory is not empty, inspect the remaining files rather than deleting unknown contents.

Acknowledgements

This post was created with assistance from AI.