This diagram shows main staying deployable while short-lived feature branches leave it and merge back within 1-3 days.
main ──●──●──●──●──●──●──●──●──●──
╲ ╱ ╲ ╱
●──●─╱ ●──╱
Teams that use gitflow or long-lived branches can adapt these principles to their branching model. The commit discipline (atomic commits, small changes, descriptive messages) matters more than the branching strategy.
- Dev branches are costs. Every day a branch lives, it accumulates merge risk.
- Release branches are acceptable when you need to stabilize a release while
mainmoves forward. - Small slices beat long branches. The coding instructions (
code_rules) rule out feature flags, so keep branches short by merging small finished slices.
Work in a loop. Implement a slice, test it, verify it, commit it, and move to the next slice. Never implement everything at once, hope it works, and make one giant commit. Commits are save points. If the next change breaks something, you can revert to the last known-good state at once.
git log --oneline
a1b2c3d Add task creation endpoint with validation
d4e5f6g Add task creation form component
h7i8j9k Connect form to API and add loading state
m1n2o3p Add task creation tests (unit + integration)
This bad history mixes everything into one commit.
git log --oneline
x1y2z3a Add task feature, fix sidebar, update deps, refactor utils
feat: add email validation to registration endpoint
Prevents invalid email formats from reaching the database.
Uses Zod schema validation at the route handler level,
consistent with existing validation patterns in auth.ts.
This bad message describes what is obvious from the diff.
update auth.ts
Follow the convention the project's git log already shows. Without one, use Conventional Commits 1.0.0. A message there has a type, an optional scope, a description, an optional body, and optional footers.
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
The type sets the SemVer bump. A fix is a patch, and a feat is a minor. A ! before the colon, as in feat(api)!: drop v1 routes, or a BREAKING CHANGE: footer makes a major. The spec itself defines only feat and fix. Six common types from the Angular convention cover most commits.
featfor a new featurefixfor a bug fixrefactorfor a code change that neither fixes a bug nor adds a featuretestfor adding or updating testsdocsfor documentation onlychorefor tooling, dependencies, and config
git commit -m "refactor: extract validation logic to shared utility"
git commit -m "feat: add phone number validation to registration"
This bad commit mixes them.
git commit -m "refactor validation and add phone number field"
Separate refactoring from feature work. A refactoring change and a feature change are two different changes, so submit them separately. Each change is then easier to review, revert, and understand in history. A small cleanup, such as renaming a variable, can join a feature commit at the reviewer's discretion.
| Size | Effect |
|---|---|
| About 100 lines | Easy to review and easy to revert |
| About 300 lines | Acceptable for a single logical change |
| About 1000 lines | Split into smaller changes |
main
│
├── feature/task-creation
├── feature/user-settings
└── fix/duplicate-tasks
- Branch from
mainor from the team's default branch. - Keep branches short-lived and merge within 1-3 days, because long-lived branches are hidden costs.
- Delete branches after merge.
A branch name is its type prefix and a short description, such as feature/<short-description>. The four prefixes are feature/, fix/, chore/, and refactor/, as these names show.
feature/task-creation
fix/duplicate-tasks
chore/update-deps
refactor/auth-module
git worktree add -b feature/task-creation ../project-feature-a main
git worktree add -b feature/user-settings ../project-feature-b main
The parent directory then holds project/ on the main branch and one directory per feature branch. When the work is done, merge it and remove the worktree.
git worktree remove ../project-feature-a
Worktrees bring four benefits.
- Several agents can work on different features at the same time.
- No branch switching is needed, because each directory has its own branch.
- If an experiment fails, you delete its worktree and lose nothing.
- Changes stay isolated until someone merges them explicitly.
Agent starts work
│
├── Makes a change
│ ├── Test passes? → Commit → Continue
│ └── Test fails? → Investigate → Fix, or restore the last commit
│
├── Makes another change
│ ├── Test passes? → Commit → Continue
│ └── Test fails? → Investigate → Fix, or restore the last commit
│
└── Feature complete → All commits form a clean history
Before restoring a path, inspect both staged and unstaged changes. Restore it only when all changes belong to this task and the user authorized discarding them. Preserve user edits and other tasks' changes. This command discards both staged and unstaged changes in the named path.
git restore --source=HEAD --staged --worktree <path>
A command that discards other work, such as git reset --hard, needs the user's confirmation first.
Before every commit, review what you are about to commit.
git diff --staged
Then make sure the diff has no secrets. This command lists only the names of matching files, and any output means you review them.
git diff --staged -i -G'password|secret|api_key|token' --name-only
Then run the project's checks as the verification block of the coding instructions requires.
- Commit generated files only if the project expects them, such as
package-lock.jsonor Prisma migrations. - Do not commit build output (
dist/,.next/), environment files (.env), or IDE config. Shared IDE config such as.vscode/settings.jsonis the exception. - Keep a
.gitignorethat coversnode_modules/,dist/,.env,.env.local, and*.pem.
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
git bisect run npm test
git bisect reset
These commands show what changed recently.
git log --oneline -20
git diff HEAD~5..HEAD -- src/
git blame shows who last changed each line of a file.
git blame src/services/task.ts
git log --grep searches commit messages for a keyword.
git log --grep="validation" --oneline
| Part | Change | Upgrade |
|---|---|---|
| MAJOR | Breaking change | Consumers must change their code to upgrade |
| MINOR | New functionality, backward-compatible | Safe to upgrade |
| PATCH | Bug fix, backward-compatible | Safe to upgrade |
The number is a promise, so make the code match it. A patch that changes behavior consumers relied on is a disguised major change (Hyrum's Law). When you are unsure whether a change is breaking, assume it is. A surprise major is far cheaper than a broken consumer.
git tag -a v1.4.0 -m "Release 1.4.0"
git push origin v1.4.0
Derive the version from the tag instead of hand-editing it in scattered files. Then the artifact, the tag, and the changelog can never disagree.
## [Unreleased]
### Changed
- Task list loads 50 items per page instead of 20
## [1.4.0] - 2025-06-12
### Added
- Bulk task import via CSV
### Fixed
- Timezone drift in recurring task due dates
### Deprecated
- `GET /v1/tasks/all`, replaced by the paginated `GET /v1/tasks` (removal in 2.0)
Write the entry under Unreleased in the same change that makes the change, while the impact is fresh. At release time, those entries move into the new version section. Breaking changes get a migration note and a deprecation window.
- Large uncommitted changes accumulate after the user asked for commits.
- Commit messages say "fix", "update", or "misc".
- Formatting changes are mixed with behavior changes.
- The project has no
.gitignore. - Someone commits
node_modules/,.env, or build artifacts. - Long-lived branches diverge significantly from
main. - Someone force-pushes to shared branches.
- A breaking change ships under a minor or patch version bump.
- A release has no tag, or its version number is hand-edited out of sync with the tag.
- A user-facing release has no changelog entry, or the changelog is just dumped commit messages.
- The commit does one logical thing.
- The message explains why and follows the project's commit convention.
- Tests pass before the commit.
- The diff has no secrets.
- Formatting-only changes are not mixed with behavior changes.
- No build output, dependency folder, or
.envfile is staged.
Every release of anything with consumers passes three checks.
- The version bump matches the change. Breaking means major, additive means minor, and a fix means patch.
- The release is tagged, and the version comes from the tag instead of a hand edit.
- The changelog has a curated, human-readable entry for this version, grouped by impact.