分支与提交

命名规则与检查命令

用全小写、词与词用连字符、总长不超过 40 个字符。名称要能看出改了什么：fix/123 和拼音分支看不出。main 与 release 是例外，它们不套这个格式。

git switch -c feat/load-note

# 推送前看当前分支名，并用同一台正则自检
git branch --show-current |
  grep -Eq '^(feat|fix|docs|refactor|test|chore)/[a-z0-9]+(-[a-z0-9]+)*$'

# 合回之后删除远端分支
git push origin --delete feat/load-note

写成这样 / 留在本地不推送

feat(notes): 按会话里的所属范围读取笔记

请求体里的 scope_id 不再采用，避免读到其他范围。
读路径统一走 internal/notes.Visible，列表与详情共用一处判断。

Refs: #12

这三种会被检查拦住

update
fix bug
修改了一下

commitlint.config.mjs

阈值写进配置，红了的改动由写代码的自己改，不进评审。subject-case 关掉，因为中文没有大小写。范围不在清单里时只警告，用来发现新出现的模块名。

export default {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "header-max-length": [2, "always", 72],
    "subject-empty": [2, "never"],
    "subject-case": [0],
    "type-enum": [
      2,
      "always",
      ["feat", "fix", "docs", "refactor", "test", "chore", "perf"],
    ],
    "scope-enum": [
      1,
      "always",
      ["notes", "http", "env", "db", "ui", "docs", "deps", "ci"],
    ],
    "body-max-line-length": [2, "always", 100],
  },
};

装上钩子（git 自带的 hooksPath，不依赖前端工具链）

prepare-commit-msg 给编辑器预填模板，commit-msg 做检查。两个文件都要给执行权限：chmod +x .githooks/*。

git config core.hooksPath .githooks

.githooks/commit-msg

#!/bin/sh
npx --no-install commitlint --edit "$1"

仓库里没有 Node 时的替代检查

纯 Go 或纯 Python 仓库不想为一条检查引入 Node 时，用这条 grep。它只查类型与长度，查不了正文。

#!/bin/sh
msg=$(head -n1 "$1")
echo "$msg" | grep -Eq '^(feat|fix|docs|refactor|test|chore|perf)(\([a-z0-9-]+\))?: .{1,50}$' \
    || { echo "提交信息不符合模板: $msg"; exit 1; }

自检命令

第二条用来排除生成文件，否则一次依赖升级就会让行数失控。第三条按提交逐个统计，用来找「一条提交做了两件事」。

git diff --shortstat main...HEAD
git diff --name-only main...HEAD | wc -l
git diff --numstat main...HEAD |
  grep -vE '(package-lock\.json|go\.sum|\.min\.)' |
  awk '{a+=$1; d+=$2} END {print a+d" 行"}'
git log --oneline --no-merges main..HEAD

助手交出来的样子

$ git log --oneline -5
3f1a2c9 update
a8b0d11 fix
7c2e4f3 修改
9d1a0b5 wip
e5c7d22 update code