Add optional pre-commit hook for code formatting

[jamescrosswell]

Summary

Adds an optional pre-commit git hook that auto-fixes code formatting before allowing commits. This helps catch formatting issues early and reduces CI failures.

Implementation

New files:

• .githooks/pre-commit: Hook script that runs dotnet format against staged .cs files only

Updated files:

• dev.cs: Adds setup-hooks and remove-hooks commands to opt in/out

Behavior:

1. Developer runs ./dev.cs setup-hooks once to enable the hook
2. On each commit, the pre-commit hook runs
3. If unstaged changes are present → hook skips with a warning (dotnet format operates on the working tree, so partially staged files can't be handled safely)
4. Otherwise, dotnet format runs against staged .cs files only and auto-fixes any formatting issues
5. If fixes were applied → commit fails, developer stages the fixes (git add -u) and commits again
6. Can bypass with git commit --no-verify if needed
7. Run ./dev.cs remove-hooks to opt out

Design decisions:

• Auto-fix: Hook applies formatting fixes rather than just reporting them — developer only needs to git add -u and recommit rather than manually running dotnet format
• Staged files only: Uses --include scoped to staged .cs files so only what's being committed gets formatted
• Skip on unstaged changes: If the working tree isn't clean, the hook exits with a warning rather than risking modification of unstaged hunks in partially staged files
• Native git hooks: No external dependencies (Husky.NET not needed)
• Opt-in via dev.cs: Discoverable through the existing dev CLI rather than a separate shell script

Addresses

Fixes #4980

Next Steps

This PR makes the hook optional. After battle testing for a bit, we could:

• Document in CONTRIBUTING.md
• Add other pre-commit checks (analyzers, etc.)

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.21%. Comparing base (32a55e3) to head (d604b31).
⚠️ Report is 110 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5178      +/-   ##
==========================================
+ Coverage   74.06%   74.21%   +0.15%     
==========================================
  Files         501      509       +8     
  Lines       18113    18386     +273     
  Branches     3521     3600      +79     
==========================================
+ Hits        13415    13645     +230     
- Misses       3838     3868      +30     
- Partials      860      873      +13     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Flash0ver]

note: --diff-filter=ACM

I wasn't sure if filter --diff-filter=ACM also includes files that are renamed, but also contain changes. I gave it a quick test and it seems that they are. ✅

[Flash0ver]

praise: great optimization ... dotnet format on the "full" solution takes quite a while

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit b5e1c98. Configure here.}

[cursor]

Autofix enables skip bypass

High Severity

After dotnet format writes fixes, the working tree is dirty and the hook exits with failure. A follow-up git commit without staging those fixes hits the unstaged-changes guard, exits successfully, and lets the original unformatted staged content through. The formatting changes stay unstaged while the bad formatting is committed, so the hook fails open on the exact retry path it tells developers to use if they omit git add -u.

 

^{Reviewed by Cursor Bugbot for commit b5e1c98. Configure here.}

[jamescrosswell]

This is intentional rather than a defect. The unstaged-changes guard exists specifically so dotnet format never touches work-in-progress, and it prints a visible ⚠️ Skipping format check rather than failing silently. This is an opt-in convenience hook — CI remains the actual formatting gate — so on the (documented) retry path the worst case is a formatting-only CI failure, not committing broken code. Enforcing formatting on a dirty tree would require a stash-based partial-format dance that risks mangling WIP, which we deliberately avoid. Leaving as-is.

[cursor]

Setup skips executable bit

Medium Severity

setup-hooks only sets core.hooksPath and never ensures .githooks/pre-commit is executable. On macOS/Linux, Git silently ignores a non-executable hook, so after ./dev.cs setup-hooks commits proceed with no formatting check and only a brief ignored-hook hint. Contributors can believe the optional hook is enabled when it is not running at all.

Additional Locations (1)

• .githooks/pre-commit#L1-L2

 

^{Reviewed by Cursor Bugbot for commit b5e1c98. Configure here.}

[jamescrosswell]

Not applicable here — .githooks/pre-commit is committed with mode 100755 (executable), so git checks it out executable on clone/checkout. setup-hooks therefore doesn't need to chmod it, and on Windows git runs hooks via its bundled shell regardless of the exec bit. No change needed.