Choosing a branching model: release cadence first, team size second
gitflow expresses code maturity through five branch types: main for stable releases, develop for integration, and feature, release, and hotfix branches on top. Its value is that there is zero ambiguity about which branch may reach production, which suits software that genuinely maintains multiple long-lived versions — supporting both 2.0 and 3.0, shipping separate patch releases, and operating under strict release windows and quality gates.
The cost is branch lifetime. A feature branch that lives two weeks from creation to merge accumulates divergence from main, and the area of potential conflict grows with it; the merge then requires manual verification to be confident the work still behaves correctly on the trunk. For a product shipping many times a day, that coordination cost often exceeds the discipline gitflow buys.
Trunk-based development rests on short-lived branches plus frequent integration: a developer branch typically lives one or two days, unfinished features stay invisible behind feature flags, and the gate for merging to trunk is passing automated tests plus code review. The payoff is a tiny conflict surface and problems surfacing early. The cost is that trunk may hold incomplete-but-hidden code, which demands feature flags and real test coverage.
The pragmatic middle ground is GitHub Flow: a single trunk, short-lived feature branches, and preview environments instead of release branches. For the majority of web projects it is the best default. Three questions actually drive the choice: whether you must maintain several shipped versions simultaneously, whether the team has automated tests and feature flags to make trunk-based safe, and how heavy the approval process for production is.
# Typical gitflow branches
main # Accepts only hotfix and release merges, points only at released versions
develop # Integration branch, the everyday merge target
feature/xxx # Feature branch, cut from develop and merged back to develop
release/1.4 # Accepts only bugfixes, cut from develop and merged back to develop and main
hotfix/1.3.2 # Cut from main and merged back to both main and develop
# Typical GitHub Flow branches (recommended by default)
main # Always releasable
feature/checkout-retry # Lives 1-2 days, merged back to main via PR
# trunk-based: trunk + feature flags
main
feature/new-search # Short-lived branch, code is merged but a flag controls feature visibility
# Inspect the branch topology locally
# git log --graph --oneline --all --decorate -30Why conflicts actually happen: mostly not concurrent edits
The first cause is genuine parallel development: two people changing the same region of the same files. The fix is not a better tool but better module boundaries — if two people keep colliding in one file, that file probably owns too many responsibilities or sits in the wrong place.
The second cause is formatters. Two people with different Prettier configurations or formatter versions touching the same files produce large volumes of purely cosmetic conflict. This class must be handled with .gitattributes: mark machine-generated files such as lockfiles and snapshots with merge attributes such as linguist-generated or -diff, so Git uses a merge driver instead of a text three-way merge.
The third cause is renaming, especially changes in letter case. macOS and Windows filesystems are case-insensitive by default, so renaming UserService.ts to userservice.ts shows up as a delete plus an add, and Git readily interprets that as "someone deleted the file". Rename with git mv as its own commit first, then make content changes in a later commit. A single naming convention across the team, such as kebab-case, eliminates this whole category.
The fourth cause is misuse of .gitignore: adding a rule after the file is already tracked means later edits still show up as conflicts. For already-tracked files use git update-index --skip-worktree, or remove them from the index with git rm --cached and then ignore them. Line-ending differences between Windows CRLF and Unix LF also produce whole-file conflicts, handled by core.autocrlf plus text=auto eol=lf in .gitattributes.
# .gitattributes: hand generated files to a merge driver instead of a textual three-way merge
# package-lock.json linguist-generated=true -diff
# *.snap linguist-generated=true -diff
# *.min.js linguist-generated=true -diff
# Normalize line endings for text files
* text=auto eol=lf
*.bat text eol=crlf
*.ps1 text eol=crlf
# Rename in two steps: git mv and commit first, then change the content
# git mv src/user/UserService.ts src/user/user-service.ts
# git commit -m "refactor(user): rename UserService to kebab-case"
# When a tracked file really needs to stop being tracked
# git update-index --skip-worktree .env.local
# git rm --cached -r logs/ && echo "logs/" >> .gitignore
# Detect case sensitivity differences (when debugging renames on a case-insensitive file system)
# git ls-files | grep -i "userservice"Commit messages and a readable history
The only consumers of a commit message are you and your colleagues six months from now. An effective message has three parts: what was done, as an imperative verb opening such as fix, add, or refactor; why, which is often more important than what, especially for changes that look superfluous but are genuinely required; and references, such as a ticket or PR link. Messages like "fix bug", "update", or "asdf" carry no information, turn git log into noise, and make git bisect impossible.
The widely used convention is Conventional Commits: a type from a small fixed set, an optional scope, and a short imperative subject with no trailing period. It pays off twice: git log supports --grep filtering by type, and release changelogs can be generated mechanically.
The test for commit granularity is whether the commit can be reverted independently without breaking the system. A commit that mixes a refactor with a feature change denies reviewers the ability to approve half of it and prevents reverting the feature while keeping the refactor. Splitting with git rebase -i is the standard remedy. Before committing, glance at git diff --stat: if a single commit touches forty or fifty files, it probably should be split.
The other lever for readable history is keeping noise out of it. Feature flag toggles, temporary debug prints, and unrelated formatter churn belong in their own commits, ideally ones that can be reverted later. Generated lockfiles and machine output should stay out of diff review via .gitattributes, and local tooling artifacts should remain in the working tree rather than being committed. The health check is simple: if you cannot read git log --oneline -20 and say what those twenty commits did, the history needs work.
# Pre-commit self-check: review the change scope and potential whitespace/conflict issues
# git diff --stat
# git diff --check
# Split commits: divide the current changes into staged and unstaged groups and commit each
# git add -p src/parser.ts
# git commit -m "fix(parser): correct out-of-bounds read on empty input"
# git commit -m "test(parser): add regression case for empty input"
# History search
# git log --oneline --grep="fix(parser)" --since="2 weeks ago"
# git log --oneline --no-merges -20 Skip merge commits to see real changes
# git log --stat -1 See which files a single commit touched
# Locate the problem commit
# git bisect start
# git bisect bad
# git bisect good <known good commit>
# git bisect resetTurning conventions into enforced process
Any convention written in a wiki but not enforced by tooling will be bypassed under delivery pressure. What actually works is pushing those rules down into hooks and server configuration: pre-commit formatting, branch name validation, commit message format checks, and protected branches that reject force pushes. None of this needs extra tooling — plain Git hooks are sufficient.
A practical step is to require fast-forward merges. Setting git config --add merge.ff only makes git pull fast-forward only, so a branch that needs a merge surfaces immediately instead of quietly producing a string of useless merge commits in your local history. Combined with an explicit --no-rebase or rebase pull policy, everyone keeps a tidy local graph.
Large files deserve their own governance. Handle binaries through .gitattributes or git lfs. If a large file was already committed, rewriting history with git filter-repo is the only remedy — and that must be a coordinated team operation with everyone re-cloning or resetting, never something one person does silently on their own machine.
Finally, bring large-repository maintenance into the conventions. Beyond periodic git gc, the important thing is to keep build output, dependency directories, and caches out of the repository: they bloat history and are a standing source of conflict. A check for common artifacts in the pre-commit hook is far more reliable than hoping a reviewer notices them in a diff.
# .git/hooks/pre-commit (example: block artifacts + validate the commit message)
# #!/bin/sh
# staged=$(git diff --cached --name-only)
# if echo "$staged" | grep -Eq "(^|/)(node_modules|dist|\.next|\.nuxt|coverage)/|\.log$"; then
# echo "Refusing to commit build artifacts or dependency directories"
# exit 1
# fi
# msg=$(git log -1 --pretty=%s)
# case "$msg" in
# feat\(*\):*|fix\(*\):*|docs\(*\):*|chore\(*\):*|refactor\(*\):*) ;;
# *) echo "Commit message must match <type>(<scope>): <subject>, current is: $msg"; exit 1 ;;
# esac
# Team-level config (use git config --global or includeIf to differentiate by directory)
# git config --global merge.ff only
# git config --global pull.rebase true
# git config --global core.autocrlf input
# git config --global init.defaultBranch main
# Large file management
# git lfs install
# git lfs track "*.psd"
# An already committed large file: needs whole-team coordination, rewrite history with git filter-repo