dotnet-gitmoji: Gitmoji Commits for .NET Teams

Why it exists #

When a team is moving fast, commit titles tend to drift toward something like this:

9e79328 fix for real this time
3fba982 final fix
b9d9153 wip 2
d2c6acd Update appsettings.json
f6c8590 fix build
7afe3cf changes
3d45706 asdf
ee9a912 fix
0bcc0d1 wip
66ae352 Update Program.cs

Each of those made sense to whoever wrote it, but read later as a list, it’s hard to tell what changed, which commit fixed a bug, or which one broke the build. gitmoji ➡️ is a small convention that helps with this: every commit title starts with one emoji that says what kind of change it is.

• 🐛 fixes a bug
• ✨ adds a feature
• ♻️ refactors code
• 📝 updates docs

The history becomes something you can scan, and because many gitmojis also carry a semver hint (✨ is a minor, 🐛 a patch, 💥 a major), the log tells you what the next release contains.

A convention only works if people follow it, and nobody follows one from memory for long.

So it needs a commit hook that asks for the emoji at the moment you commit. That hook also has to live in the repo, otherwise it only exists on the machine of whoever installed it. The existing gitmoji tooling solves this for JavaScript projects, but it assumes Node.js, and a .NET team shouldn’t have to provision Node on every machine just to share a commit hook.

See it in action #

The two-minute walkthrough below follows the setup straight from the README, then shows a teammate joining the repo.

Try it in five steps #

Run these once in your repo. After you commit the result, every teammate gets the hook without doing anything. You need the .NET 10 SDK, plus Git for Windows on Windows, since the hook runs under Git Bash.

1. Add both tools to the local tool manifest.

dotnet new tool-manifest   # skip if the repo already has a dotnet-tools.json
dotnet tool install Husky
dotnet tool install dotnet-gitmoji

The manifest pins both tool versions for the whole team.

2. Initialize Husky.Net.

dotnet tool run husky install

This points Git’s core.hooksPath at the .husky/ folder.

3. Install the gitmoji hook.

dotnet tool run dotnet-gitmoji init --mode shell

It adds a prepare-commit-msg hook to .husky/, a plain text file that is safe to commit.

4. Add the MSBuild target. Create a file named Directory.Build.targets at the root of the repository, next to .husky/ and dotnet-tools.json, even if your solution lives in a subfolder. If the repo already has one, add the PropertyGroup and Target below inside its existing <Project>.

<Project>
  <PropertyGroup>
    <HuskyRoot Condition="'$(HuskyRoot)' == ''">$(MSBuildThisFileDirectory)</HuskyRoot>
    <HuskyToolManifest Condition="'$(HuskyToolManifest)' == '' and Exists('$(HuskyRoot)dotnet-tools.json')">$(HuskyRoot)dotnet-tools.json</HuskyToolManifest>
    <HuskyToolManifest Condition="'$(HuskyToolManifest)' == ''">$(HuskyRoot).config/dotnet-tools.json</HuskyToolManifest>
  </PropertyGroup>
  <Target Name="Husky" BeforeTargets="Restore;CollectPackageReferences" Condition="'$(HUSKY)' != 0"
          Inputs="$(HuskyToolManifest)"
          Outputs="$(HuskyRoot).husky/_/install.stamp">
    <Exec Command="dotnet tool restore"
          StandardOutputImportance="Low" StandardErrorImportance="High" />
    <Exec Command="dotnet husky install"
          StandardOutputImportance="Low" StandardErrorImportance="High"
          WorkingDirectory="$(HuskyRoot)" />
    <Touch Files="$(HuskyRoot).husky/_/install.stamp" AlwaysCreate="true"
           Condition="Exists('$(HuskyRoot).husky/_')" />
    <ItemGroup>
      <FileWrites Include="$(HuskyRoot).husky/_/install.stamp" />
    </ItemGroup>
  </Target>
</Project>

MSBuild finds Directory.Build.targets by walking up from each project’s folder, so one file at the root covers every project in the repo (unless a subfolder has its own, which then has to import the root one). The target also uses its own folder, $(MSBuildThisFileDirectory), to locate .husky/ and the tool manifest, which is why it has to sit next to them.

It runs dotnet tool restore and dotnet husky install whenever someone restores, builds, or opens the project, which is what installs the hook for every teammate. Why it hooks BeforeTargets instead of the more obvious AfterTargets="Restore" is one of the stories below.

5. Commit everything.

git add dotnet-tools.json .husky/ Directory.Build.targets
git commit -m "chore: add dotnet-gitmoji hook"

The hook is already active, so this very commit goes through the picker.

From here on, every git commit opens a fuzzy picker. Type bug and the list narrows to 🐛, with a panel below explaining what it means and its semver impact: “Fix a bug.”, a patch. Press Enter, confirm the title, and the commit lands as 🐛 Fix login redirect. Your old history stays the way it was, and every commit from the setup onward follows the convention.

What I learned building it #

The picker is the part people see, but most of the work in a tool this small is the plumbing between Git, the terminal, and MSBuild. These four problems taught me the most.

The hook that lost its terminal #

The tool manifest is the team’s contract #

// GitService.cs
private async Task<string> BuildShellHookCommandAsync()
{
    bool isLocal = await IsLocalToolManifestAsync();
    string invocation = isLocal ? DotnetGitmojiLocalInvocation : DotnetGitmojiTaskName;
    return $"{invocation} \"$1\" \"$2\"";
}

The restore target that never fired #

Config split by who owns it #

Where to go next #

This page covers why the tool exists and the shortest path to a first commit. dotnet-gitmoji.com ➡️ is the tool’s home, with the setup, joining a repo that already uses it, daily use, and the config wizard with its main options. For every .gitmojirc.json key, the color themes, client mode for personal workflows, the task-runner mode, and the full command list, go to the README ➡️.

Links #

1. Website: dotnet-gitmoji.com ➡️
2. Full reference: dotnet-gitmoji README ➡️
3. Repository: dotnet-gitmoji ➡️
4. NuGet package: dotnet-gitmoji ➡️
5. gitmoji convention: gitmoji.dev ➡️
6. Husky.Net: Husky.Net ➡️

Photo by Tim Witzdam ➡️ on Unsplash ➡️