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.
Topics on this page
Section titled “Topics on this page”| 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. |
Commit message conventions
Section titled “Commit message conventions”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-123Pitfalls:
- 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: stuffpasses every regex. Reviews still need to ask what changed and why.
Client-side hooks
Section titled “Client-side hooks”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 linesubject=$(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 1fiPitfalls:
- Hooks must be executable. Run
chmod +xon Unix-like systems; a non-executable hook is silently ignored. - Keep
pre-commitfast. Developers bypass slow hooks with--no-verify. Check only staged files, and leave the full test suite topre-pushor CI.
Sharing hooks with the team
Section titled “Sharing hooks with the team”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.
mkdir .githookscp commit-msg .githooks/ && chmod +x .githooks/commit-msggit config core.hooksPath .githooks
git commit -m "added refunds"git commit -m "feat(refunds): add refund endpoint"git log --onelineOutput:
commit-msg: subject must look like 'feat(orders): add refund endpoint'commit-msg: got 'added refunds'941d714 feat(refunds): add refund endpointPitfalls:
- Git does not install hooks for you. Cloning never runs code from the repository, by design. The
core.hooksPathstep has to happen once per clone, which is why npm projects automate it with apreparescript. - Windows needs a shell. Git for Windows runs
shhooks through its bundled shell; keep scripts POSIX and avoid tools that are not in Git Bash.
Husky lint-staged and commitlint
Section titled “Husky lint-staged and commitlint”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.
npm install --save-dev husky lint-staged @commitlint/cli @commitlint/config-conventionalnpx husky initecho "npx lint-staged" > .husky/pre-commitecho 'npx --no -- commitlint --edit "$1"' > .husky/commit-msgecho "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.mjsIn 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 warningshusky - 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/mainand the linters protects the branch. preparedoes not run everywhere.npm ci --ignore-scriptsand some Docker builds skip it; that is fine, hooks are only for developer machines.
Annotated and lightweight tags
Section titled “Annotated and lightweight tags”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.
git tag -a v1.4.0 -m "OrdersPortal 1.4.0" # annotatedgit tag build-2026-11-02 # lightweightgit cat-file -t v1.4.0git cat-file -t build-2026-11-02git tag -n1 -l 'v1.*'Output:
tagcommitv1.4.0 OrdersPortal 1.4.0git 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
releasemakegit switch releaseambiguous; use avprefix for tags.
Pushing and deleting tags
Section titled “Pushing and deleting 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>.
git push origin main --follow-tagsgit ls-remote --tags originOutput (the ^{} line is the commit the annotated tag points to; the lightweight tag was not pushed):
c5ee2e7c9f2e3856555201730bbc4c5e3a3eb237 refs/tags/v1.4.02bb7b0180a55f78c2557e29f0d1283da37d810e5 refs/tags/v1.4.0^{}Pitfalls:
--tagspublishes everything. Experimental or personal tags end up on the server; prefer--follow-tagsor 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.
Versions and releases
Section titled “Versions and releases”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.
git describeOutput:
v1.4.0-2-gd6ff91eOn 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):
git push origin v1.5.0gh release create v1.5.0 --verify-tag --generate-notes ./dist/orders-portal-1.5.0.zipPipelines 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: 0withactions/checkout,GIT_DEPTH: 0in GitLab CI) before computing a version. - One source of truth for the version. If the version lives in both
package.jsonand the tag, automate one from the other; mismatches are a common release bug.
Choosing between them
Section titled “Choosing between them”| 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 |
Interview questions
Section titled “Interview questions”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.
Related pages
Section titled “Related pages”- Git fundamentals
- Branching strategies: where release branches and hotfixes fit.
- Merge, rebase and cherry-pick: backport fixes before tagging a patch release.
- GitLab push rules and server hooks: the server-side counterpart to these hooks.
- GitHub Actions and automation: building and publishing from tag pushes.