# Git Workflow And Versioning

> Branching strategy, commit discipline, PR hygiene, and semantic versioning

- Skill: `vignesh2027/git-workflow-and-versioning` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vignesh2027/git-workflow-and-versioning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vignesh2027/git-workflow-and-versioning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: vignesh2027 (https://skillmd.com/u/vignesh2027)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vignesh2027/git-workflow-and-versioning

---


## Overview

Git history is documentation. A clear commit history enables fast debugging, safe reverts, and meaningful changelogs. This skill enforces the habits that make git useful as a tool rather than just a backup system.

## When to Use

- Before starting any branch
- Before committing changes
- Before creating a PR
- When tagging a release

## Process

### Step 1: Branch naming
Use: `<type>/<description>` — e.g., `feat/user-search`, `fix/login-redirect`, `chore/update-deps`
Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `perf`, `test`

### Step 2: Commit messages
Follow Conventional Commits:
```
<type>(<scope>): <description>

[optional body]
[optional footer]
```
Examples:
- `feat(auth): add OAuth2 login with Google`
- `fix(api): handle null user_id in /profile endpoint`
- `perf(db): add index on users.email column`

Rules:
- Description is imperative mood ("add" not "added")
- Under 72 characters
- One logical change per commit
- Reference ticket: `Closes #123`

### Step 3: Keep PRs small
A PR should be reviewable in under 30 minutes. If it takes longer, it's too big. Split it.
- One logical change per PR
- No PRs with 500+ line diffs (with rare exceptions)
- No WIP code in a PR

### Step 4: PR description
Every PR must have:
- What changed (not a list of files, but a description of the change)
- Why it changed
- How to test it
- Screenshots for UI changes
- Link to the ticket

### Step 5: Semantic versioning
`MAJOR.MINOR.PATCH`
- MAJOR: breaking change (removing an API, changing a contract)
- MINOR: backward-compatible new feature
- PATCH: backward-compatible bug fix

Tag releases: `git tag v1.2.3 -m "Release 1.2.3"`

### Step 6: Git hygiene
- Never force push to main/master
- Never commit secrets (use pre-commit hooks: `gitleaks`, `detect-secrets`)
- Rebase feature branches on main before merging (or squash)
- Delete branches after merge

## Verification Requirements

- [ ] Branch follows naming convention
- [ ] Commits follow Conventional Commits format
- [ ] PR has description with: what, why, how to test
- [ ] PR is reviewable in under 30 minutes
- [ ] No secrets committed (pre-commit hook confirms)
- [ ] Release tagged with semantic version