AI code review: flag binary files and submodule changes
TL;DR: A text diff can show every line change and still leave binary content and submodule internals unreviewed. Inventory the staged paths before sending a patch to an AI reviewer. Flag these boundaries explicitly, review them with suitable tools, and avoid paying for repeated prompts that lack the underlying evidence.
What you’ll be able to do:
- Detect staged binary changes and Git submodule pointers without exporting file contents.
- Preserve unusual filenames with Git’s NUL-delimited output.
- Separate a text review’s coverage from the work that still needs another reviewer or tool.
Honest take: Send a scoped text patch with an explicit exception list; an AI verdict cannot fill in content the review packet never contained.
Why can a complete text patch still be an incomplete review?
A Git text patch can represent a changed binary file with a notice and represent a submodule change with commit identifiers. Neither representation gives a text-only reviewer the contents needed to judge the whole change. This is a review-input problem before it is a model-quality problem.
The official git-diff documentation, checked November 11, 2026, distinguishes patch output, numeric statistics, raw output, and binary patch output. Those are different views of the same comparison. Choosing the view is part of defining the review, not a cosmetic formatting choice.
An image replacement may change a screenshot used in onboarding. A submodule update may bring a new implementation into a build. A prose reviewer given only “binary files differ” or “subproject commit” cannot inspect the visual result or evaluate the implementation. Asking it to try harder supplies no missing pixels or code.
That matters for both local and paid coding assistants. The local workflow spends context and compute; a metered workflow may also spend money. This tutorial measures neither model quality nor financial savings. Its narrower aim is to identify where a text-review packet lacks evidence before you invest in another review round.
Which Git comparison does this tutorial inspect?
The script below inspects HEAD versus the index, meaning staged changes. It does not combine staged files with later working-tree edits. Run it after intentionally staging the paths you plan to review and before changing that selection again.
Use the staged-diff and untracked-file guide if the index boundary is unfamiliar. For a branch-to-branch review, first choose the correct base with the merge-base review guide. Do not silently replace the script’s comparison with whichever diff happens to look shortest.
| Git view | Useful evidence | Boundary the reviewer must retain |
|---|---|---|
| Ordinary patch | Text hunks and change headers | Binary contents may be absent |
--numstat | Added/deleted line counts, binary markers | Line counts do not measure semantic risk |
--raw | Modes, object IDs, and path status | A changed object ID is not its implementation |
| Submodule log/diff | A view into the recorded child-repository change | Child objects and a deliberate review range are needed |
| Working-tree status | Later edits and untracked paths | Those files may be outside the staged packet |
Git documents binary numstat entries with - in the line-count columns. Raw entries expose file modes; a gitlink uses mode 160000, identifying a recorded submodule commit. The submodule documentation explains the separate child-repository relationship. These markers are practical reasons to route part of the review elsewhere.
How do you produce an inventory without dumping binaries?
Save this script as review_inventory.py outside the repository being reviewed and run it from that repository’s root. It uses Python’s standard library and a locally installed Git. No GPU, model download, API key, or paid service is required for the inventory.
The script intentionally disables external diff commands and text conversion for its diff invocations. The attributes manual explains how diff drivers and text conversion can affect a diff’s representation. Disabling them here makes the inventory about Git’s selected raw and numeric views; it does not certify the repository as safe to execute.
Rename detection is disabled to keep each output record a single path. A rename can therefore appear as a deletion plus an addition. That is an explicit representation tradeoff, not evidence that the developer deleted and independently recreated the file.
import json
import os
import subprocess
import sys
def git(*args):
return subprocess.check_output(["git", "--no-pager", *args])
def inspect():
options = ["--cached", "--no-ext-diff", "--no-textconv",
"--no-renames", "--ignore-submodules=none", "-z"]
binary = set()
for record in git("diff", *options, "--numstat").split(b"\0"):
if record:
added, removed, path = record.split(b"\t", 2)
if added == b"-" or removed == b"-":
binary.add(path)
records = git("diff", *options, "--raw", "--no-abbrev").split(b"\0")
rows = []
for index in range(0, len(records) - 1, 2):
metadata, path = records[index:index + 2]
old_mode, new_mode, old_oid, new_oid, status = metadata.split()
old_mode = old_mode.lstrip(b":")
rows.append({
"path": os.fsdecode(path),
"status": status.decode("ascii"),
"binary": path in binary,
"gitlink": b"160000" in (old_mode, new_mode),
"old_mode": old_mode.decode("ascii"),
"new_mode": new_mode.decode("ascii"),
"old_oid": old_oid.decode("ascii"),
"new_oid": new_oid.decode("ascii"),
})
untracked = [p for p in git("ls-files", "--others", "--exclude-standard", "-z").split(b"\0") if p]
manual = any(r["binary"] or r["gitlink"] for r in rows) or bool(untracked)
return {"scope": "HEAD_to_index", "changed_paths": len(rows),
"untracked_count": len(untracked), "manual_review_required": manual,
"paths": rows}
if __name__ == "__main__":
try:
result = inspect()
print(json.dumps(result, indent=2))
sys.exit(2 if result["manual_review_required"] else 0)
except (ValueError, OSError, subprocess.CalledProcessError) as error:
print("INVENTORY_FAILED: " + str(error), file=sys.stderr)
sys.exit(1)
Run the script before exporting your staged patch:
python3 /path/outside/repo/review_inventory.py
Exit 0 means the script found no binary/gitlink exceptions or untracked paths in its chosen checks. Exit 2 means manual attention is required. Exit 1 means the inventory failed. None of these statuses means the source code is correct, the tests passed, or a particular AI product reviewed everything.
The distinction between “manual attention” and “tool failure” is deliberate. A binary asset is a valid repository object, not a corrupted patch. A failed Git invocation, by contrast, means you do not yet have a reliable inventory. Keep the error and fix the comparison before exporting a packet.
What did the local Git experiment show?
On November 11, 2026, the script was exercised in a temporary repository with Git 2.47.3 and Python 3.13.5. No AI model or paid review service was invoked. The fixture used a text file, binary files containing a NUL byte, and a synthetic gitlink entry pointing to a commit already present in the fixture repository.
The gitlink was created with Git’s documented update-index cacheinfo interface. It tested the parent’s index representation; it was not a claim that a real dependency had been fetched, built, or reviewed.
| Fixture state | Changed staged paths | Binary flags | Gitlink flags | Result |
|---|---|---|---|---|
| Clean repository | 0 | 0 | 0 | Exit 0 |
| Text modification only | 1 | 0 | 0 | Exit 0 |
| Text, two binary files, synthetic gitlink | 4 | 2 | 1 | Exit 2 |
| Same staged selection, one extra untracked file | 4 | 2 | 1 | Exit 2; untracked count 1 |
One binary filename contained both a tab and a newline. The script preserved it as one path, and JSON escaped the control characters in the output. Splitting ordinary diff output into lines would have made that representation ambiguous. Git’s -z output and the script’s limited split on the first two numstat tabs avoided that mistake.
The ordinary staged patch included Binary files and Subproject commit notices. Those strings were actual fixture output. They are evidence of the patch representation, not evidence about the quality of an image or the behavior of a child repository.
How should you handle a flagged binary file?
Choose a review method that understands the asset and record its result alongside the text review. For an image, inspect the before-and-after render at the size where users see it. For an archive or generated artifact, identify its source and build process rather than treating a filename as proof of its contents.
Do not force every binary through --text merely to make an AI packet longer. Git’s binary classification and a useful human-readable representation are separate questions. A custom text conversion can help for a known file format, but it introduces a transformation whose coverage must be understood.
Likewise, --binary can create an applicable binary patch, as documented by Git. Applicability is not visual or semantic review. A textual model reading an encoded patch has not thereby inspected the image in the UI or validated an executable’s behavior. Record the relevant test or specialist inspection separately.
If the binary is incidental to a small code change, a good packet says exactly that: the source hunks were reviewed, the named asset was routed to a visual check, and that check is either complete or pending. The exception is part of the result, not an embarrassing detail to hide from the final summary.
What does a gitlink flag require from the reviewer?
A gitlink flag requires checking the child repository and the intended old-to-new commit range. The parent stores the referenced commit; it does not inline all child code into an ordinary parent patch.
Start by inspecting the parent comparison explicitly:
git --no-pager diff --cached --submodule=log
git --no-pager diff --cached --submodule=diff
Git documents these submodule display modes. Their usefulness depends on having the relevant child objects and understanding the comparison. If the child repository is unavailable, record that as missing evidence. Do not turn a successful parent diff into a claim that the dependency internals were reviewed.
A dirty child working tree adds another boundary: local child changes can differ from the commit recorded in the parent index. Inspect the child status before deciding what will actually be committed or deployed. Avoid automatically updating every submodule just to make the warning disappear; an update changes the checkout and may fetch or select content beyond the intended review.
The right response to an unexpected dependency bump is to ask why that specific bump is in scope, then review its range. It is not to approve the parent because the changed lines happen to fit in a small prompt.
Honest take: what should go into the AI review packet?
Include the exact comparison, a text patch, the path inventory, and a plain statement of pending exceptions. Keep the inventory report with the patch rather than relying on the model to infer that missing contents exist.
For example, a review request can state: “Review the staged source hunks. Two binary assets require separate visual inspection; the gitlink change requires a child-commit review. Do not mark those items complete from the parent patch.” That is a scope instruction, not a promise that every assistant will obey it. The human acceptance step still needs to verify the resulting claims.
After changing the index, regenerate both the inventory and the patch. After changing the working tree, ensure tests target the same content you intend to accept. A clean exception list cannot compensate for reviewing one version and shipping another.
Use this inventory to prevent incomplete review claims and unnecessary repeated prompts. Skip it when you already have a review system that reliably inventories these object types and tracks the corresponding checks. Adding another script has value only if it makes a real review boundary visible.
Sources
- Patch, numstat, raw output, NUL paths, and submodule modes — Git diff manual
- Binary classification and text conversion — Git attributes manual
- Child repositories and recorded commits — Git submodule manual
- Untracked-file inventory — Git ls-files manual
- Index entries and cacheinfo — Git update-index manual
Last updated November 11, 2026. Results are local Git fixtures, not AI model evaluations or measured subscription savings. Verify the staged comparison again before accepting a review.
Was this article helpful?
Thanks for the feedback — it helps improve future articles.
Need hands-on help?
I offer 1-on-1 technical consulting for local AI setup, GPU selection, and AI coding tool configuration — same topics covered on this site.
Book a session — $49 / hour →Know which coding tool is worth paying for
Hands-on comparisons of AI coding assistants and what each one costs to run — including the local-model path. Sent only when something changes. Unsubscribe anytime.