单人开发git最佳实践

目标：简单、可回溯、可发布。默认仅你一人开发；必要时支持热修复与版本化。

一、分支模型（最简）

• main：稳定可发布分支，只合并经过自测的代码。

• dev：日常开发分支。

• feature/*：大改动/新功能临时分支，完成后合回 dev 并删除。

极简可只用 main + dev；重大改动临时开 feature/*。

二、一次性全局配置（建议）

git config --global user.name "你的名字"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase true      # 默认rebase，保持线性历史
git config --global core.autocrlf input   # 统一换行
git config --global fetch.prune true      # 拉取时清理已删远端分支

三、仓库初始化与基础文件

mkdir myapp && cd myapp
git init
# .gitignore（按技术栈生成）
# https://www.toptal.com/developers/gitignore

echo "* text=auto" > .gitattributes

echo "# MyApp" > README.md
git add .
git commit -m "chore: init repo"

.gitignore 忽略：依赖目录（node_modules/、.venv/）、构建产物、缓存、IDE配置、日志等。

四、提交规范（Conventional Commits 摘要）

• 小步提交、语义化信息：

feat: 新增功能
fix: 修复缺陷
docs: 文档更新
refactor: 代码重构（无特性/修复）
perf: 性能优化
test: 测试相关
chore: 构建/脚手架/杂项

• 示例：feat(login): 支持JWT刷新

五、日常开发节奏（模板）

# 开工：同步 dev（线性历史）
git checkout dev && git pull --rebase

# 开功能分支
git checkout -b feature/xyz
# ...编码 -> 小步提交

git add . && git commit -m "feat(xyz): 初版实现"

# 收尾：整理历史并合回dev
git fetch origin && git rebase origin/dev

git checkout dev
git merge --ff-only feature/xyz

git branch -d feature/xyz

git push

六、发布与版本标签（Tag）

# 确认dev稳定后合入main
git checkout main && git pull --rebase

git merge --ff-only dev

# 打附注标签（推荐）
git tag -a v0.1.0 -m "v0.1.0: 初次可用版本"

git push origin main
git push origin v0.1.0

Tag 用于标记“可发布里程碑”，方便回溯与对外发布。

七、热修复流程（Hotfix）

# 基于 main 开分支
git checkout main && git pull --rebase

git checkout -b hotfix/urgent-bug
# ...修复
git add . && git commit -m "fix: 处理token竞态"

# 合回 main 并打补丁版本
git checkout main && git merge --ff-only hotfix/urgent-bug

git tag -a v0.1.1 -m "v0.1.1: 修复token竞态"

git push origin main && git push origin v0.1.1

# 同步回 dev
git checkout dev && git pull --rebase

git merge --ff-only main && git push

git branch -d hotfix/urgent-bug

八、变更日志（可选但推荐）

• 简单：git log --oneline v0.1.0..v0.1.1

• 工具化（按提交类型分组）：conventional-changelog、cz-git 等。

九、Pre-commit 钩子（提交前自动检查）

多语言通用（pre-commit）：

pip install pre-commit
pre-commit sample-config > .pre-commit-config.yaml
pre-commit install

Node 项目（husky + lint-staged）：

pnpm add -D husky lint-staged
npx husky init
# .husky/pre-commit 中添加：
# npx lint-staged
# package.json：
# "lint-staged": { "*.{ts,tsx,js}": ["eslint --fix", "git add"] }

十、回滚策略（选正确方式）

• 已推送/公开历史：用 revert（安全）：

git revert 
git push

• 未推送/本地历史：可用 reset（危险）：

git reset --hard HEAD~1

十一、远程与备份

• 私密项目用私有仓库；启用双重验证（2FA）。

• 多远端可命名：origin（主）、backup（镜像备份）。

git remote add backup 
git push --mirror backup

十二、效率别名（建议）

git config --global alias.lg "log --oneline --decorate --graph --all"
git config --global alias.st "status -sb"
git config --global alias.co "checkout"
git config --global alias.br "branch"
git config --global alias.cm "commit -m"

十三、rebase vs merge（何时用）

• 单人开发：默认 --rebase，保持线性历史，便于回溯。

• 团队协作：避免对已推送分支做 rebase（会改写历史）。

十四、常见故障排查

• rebase 冲突：按文件解决后 git add ，继续：git rebase --continue；放弃：git rebase --abort。

• 误删/误 reset：尝试 git reflog 找到 commit，再 git checkout -b rescue 。

• 推送被拒：先 git pull --rebase 同步，再推送。

十五、一页式速查（可打印）

1. 日常：dev 拉最新 → feature/* 开发 → 小步提交 → rebase 到 dev → merge --ff-only → 推送。

2. 发布：dev → main，打 tag（vX.Y.Z），推送代码+标签。

3. 热修复：main 开 hotfix/* → 修复 → 回 main 打补丁 tag → 合回 dev。

4. 回滚：公开历史用 revert，本地未推送可 reset。

5. 整洁：pull.rebase=true、fetch.prune=true、.gitignore、pre-commit 钩子。

照此执行，可获得：清晰线性历史、稳定可发布版本、可回溯的里程碑，以及最小化的日常心智负担。