Git Diff --no-index: Compare Files Outside a Repository

Two configuration files or extracted source archives need comparison, but neither belongs to a repository. There is no need to initialize Git and commit each version. Git diff --no-index compares paths directly, making it useful before file replacement or delivery.

1. Define both inputs

Place the baseline on the left and the candidate on the right. These example JSON files contain no secrets:

git --no-pager diff --no-index --no-ext-diff --no-textconv -- before.json after.json

The git diff manual documents no-index comparisons outside repositories. These options disable external diff helpers and text conversion; -- separates options from paths. Quote paths containing spaces.

The comparison does not replace either file. Nevertheless, use stable copies: concurrent application writes can prevent the result from representing a consistent moment.

2. Read changes in the correct direction

For {"timeout":10} before and {"timeout":30} after, the changed content appears as:

-{"timeout":10}
+{"timeout":30}

Minus lines belong to the left input; plus lines belong to the right. Reversing inputs reverses the presentation. Record the baseline explicitly rather than sharing an unexplained screenshot.

This is a text comparison, not JSON semantic analysis. Reordering keys or formatting can produce substantial differences without equivalent behavioral changes. If normalization is necessary, compare separate derived copies and preserve originals as evidence.

3. Differences are not execution failures

For a successful comparison, no-index returns 0 for no differences and 1 for differences. Some input failures can also return 1. This PowerShell example checks file existence first, but Git diagnostics still require inspection:

if (!(Test-Path -LiteralPath before.json -PathType Leaf) -or
    !(Test-Path -LiteralPath after.json -PathType Leaf)) {
    throw "Both input files must exist"
}
git --no-pager diff --no-index --no-ext-diff --no-textconv -- before.json after.json
$comparisonExit = $LASTEXITCODE
if ($comparisonExit -eq 0) {
    Write-Output "No differences reported"
} elseif ($comparisonExit -eq 1) {
    Write-Output "Exit 1: inspect diff and stderr before classifying"
} else {
    throw "Comparison failed: exit $comparisonExit"
}

Do not discard stderr or assume every exit 1 represents a valid diff. Existence checks do not guarantee readability or prevent later file changes. Pipelines should retain diagnostics and stop for review when classification is uncertain. Nor should a difference authorize overwriting a live file; reviewers must decide which changes are appropriate.

4. Review directories in two passes

git --no-pager diff --no-index --no-ext-diff --no-textconv --stat -- before/ after/
git --no-pager diff --no-index --no-ext-diff --no-textconv -- before/config.json after/config.json

First inspect scope, then review selected files. Prepare directories containing only authorized material rather than pointing at an entire disk, personal directory, or production data tree. Do not treat .gitignore as a secret-protection boundary for this path comparison.

For large deliveries, exclude dependencies and caches from review copies under a documented policy. Do not delete them from the original merely to shorten the report.

5. Preserve meaningful differences

Avoid ignoring whitespace from the outset: it may be significant in source or configuration. When reducing noise, document the chosen options and retain an unfiltered comparison.

Different binary files may yield only a difference notice rather than useful line changes. A diff does not replace application tests or a complete inventory of permissions, ACLs, and operating-system metadata. Add tools appropriate to the handover requirements.

6. Before sharing the report

• Record input provenance and ordering.
• Use stable snapshots rather than changing data.
• Distinguish equality, differences, and execution failures.
• Inspect removed, added, and context lines for secrets.
• Keep sensitive reports out of public CI logs and tickets.
• Test approved changes before replacing real files.

Git diff --no-index offers a compact review step outside Git history. Its value depends on appropriate inputs and careful interpretation, not on producing the largest possible diff.