git-conventions 1.0.0

Conte.GitConventions

Conte.GitConventions is a small .NET 8 CLI that installs and maintains native Git enforcement for branch names and Conventional Commits.

It uses only Git's built-in capabilities:

• core.hooksPath
• commit.template
• native hooks such as commit-msg and pre-push

There is no Node.js, Husky, commitlint, Python package, or third-party hook framework involved.

Why Native Git Only

This project enforces conventions at the Git layer, which means the behavior is shared by:

• Visual Studio
• VS Code
• command-line Git
• any Git-aware editor or workflow that respects Git configuration

Because enforcement lives in Git itself, teams do not need editor-specific extensions or per-repo JavaScript tooling just to keep branch names and commit messages consistent.

Managed Behavior

The tool manages a dedicated folder under the current user's home directory:

• Windows example: %USERPROFILE%\.conte-git-conventions
• Linux/macOS design target: ~/.conte-git-conventions

Inside that folder it manages:

• hooks/commit-msg
• hooks/pre-push
• scripts/commit-msg.ps1
• scripts/pre-push.ps1
• templates/commit-template.txt

Every managed file contains an internal marker with a version number. That marker is used to:

• detect whether a file belongs to this tool
• report drift during status
• safely repair only tool-managed files
• avoid deleting unrelated user files during uninstall

Commands

Build and run locally:

dotnet build Conte.GitConventions.sln
dotnet run --project .\src\Conte.GitConventions.Tool -- install
dotnet run --project .\src\Conte.GitConventions.Tool -- status
dotnet run --project .\src\Conte.GitConventions.Tool -- repair
dotnet run --project .\src\Conte.GitConventions.Tool -- uninstall

CLI contract:

git-conventions install
git-conventions status
git-conventions repair
git-conventions uninstall

What install Does

install will:

1. Verify Git is installed.
2. Create the managed folder structure if it does not exist.
3. Write the managed hook wrappers and PowerShell scripts.
4. Write the default commit message template.
5. Configure:
   • git config --global core.hooksPath <managed-hooks-path>
   • git config --global commit.template <managed-template-path>
6. Leave unrelated files untouched.
7. Behave idempotently when run multiple times.

What status Checks

status reports:

• Git installed: yes/no
• core.hooksPath configured: yes/no
• commit.template configured: yes/no
• managed files present: yes/no
• hook content valid: yes/no
• overall health: healthy/warning/error

It also explains what is missing, outdated, or conflicting.

What repair Does

repair restores the expected managed state:

• re-creates missing managed files
• overwrites invalid or outdated tool-managed files
• restores Git global configuration if it drifted away from the expected managed paths

It still refuses to overwrite unmanaged files.

What uninstall Does

uninstall removes only what this tool owns:

• deletes managed files that still contain the tool marker
• removes empty managed directories
• unsets core.hooksPath only if it still points to the tool-managed hooks path
• unsets commit.template only if it still points to the tool-managed template path

It will not delete unrelated custom hooks or unrelated Git configuration.

Conventions Enforced

Branch Names

Accepted examples:

• feat/exchange-rate-sync
• fix/login-timeout
• docs/readme-update
• refactor/task-config
• test/scheduler-rules
• chore/repo-cleanup
• hotfix/sql-timeout

Regex:

^(feat|fix|docs|refactor|test|chore|hotfix)\/[a-z0-9._-]+$

Conventional Commits

Accepted examples:

• feat(api): add exchange rate sync
• fix(auth): handle expired cookie
• refactor(scheduler): simplify next-run calculation
• chore(repo): update git hooks

Regex:

^(feat|fix|docs|style|refactor|test|chore|build|ci|perf)(\([a-z0-9._-]+\))?!?: .+$

How the Hooks Work

The hooks folder contains the files Git expects:

• commit-msg
• pre-push

On Windows-first installations, those hooks are small shell wrappers that invoke tool-managed PowerShell scripts:

• scripts/commit-msg.ps1
• scripts/pre-push.ps1

commit-msg.ps1 validates the first real commit-message line against the Conventional Commits regex.

pre-push.ps1 validates the current branch name against the branch regex before the push proceeds.

This approach keeps enforcement native to Git while letting the project author the logic entirely with .NET-generated content.

Why Visual Studio and VS Code Benefit

Because the rules are enforced by Git itself:

• Visual Studio commits are checked by commit-msg
• VS Code source control commits are checked by commit-msg
• pushes from terminals, IDEs, and GUI Git clients are checked by pre-push

That keeps behavior consistent across tools without requiring editor-specific extensions.

Safety Notes

• The tool writes only to its own managed folder.
• It uses an internal marker to distinguish managed files from user files.
• It does not automatically overwrite unrelated existing files.
• It does not unset unrelated Git configuration values.
• It is safe to run install multiple times.

Limitations

• Windows is the primary target in this version.
• The generated hook wrappers call PowerShell scripts, so non-Windows environments are designed for future support rather than fully optimized today.
• The pre-push hook validates the current local branch name. Detached HEAD workflows are intentionally rejected.

Future Improvements

• add first-class Linux and macOS script generation
• package as a global .NET tool
• support team-specific convention profiles
• add a minimal test project around orchestration behavior if the codebase grows