Unity Git Guard

Git Pre-Commit Hook for Unity Conflict Markers

A pre-commit hook can stop unresolved merge markers before they enter history. Scan the staged diff or staged asset content, not only the working tree, and keep the same check in CI because local hooks are optional and can be bypassed.

Minimal pre-commit hook

Create .git/hooks/pre-commit and make it executable:

#!/usr/bin/env bash
set -euo pipefail

# Git also reports newly introduced conflict markers and whitespace errors.
git diff --cached --check

if git diff --cached -U0 -- \
  'Assets/*.unity' 'Assets/*.prefab' \
  'Assets/*.asset' 'Assets/*.mat' |
  grep -E '^\+(<<<<<<< |=======|>>>>>>> )'; then
  echo "Commit blocked: unresolved Unity conflict markers are staged." >&2
  exit 1
fi

chmod +x .git/hooks/pre-commit

The explicit pattern limits the scan to primary text-serialized Unity assets. Add other validated text formats used by the project.

Why the hook must inspect staged content

A commit records the index, not the complete working tree. A developer can fix a marker locally but leave an older staged copy, or stage only part of a file. git diff --cached checks the content that will actually be committed.

Do not use only a broad grep -R Assets. It can flag ignored caches, generated files, or unstaged edits while missing the exact index state.

Test the hook

1. Create a disposable branch.
2. Add a marker block to a test .prefab or fixture.
3. Stage the file and verify that the commit is blocked.
4. Resolve the block, stage the corrected file, and verify that the commit proceeds.
5. Test partial staging so the index and working tree intentionally differ.
6. Remove the test change before merging the hook rollout.

Share hooks without assuming Git copies them

The default .git/hooks directory is not tracked. Teams commonly store hooks in a repository folder and configure:

git config core.hooksPath .githooks

Document the bootstrap step or run it from an explicit setup command. Treat the hook as developer feedback, not the only security or quality gate.

Repeat the guard in CI

Local hooks can be skipped with --no-verify, missing on a new clone, or misconfigured. Add the same marker search to protected-branch CI. The hook improves feedback speed; CI provides enforcement.

If markers are found, keep the conflict state and inspect it with a Unity-aware workflow. MergeSight staged Unity conflict review can expose Base / Ours / Theirs decisions, hierarchy, references, and preview instead of encouraging a developer to remove marker lines blindly.

What this hook does not validate

• Valid Unity YAML syntax beyond marker detection.
• Missing scripts, dangling references, hierarchy, or component ownership.
• Whether the correct branch content was selected.
• Whether the scene or prefab opens in Unity.
• Whether an automatic merge preserves design intent.

Add semantic and Unity-hosted validation for those questions.

FAQ

Can a Git pre-commit hook prevent Unity merge markers?

It can block commits whose staged Unity text assets introduce unresolved marker lines. CI should repeat the same check because local hooks can be missing or bypassed.

Should the hook scan the working tree or staged files?

Scan the staged diff or index because that is what Git commits. Working-tree-only scans can report irrelevant edits or miss an older staged version.

Are Git hooks committed to the repository?

Files in .git/hooks are not tracked. Store shared hooks in a tracked folder and configure core.hooksPath, or install them through a documented bootstrap step.

Does git diff --cached --check find conflict markers?

Git uses --check to warn about newly introduced conflict markers and whitespace errors. An explicit Unity-asset marker pattern makes the intended guard visible and scoped.

Summary

Inspect the index

Check staged content because the commit may differ from the working tree.

Fail with a direct message

Name the affected Unity file and explain that the conflict must be resolved.

Repeat in CI

Hooks improve feedback but protected branches need server-side enforcement.

A marker hook is a small, reliable guard against one destructive failure class, not a replacement for semantic or Unity validation.

Next step

Use the recovery procedure in the Unity conflict-marker fix guide when the hook blocks a real merge.