Fix parallel install mutex bug and support incremental build

[MattKotsenas]

Description

Fixes #155

This PR fixes two issues that occur when the target is present in more than one project (common in monorepo scenarios).

1. Fix concurrent git config lock contention

When multiple MSBuild nodes run dotnet husky install in parallel, concurrent git rev-parse calls would intermittently fail with:

warning: unable to access '.git/config': Permission denied
fatal: unknown error occurred while reading the configuration files

The existing mutex serialized CreateResources (which writes .git/config via git config core.hooksPath), but the validation calls (git rev-parse, IsSubmodule, GetGitDirectory) ran outside the mutex. When one process held .git/config locked for writing, concurrent processes trying to read it got Permission denied.

The fix is to move all git operations inside the mutex by extracting a DoInstallAsync method that contains both validation and resource creation. The mutex now wraps the entire install as a single critical section.

Reproduced at ~10% failure rate with a 100-project monorepo test harness.

2. Make the Husky MSBuild target incremental

The Husky target ran dotnet tool restore + dotnet husky install on every build, even when nothing changed. This added seconds to every restore/build cycle, particularly painful when the target is in Directory.Build.targets (runs once per project in the solution).

The fix is to add MSBuild Inputs/Outputs to the target. .config/dotnet-tools.json is an input so that the target re-runs when tool version changes. .husky/_/install.stamp is a sentinel file created after successful install. Touch task creates the stamp; FileWrites ensures dotnet clean removes it.

Both the dotnet husky attach command and the embedded target in Husky.csproj now generate the incremental pattern. Documentation updated with the new snippet and a note about using $(MSBuildThisFileDirectory) in Directory.Build.targets.

3. Tradeoff: self-healing vs. performance

Previously, husky re-installed on every build, which meant a corrupted or manually altered install (e.g., someone running git config --unset core.hooksPath) would silently self-heal on the next build. With the stamp file, this self-healing is lost as the stamp says "done" and husky won't re-run until the inputs change or the stamp is removed.

I believe this is the right tradeoff:

• The per-build cost was the original problem reported in Guide for automating installation causes unnecessary work to be done when applied to multiple projects #155 and affected every developer on every build
• Corrupted installs are rare (requires local git config or file write failure, or manual config editing)
• The fix for a corrupted install is dotnet clean && dotnet restore, which is a well-understood MSBuild pattern

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• I have performed a self-review of my code
• I have added tests that prove my fix is effective or that my feature works
• I have made corresponding changes to the documentation
• I have commented my code, particularly in hard-to-understand areas
• New and existing unit tests pass locally with my changes
• I did test corresponding changes on Windows
• I did test corresponding changes on Linux
• I did test corresponding changes on Mac

[what-the-diff]

PR Summary

• Husky Target Definition Enhanced
  Updates were made to the Husky target in a few documents to better support the incremental build process through including additional attributes.

• Refactored Installation Process
  The process of installation in the InstallCommand.cs file has been simplified. A new method was created for this purpose, and redundant checks have been removed, resulting in better clarity and structure.

• Improved Parallelism Management
  A new lock mechanism has been introduced to manage multiple installations at once. This ensure commands do not overlap when multiple installations are done simultaneously.

• Testing Process Upgraded
  The tests have been updated in order to confirm the functioning of the new attributes in the Husky target and check the parallel executions. Also, they assure that the Git commands are executed rightly without interference.

• Documentation Upgrades
  The documentation has been refined to explain better the usage of new attributes and file handling for Husky configurations. Additional tips are also provided for managing multi-project solutions.

[Copilot]

Pull request overview

This PR addresses monorepo/multi-project build issues by (1) preventing parallel Husky installs from interleaving git operations and (2) making the Husky MSBuild integration incremental via an input/output stamp file.

Changes:

• Wrap git validation + install work under the install mutex to avoid .git/config lock contention in parallel builds.
• Add MSBuild Inputs/Outputs with a sentinel .husky/_/install.stamp to avoid running Husky install on every build.
• Update attach generation, tests, and docs to reflect the incremental target pattern.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/Husky/Cli/InstallCommand.cs	Refactors install flow so git operations are performed under the mutex when parallelism is enabled.
src/Husky/Husky.csproj	Makes the embedded Husky target incremental using Inputs/Outputs + a stamp file.
src/Husky/Cli/AttachCommand.cs	Updates generated MSBuild target to include Inputs/Outputs, Touch, and FileWrites for the stamp.
docs/guide/automate.md	Updates the manual snippet and guidance to the new incremental build pattern.
tests/HuskyTest/Cli/InstallCommandTests.cs	Adds a concurrency regression test for git call interleaving.
tests/HuskyTest/Cli/AttachCommandTests.cs	Extends assertions to validate incremental target attributes/elements.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[alirezanet]

Hi @MattKotsenas, thanks for the PR
I haven't reviewed this PR myself yet, but could you please check the Copilot suggestions first? That way, I'll know your take on each potential issue during my review.

[MattKotsenas]

Hi @alirezanet! Thanks for the quick response!

In this particular case, Copilot is incorrect. It's assuming that FileWrites is a normal item group that's evaluated as part of clean. However, the way it actually works then the target runs during build, FileWrites items get written to the file obj/**/{project}.FileListAbsolute.txt on disk. When dotnet clean runs later, it reads that persisted list and deletes everything in it. It does not re-evaluate the target. So, it doesn't matter that the target doesn't execute during clean, the stamp file path was already recorded during the build that created it.

Here's a blog post to read more if you're interested: https://learn.microsoft.com/en-us/archive/msdn-magazine/2009/february/msbuild-best-practices-for-creating-reliable-builds-part-1

Let me know if you have any questions. Thanks!

[alirezanet]

LGTM 🎉

[MattKotsenas]

Thanks @alirezanet, I apologize because I know it can be annoying, but do you know when the next release would be with this fix? Depending on the timing I'll either wait for this release to fix our build, or try to find a short term workaround. Any guidance is greatly appreciated. Thanks!

[alirezanet]

Thanks @alirezanet, I apologize because I know it can be annoying, but do you know when the next release would be with this fix? Depending on the timing I'll either wait for this release to fix our build, or try to find a short term workaround. Any guidance is greatly appreciated. Thanks!

I'm working on a couple of other small issues, if I manage to fix them, I'll release the next version in 1-2 days max, maybe even tonight! 🤞

honestly releasing this library is a bit risky because it might block a lot of people if I miss any small potential issues. if you could help me later to test it properly I would do it faster 😊. (I mean after release)

[MattKotsenas]

Sounds good! Feel free to ping me when you have a release or a pre-release and I'm happy to test it

[alirezanet]

Sounds good! Feel free to ping me when you have a release or a pre-release and I'm happy to test it

Just release the v0.9.0
https://github.com/alirezanet/Husky.Net/releases/tag/v0.9.0