Skip to content

Git tags, hooks and commit conventions

Releasing software from Git depends on two habits. The first is marking exactly which commit became a release, which is what tags are for. The second is keeping commits consistent enough that tools can read them: a commit message format that changelog and version tools understand, and checks that run before a bad commit is created. Git hooks are the mechanism for those checks on your machine; platforms add server-side equivalents that nobody can skip.

This page covers both halves in the order you meet them: commit message conventions, client-side hooks and how to share them, then tags, versions and releases. Examples use an invented OrdersPortal repository; every block with output was run with Git 2.43 (and Node.js 22 for the npm tools) in a throwaway repository.

Topic Use it when
Commit message conventions You want history that tools and people can scan.
Client-side hooks You want checks to run automatically on commit or push.
Sharing hooks with the team Hooks must be versioned with the repository.
Husky lint-staged and commitlint Your project already uses npm.
Annotated and lightweight tags You mark a release or milestone.
Pushing and deleting tags You publish or correct tags on the remote.
Versions and releases You derive version numbers and publish release notes.

A commit message has a subject line (keep it under about 72 characters, imperative mood: “Add refund endpoint”, not “Added”), a blank line, and an optional body explaining why. On top of that, many teams adopt Conventional Commits, a small specification that gives the subject a machine-readable prefix:

<type>(<optional scope>): <description>
[optional body]
[optional footer(s)]

Common types are feat (a new feature, maps to a minor version), fix (a bug fix, maps to a patch version), plus docs, refactor, perf, test, build, ci and chore. A ! after the type or a BREAKING CHANGE: footer marks a breaking change, which maps to a major version. Release tools read these prefixes to generate changelogs and decide the next version number. Issue keys usually go in the footer (Refs: ORD-123) or the scope.

feat(refunds): add partial refund endpoint
Customers can now refund individual order lines instead of the whole order.
Refs: ORD-123

Pitfalls:

  • Merge commits need a rule too. Platform-generated merge commits (“Merge branch ‘x’ into ‘main’”) do not follow the format. Either allow them in your checks or use squash merges with a conforming title.
  • Format is not quality. fix: stuff passes every regex. Reviews still need to ask what changed and why.

Hooks are executable files that Git runs at fixed points. If a “pre” hook exits with a non-zero status, Git aborts the operation. The most useful client-side hooks are:

Hook Runs Typical use
pre-commit Before the commit message is requested Lint or format staged files, block secrets and debug statements
prepare-commit-msg Before the editor opens Prefill the message, for example with an issue key from the branch name
commit-msg After the message is written; receives the message file path as $1 Validate the message format
post-commit After the commit is created Notifications; cannot block
pre-push Before objects are sent; receives the remote name and URL Run fast tests, block pushes to main
pre-rebase Before a rebase starts Refuse to rebase published branches

By default hooks live in .git/hooks/, which is not versioned. A new clone contains only .sample files. Any hook can be skipped with --no-verify (git commit --no-verify, git push --no-verify), which is exactly why rules that must hold are also enforced on the server: see GitLab push rules and server hooks and GitHub repository governance.

This commit-msg hook enforces the Conventional Commits subject line with plain POSIX shell, so it works without Node.js:

#!/bin/sh
# .githooks/commit-msg: enforce Conventional Commits on the subject line
subject=$(head -n 1 "$1")
pattern='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9-]+\))?!?: .{1,72}$'
if ! printf '%s\n' "$subject" | grep -Eq "$pattern"; then
echo "commit-msg: subject must look like 'feat(orders): add refund endpoint'" >&2
echo "commit-msg: got '$subject'" >&2
exit 1
fi

Pitfalls:

  • Hooks must be executable. Run chmod +x on Unix-like systems; a non-executable hook is silently ignored.
  • Keep pre-commit fast. Developers bypass slow hooks with --no-verify. Check only staged files, and leave the full test suite to pre-push or CI.

Since Git 2.9, the core.hooksPath setting points Git at a different hooks directory. Commit the hooks to a folder such as .githooks/, and have each developer (or a setup script) run git config core.hooksPath .githooks once per clone.

Terminal window
mkdir .githooks
cp commit-msg .githooks/ && chmod +x .githooks/commit-msg
git config core.hooksPath .githooks
git commit -m "added refunds"
git commit -m "feat(refunds): add refund endpoint"
git log --oneline

Output:

commit-msg: subject must look like 'feat(orders): add refund endpoint'
commit-msg: got 'added refunds'
941d714 feat(refunds): add refund endpoint

Pitfalls:

  • Git does not install hooks for you. Cloning never runs code from the repository, by design. The core.hooksPath step has to happen once per clone, which is why npm projects automate it with a prepare script.
  • Windows needs a shell. Git for Windows runs sh hooks through its bundled shell; keep scripts POSIX and avoid tools that are not in Git Bash.

In npm projects, Husky automates the setup: npx husky init adds a "prepare": "husky" script (run by npm install), creates .husky/pre-commit, and sets core.hooksPath to .husky/_. With Husky 9, hook files are plain shell commands without a shebang. lint-staged runs tools only on staged files, and commitlint validates messages against the Conventional Commits rules. Versions checked with npm view in November 2026: husky 9.1.7, lint-staged 17.6.1, @commitlint/cli 21.2.4.

Terminal window
npm install --save-dev husky lint-staged @commitlint/cli @commitlint/config-conventional
npx husky init
echo "npx lint-staged" > .husky/pre-commit
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg
echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.mjs

In package.json, map file patterns to commands (a real project would run ESLint and Prettier here):

{
"lint-staged": {
"*.{js,ts}": ["eslint --fix", "prettier --write"],
"*.{css,md}": "prettier --write"
}
}

