Git 仓库根目录必须等于 Go 模块根目录，否则 go mod 会拉错依赖、CI 失败、go build 报错；正确流程是先 git init 再 go mod init，确保二者路径一致，并严格配置 .gitignore 和打 tag 前运行 go mod tidy。

git 不是 Go 项目的“可选插件”，而是构建、测试、协作的基础设施。没配好 git，go mod 就会拉错依赖，CI 流水线跑不通，团队成员 clone 下来连 go build 都失败——这不是配置问题，是项目结构本身就不合法。

Git 仓库根目录必须等于 Go 模块根目录

go mod init example.com/myapp 这条命令不是“随便在哪都能跑”。它生成的 go.mod 和 go.sum 文件，记录的是当前目录下所有源码文件的路径哈希。如果 git init 在子目录里（比如 src/ 或 cmd/），而 go mod init 在上层目录执行，就会导致： - go.sum 记录的校验和与实际文件树不匹配 - go get ./... 或 go test ./... 找不到包路径 - CI 中 actions/checkout@v6 拉下来的代码树和本地开发环境不一致

正确做法：

• 先建空目录（如 myapp/）
• cd 进去，立刻执行 git init
• 再执行 go mod init example.com/myapp
• 确保 go.mod 第一行是 module example.com/myapp，且没有多余前缀或相对路径

.gitignore 必须排除非源码产物

Go 编译产物不进 Git，不是“建议”，是硬性要求。否则： - /bin、/pkg 被提交后，不同系统生成的 *.exe 或 *.a 文件污染仓库 - go.work（多模块工作区）若被提交，会覆盖开发者本地配置，导致 go list -m all 解析失败 - go test -c 生成的 *.test 文件被误 commit，CI 检查时触发二进制文件扫描告警

标准 .gitignore 至少应含：

• /bin
• /pkg
• go.work
• *<em>/</em>.exe
• *<em>/</em>.test
• **/go-build-cache

注意：不要写 **/bin —— 这会误删 internal/bin 这类合法包名；用 /bin 开头才精准匹配项目根下的目录。

MergeIQ: Automatically Score & Prioritise PR Complexity for GitLab and GitHub

使用四维度框架评估任意 GitLab MR 或 GitHub PR 的复杂度：规模（20%），认知负荷（30%），审查工作量（30%），风险/影响（20%）...

下载

立即学习“go语言免费学习笔记（深入）”；

打 tag 前必须验证 go.mod 和依赖状态

Go 生态认 git tag，不认分支名。但 tag 本身不会自动校验语义正确性： - 如果 go.mod 里写的是 module myapp（缺域名），下游 go get example.com/myapp@v1.2.0 会失败 - 如果没运行 go mod tidy，go.sum 里可能残留已删除依赖的校验和，导致 go build 报 checksum mismatch - 如果当前 HEAD 是 detached，git tag v1.2.0 后 go list -m -f '{{.Version}}' example.com/myapp 可能解析不出版本

安全打 tag 步骤：

• git checkout main（确保不在 detached HEAD）
• go mod tidy && git add go.mod go.sum && git commit -m "tidy deps"
• git tag v1.2.0
• git push origin v1.2.0

最常被忽略的一点：tag 名必须严格匹配 go.mod 中声明的模块路径。比如模块是 github.com/user/repo，就不能打 v1.2.0 以外的 tag（如 release/v1.2.0），否则 go get 无法识别。