命令序列（Mac，基于origin/main，分支名：feature/auth-middleware）

• 更新本地并从最新主干创建功能分支

  • git fetch origin
  • git switch -c feature/auth-middleware origin/main
    • 如主干为develop，请把“main”替换为“develop”。

• 检查现有GPG签名配置（保留现有全局配置，不修改）

  • git config --show-origin --get commit.gpgsign
  • git config --show-origin --get user.signingkey
  • gpg --list-secret-keys --keyid-format=long
  • 在终端会话中确保pinentry正常弹出（macOS常见需要）：
    • export GPG_TTY=$(tty)
    • 可选：git config --global gpg.program gpg

• 仅暂存 src/middleware 与相关测试改动（使用交互式分块暂存，避免无关变更）

  • git status
  • git add -p -- src/middleware
  • 按你的测试目录实际情况选择其一或多个：
    • git add -p -- tests
    • git add -p -- test
    • git add -p -- src/tests
  • 查看当前暂存内容：
    • git diff --staged --name-only

• 如有误加的文件或敏感文件，立即撤销暂存

  • 示例：
    • git restore --staged .env .env.* .DS_Store *.pem .key config/.yaml
    • 再次确认：
      • git status --porcelain

• 进行GPG签名提交（强制签名）

  • git commit -S -m "feat(auth-middleware): add authentication middleware and tests"

• 验证签名

  • git log --show-signature -1

• 推送到origin并设置上游（准备发起PR）

  • git push -u origin feature/auth-middleware

注意事项与关键点

• 基准分支要最新：先 git fetch origin，再从 origin/main（或origin/develop）创建分支，避免老基线引起后续PR冲突。
• GPG签名要点（macOS）：
  • -S 参数会强制为该次提交使用GPG签名，即使你已在全局开启 commit.gpgsign = true，仍建议使用 -S 明确化。
  • 若终端不弹密码输入框或提交未签名，常见修复：
    • export GPG_TTY=$(tty) 放入你的 shell 配置（如 ~/.zshrc）。
    • 安装/启用 pinentry-mac（brew install pinentry-mac），并在 ~/.gnupg/gpg-agent.conf 配置 pinentry-program，再执行 gpgconf --kill gpg-agent。
  • 确保你的公钥已上传到Git托管平台（如GitHub）以显示“Verified”徽标。
• 只提交目标路径的改动：
  • 使用 git add -p 精准挑选变更，避免 git add . 这类“全加”操作。
  • 提交前总是 git diff --staged 查看“将被提交”的文件与内容。
• 避免提交敏感/无关文件：
  • 常见敏感项：.env、证书/密钥（*.pem, .key）、私有配置（config/.yaml）、操作系统杂项（.DS_Store）。
  • Node项目建议在 .gitignore 中包含：
    • .env
    • .env.*
    • .DS_Store
    • node_modules/
    • coverage/
    • npm-debug.log*
    • *.pem
    • *.key
  • 如果依赖锁定策略明确，请遵循团队规范是否允许提交 package-lock.json 变更；不确定时先不提交。
• 推送与PR：
  • 首次推送使用 -u 绑定上游，后续 git push 不需额外参数。
  • 推送后到平台发起PR，或使用命令行工具（如 GitHub CLI：gh pr create），但本流程已满足“准备发起PR”的要求。
• 提交信息建议采用约定式提交，便于审查与语义化版本：
  • 例如：feat(auth-middleware): add JWT auth middleware and tests

这样可确保功能分支清晰、提交已签名、只包含中间件与测试变更，并避免敏感文件泄露。

变量准备（按需替换）

REPO_URL="https://your.git.server/your/monorepo.git" BASE_BRANCH="main" # 基准分支，例如 main 或 develop FEATURE_BRANCH="fix/payment-bug-123" # 你的评审分支名

1) 部分克隆 + 浅克隆（仅当前分支，无标签，不立即检出）

关键点：

- --filter=blob:none：部分克隆，初始不拉取任何文件内容（blob），按需懒加载；远端需支持 partial clone

- --depth=1：浅克隆，仅取最新提交，适合评审/缺陷修复

- --single-branch：仅抓取指定分支，避免多分支历史

- --no-tags：不抓取标签，进一步减少体量

- --no-checkout：暂不检出工作区，先配置稀疏规则再检出，避免不必要下载

git clone --filter=blob:none --depth=1 --single-branch --no-tags --no-checkout -b "$BASE_BRANCH" "$REPO_URL" monorepo cd monorepo

2) 启用稀疏检出（cone模式更高效，需 Git >= 2.25）

git sparse-checkout init --cone

3) 仅检出目标子目录 services/payment

关键点：

- set 会覆盖稀疏规则，仅包含此目录；如需追加可用 git sparse-checkout add <path>

git sparse-checkout set services/payment

4) 现在再检出基准分支（此时仅会按需拉取 services/payment 的必要对象）

git checkout "$BASE_BRANCH"

5) 创建并切换到评审分支

git switch -c "$FEATURE_BRANCH"

6) 进行修改后，提交变更（仅提交目标目录）

注意：避免在仓库根做全量操作（如不带路径的 git grep/ls-files），以免触发多余对象下载

git add services/payment git commit -m "fix(payment): <简要描述缺陷修复内容>"

7) 推送到远程供评审

git push -u origin "$FEATURE_BRANCH"

常用补充（按需执行）：

- 如需再加入其他依赖目录（增量，不会取消已有规则）

git sparse-checkout add libs/payment-common

- 验证当前稀疏规则

git sparse-checkout list

关键注意点汇总：

- 远端需支持部分克隆；若遇到 “server does not support partial clone”，去掉 --filter=blob:none 退化为仅稀疏检出

- 浅克隆（--depth=1）适合评审与小改动；复杂变基/合并可能需要加深历史（git fetch --deepen=N 或 --unshallow）

- 稀疏检出下尽量限定路径操作（e.g., git add services/payment），避免触发非目标目录的懒加载

- --single-branch 与 --no-tags 可显著减少初次网络与本地占用，在 monorepo 尤其重要