A non-conforming message is rejected (output trimmed):

⧗ input: added pricing
✖ subject may not be empty [subject-empty]
✖ type may not be empty [type-empty]
✖ found 2 problems, 0 warnings
husky - commit-msg script failed (code 1)

Pitfalls:

  • CI should run the same checks. Hooks protect developers from themselves; a CI job running commitlint --from origin/main and the linters protects the branch.
  • prepare does not run everywhere. npm ci --ignore-scripts and some Docker builds skip it; that is fine, hooks are only for developer machines.

A tag is a name for a commit that, unlike a branch, does not move. A lightweight tag is just a ref pointing at a commit. An annotated tag (-a) is a full Git object with the tagger, date and message, and it can be signed (-s). Use annotated tags for releases: git describe uses only annotated tags by default, --follow-tags pushes only annotated tags, and the message documents the release. Lightweight tags suit private or temporary markers.

Terminal window
git tag -a v1.4.0 -m "OrdersPortal 1.4.0" # annotated
git tag build-2026-11-02 # lightweight
git cat-file -t v1.4.0
git cat-file -t build-2026-11-02
git tag -n1 -l 'v1.*'

Output:

tag
commit
v1.4.0 OrdersPortal 1.4.0

git tag -a v1.3.1 <commit> -m "..." tags an older commit. Checking out a tag (git switch --detach v1.4.0) leaves you in detached HEAD; to fix something in that release, create a branch from it with git switch -c hotfix/1.4.1 v1.4.0.

Pitfalls:

  • Tags are not updated by a normal fetch if they changed. Moving a published tag (git tag -f) confuses everyone who already fetched the old one. Never reuse a release tag; publish a new version instead.
  • Branch and tag names can collide. A branch and a tag both called release make git switch release ambiguous; use a v prefix for tags.

git push does not send tags unless asked. git push origin v1.4.0 pushes one tag, git push origin --tags pushes every local tag (including stray lightweight ones), and git push --follow-tags pushes the branch plus any annotated tags that point at commits being pushed, which is the safest default (git config push.followTags true makes it automatic). Delete a remote tag with git push origin --delete <tag> and the local one with git tag -d <tag>.

Terminal window
git push origin main --follow-tags
git ls-remote --tags origin

Output (the ^{} line is the commit the annotated tag points to; the lightweight tag was not pushed):

c5ee2e7c9f2e3856555201730bbc4c5e3a3eb237 refs/tags/v1.4.0
2bb7b0180a55f78c2557e29f0d1283da37d810e5 refs/tags/v1.4.0^{}

Pitfalls:

  • --tags publishes everything. Experimental or personal tags end up on the server; prefer --follow-tags or explicit names.
  • Protect release tags. GitHub rulesets can target tags, and GitLab has protected tags, so only release managers can create or delete v* tags.

Semantic Versioning uses MAJOR.MINOR.PATCH: increment MAJOR for incompatible changes, MINOR for backward-compatible features, PATCH for backward-compatible fixes. Pre-releases append a hyphen (1.5.0-rc.1) and build metadata a plus sign (1.5.0+build.42). With Conventional Commits the mapping is mechanical: any ! or BREAKING CHANGE means a major bump, else any feat a minor bump, else a patch.

git describe turns the nearest annotated tag into a version string for builds between releases: tag, number of commits since the tag, and g plus the abbreviated commit hash.

Terminal window
git describe

Output:

v1.4.0-2-gd6ff91e

On GitHub, a release is created from a tag with notes and attached build artifacts, through the web UI or the GitHub CLI (fragment, not run here):

Terminal window
git push origin v1.5.0
gh release create v1.5.0 --verify-tag --generate-notes ./dist/orders-portal-1.5.0.zip

Pipelines usually build releases from tag pushes. In GitHub Actions the trigger is on: push: tags: ['v*']; in GitLab CI, a rules: - if: $CI_COMMIT_TAG condition.

Pitfalls:

  • Shallow clones break git describe. CI checkouts often fetch one commit and no tags. Fetch tags and enough history (fetch-depth: 0 with actions/checkout, GIT_DEPTH: 0 in GitLab CI) before computing a version.
  • One source of truth for the version. If the version lives in both package.json and the tag, automate one from the other; mismatches are a common release bug.
Need Tool
Mark a release permanently Annotated tag, pushed with --follow-tags
Mark a commit for yourself Lightweight tag, not pushed
Version string for a build between releases git describe
Catch problems before they are committed pre-commit and commit-msg hooks
Rules nobody may bypass Server-side checks: rulesets, push rules, CI

What is the difference between a lightweight and an annotated tag? A lightweight tag is only a ref to a commit. An annotated tag is a Git object with tagger, date, message and an optional signature. Release tooling, git describe and --follow-tags work with annotated tags by default.

Why are tags not pushed with git push? Git pushes only the refs you name or that your push configuration selects. Use git push origin <tag>, --follow-tags for annotated tags reachable from what you push, or --tags for all.

Can client-side hooks enforce policy? No. They live on each developer’s machine, are not installed by cloning, and are skipped with --no-verify. They give fast feedback; enforcement belongs to server-side rules and CI.

How does Conventional Commits relate to Semantic Versioning? The commit type determines the bump: fix is a patch, feat a minor, and a ! or BREAKING CHANGE footer a major. Tools read the commits since the last tag to produce the version and changelog.

Senior scenario: CI publishes builds whose version reads 0.0.0-unknown and release notes are empty. What is wrong? Most likely the pipeline uses a shallow clone without tags, so git describe has nothing to describe and the notes generator sees no history. Fetch full history and tags in the release job, make sure releases use annotated tags pushed to the remote, and add a guard that fails the release job if no tag is found instead of publishing a meaningless version.