Git Basics: Compare Arbitrary Files with diff --no-index
Git can compare two filesystem paths even when their contents are not tracked. git diff --no-index is useful for reviewing generated files or exports. Its exit status distinguishes equal content from differences, so a difference should not be treated as a crashed command.
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 1Run the example
Save this as demonstrate-diff-no-index.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 'mode=preview\ncount=2\n' > before.txt
printf 'mode=ready\ncount=2\n' > after.txt
if git diff --no-index --no-color --no-prefix -- before.txt after.txt > change.patch; then
exit 1
else
status=$?
test "$status" -eq 1
fi
printf 'Difference status: %s\n' "$status"
cat change.patch
cp before.txt identical.txt
git diff --no-index --quiet -- before.txt identical.txt
printf 'Identical content status: %s\n' "$?"
test "$(cat before.txt)" = "$(cat identical.txt)"Run it:
bash demonstrate-diff-no-index.shObserved output:
Difference status: 1
diff --git before.txt after.txt
index 866b7b7..3cdd24e 100644
--- before.txt
+++ after.txt
@@ -1,2 +1,2 @@
-mode=preview
+mode=ready
count=2
Identical content status: 0Read the result
--no-index selects a path-to-path comparison and implies exit-code behavior: zero for equality and one for differences. The script captures the differing patch, checks status one explicitly, and then compares an identical copy. --no-color keeps terminal escape sequences out of the saved patch; --no-prefix simplifies the displayed path names.
Apply it carefully
A status greater than one indicates a problem rather than an ordinary difference. Preserve that distinction in CI instead of using a blanket || true. This example compares text files, but binary files and directories have different output shapes. The index header identifies content, and its abbreviations are not a replacement for storing the full inputs. Review a generated patch before applying it elsewhere; this tutorial only compares and never applies changes.
The official reference describes the API and its options.
Clean up
Remove the source and then the empty practice directory:
rm -- demonstrate-diff-no-index.sh
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dirIf the directory is not empty, inspect the remaining files rather than deleting unknown contents.
Acknowledgements
This post was created with assistance from AI.