1. 为什么一个名字和一个邮箱值得单独写一篇指南1.1 你遇到的第一个 Git 报错多半是它很多人在第一次用 Git 提交代码时都会撞上这么一段话$ git commit -m first commit *** Please tell me who you are. Run git config --global user.email youexample.com git config --global user.name Your Name to set your accounts default identity. Omit --global to set the identity only in this repository.说实话Git 这个报错算是所有错误提示里最讲道理的一个了。它把解决办法直接写在脸上要么用--global配置全局身份要么去掉--global只配当前仓库。可就是因为太讲道理大部分人扫一眼复制粘贴跑完命令就完事了压根没想过这里面还有作用域、优先级、多账户管理的问题。结果呢过了一段时间发现诶我提交记录里的名字怎么是乱的公司项目和个人项目用户名混在一起提交邮箱写错了但是历史里已经留痕这时候再回来查配置就开始痛苦了。1.2 user.name 与 user.email 到底存到哪里去了先说一个容易被忽略的事实user.name和user.email并不是 Git 运行时才临时生成的东西而是被写进配置文件里的两个键值对。Git 有一套完整的配置体系每次执行命令时它都会按优先级把多份配置文件合并起来形成一份当前生效配置。这份配置里除了user这个段落还有core比如默认编辑器、换行符处理、alias命令别名、remote远程仓库地址、credential凭证存储方式等。我们这篇文章聚焦user段但搞懂了它的存储位置其他配置项你也能举一反三。最常见的三个配置文件位置如下级别配置文件位置Linux/macOS配置文件位置Windows影响范围system/etc/gitconfigGit 安装目录下的etc/gitconfig这台机器上的所有用户、所有仓库global~/.gitconfigC:\Users\你的用户名\.gitconfig当前系统用户的所有仓库local仓库/.git/config同左仅当前这个仓库优先级从高到低是local global system。也就是说如果你在某一个仓库里单独设置了user.name那么在这个仓库里它会把全局设置覆盖掉出了这个仓库全局设置又恢复生效。这个优先级机制是后面所有多账户配置方案的基石。1.3 提交记录里的身份信息会跟着代码走一辈子再提醒一个大家容易忽略的事实user.name和user.email一旦写入提交commit就会永久固化在 Git 的提交对象里。哪怕你之后改了配置之前的提交记录上的名字、邮箱也不会自动变化。这一点和 SVN、Perforce 这类集中式版本控制不太一样。Git 的提交对象是基于内容寻址的提交里的 author、committer 信息是 commit 对象内容的一部分。一旦提交被创建它的哈希值就由这些内容共同决定想改历史身份本质上就是在改写历史、重建提交对象。所以配置用户名和邮箱这件事不是先糊弄过去后面再改的小事而是一个写下去就不容易抹掉的决策。尤其是开源项目、对外发布的代码提交者身份直接关联到个人品牌和项目归属值得在一开始就认真对待。2. 三种配置级别与优先级global、local、system 怎么选2.1 配置级别对照别一上来就 --global很多人对--global有路径依赖觉得一条命令配完全局一劳永逸。这在单账户、单用途的开发环境里没毛病但如果你同时参与公司项目、个人开源项目、外包项目就迟早要面对身份切换的问题。我见过一个最常见的翻车现场开发者用个人账号全局配置了 Github 的邮箱然后到公司仓库里提交代码结果公司内部代码审查平台把提交人识别成外部邮箱权限和记录全部乱套。他当然可以用git commit --amend --reset-author修改上一次提交但如果是已经 push 到远端、已经被同事拉取过的提交改起来就要动用--force危险性陡然上升。所以在动手配置之前先想清楚你的实际场景如果只是自己写点东西项目和个人身份不冲突--global完全可以如果公司项目和个人项目需要不同身份那就应该公司仓库用 local 配置覆盖如果一台机器上有多套身份需要按目录自动区分就需要用includeIf条件包含。2.2 查看当前生效配置的正确姿势先别急着配置先学会看。我建议每次配完都执行下面这条命令确认实际生效的配置来自哪个文件git config --show-origin --list--show-origin会明确打印出每一项配置来自哪个文件、哪一行。例如file:C:/Users/你的名字/.gitconfig user.name你的名字 file:C:/Users/你的名字/.gitconfig user.emailyouexample.com file:.git/config user.name公司名字 file:.git/config user.emailyoucompany.com这样你一眼就能看出来当前仓库里生效的user.name到底是全局的还是本地的避免我明明配了怎么没生效这种经典问题。只查看user相关配置也可以用更精准的命令git config user.name # 查看当前仓库生效的 user.name git config --global user.email # 查看全局 user.email git config --list --show-origin | grep -i user # 快速过滤注意git config user.name不带任何级别参数时显示的是当前仓库最终计算出的生效值而不是某一个文件里的值。如果你想单独看某个级别git config --global --get user.name git config --local --get user.name这样区分清楚了配了没生效的排查就简单了。2.3 最小命令集收藏这几条就够了如果你只想记住最基本的东西下面这几条就是全部家当# 设置全局身份 git config --global user.name Your Name git config --global user.email youexample.com # 设置当前仓库身份会覆盖全局 git config --local user.name Company Name git config --local user.email youcompany.com # 查看 git config --show-origin --list # 修改 git config --global user.name New Name # 删除某一项配置 git config --global --unset user.email这里有一个容易歧义的点git config --local可以简写成git config不带任何级别参数时默认就是 local但我还是建议你在命令里显式写出--local。原因有两点第一可读性好别人看你的命令就知道你只想改当前仓库第二避免在仓库根目录之外误执行了 local 配置命令导致 Git 报fatal: not in a git repository。顺带一提git config --global --unset这个删除操作也经常被忽略。有些人想重置配置不知道有 unset就直接去编辑~/.gitconfig文件。其实命令效率高得多而且不容易因为手误破坏文件格式。3. 不同项目不同身份多账户场景的完整配置思路3.1 公司项目和个人项目分开管理多账户配置的核心逻辑很简单用 local 配置覆盖 global 配置。先在全局配好个人默认身份然后在公司仓库目录下单独执行 local 配置。# 全局配个人身份 git config --global user.name Zhang San git config --global user.email zhangsangmail.com # 进入公司仓库覆盖为公司身份 cd ~/work/company-project git config --local user.name zhangsan.corp git config --local user.email zhangsancompany.com这么做的好处是直观、可控每个仓库的身份清清楚楚。缺点也明显如果新 clone 一个公司仓库很容易忘记配 local 身份带着全局的个人身份就提交了。所以我的习惯是先全局配置个人身份然后所有公司仓库一定在 clone 完成后第一时间配 local并且在第一次 commit 前用git config user.name、git config user.email看一眼。好记性不如烂笔头提交之前花两秒钟确认一下能省掉后面amend甚至rebase的麻烦。3.2 用 includeIf 按目录自动切换身份如果觉得手动切换太麻烦Git 2.13 之后引入的includeIf就是为你准备的。它可以根据仓库所在路径自动加载不同的配置文件。我的做法是这样在~/.gitconfig里写一个条件包含把所有放在~/work/目录下的仓库统一指向公司身份配置其他目录统一走个人身份。# ~/.gitconfig [user] name Zhang San email zhangsangmail.com [includeIf gitdir:~/work/] path ~/.gitconfig-work然后在~/.gitconfig-work里写公司专属身份# ~/.gitconfig-work [user] name zhangsan.corp email zhangsancompany.com这样只要仓库路径在~/work/下Git 就会自动加载公司的用户名和邮箱不需要手动配 local也不会忘记。gitdir:后面支持通配符比如~/work/company/只对特定目录生效。这里有个细节需要注意includeIf的路径判断是基于git rev-parse --git-dir的结果所以它对git worktree的场景同样有效只要是同一个仓库目录下的 worktree 子目录都会被判定到同一身份。这一点你如果用了 Git 的 worktree 功能会特别省心。3.3 身份配错后的补救git commit --amend 的正确用法万一忘记配 local 就提交了或者提交时带了错误的身份别慌在提交还没有推送到远端之前可以用--amend修改上一次提交的作者信息。# 直接重置为当前配置的身份 git commit --amend --reset-author --no-edit # 或者手动指定新的作者和邮箱 git commit --amend --authorNew Name newemailexample.com --no-edit--reset-author的意思是把这次提交的 author 重置为当前配置里的 user.name / user.email--no-edit则是保持提交信息不变不需要重开编辑器。执行完后提交哈希会改变所以只适用于还没有推送的本地提交。如果提交已经推送了怎么办那是另一个更复杂的话题涉及git rebase或filter-repo改写历史而且推送到远端后需要强制推送会给团队其他人带来同步问题。这里我只强调一点提交是会被别人拉走的一旦离开你的电脑身份问题就不是你一个人的问题了。所以最优策略永远是提交前检查而不是事后修补。4. Windows/Linux/macOS 下配置时容易踩的隐藏坑4.1 配置文件位置与直接编辑方式不同操作系统下全局配置文件的默认位置略有差别但这只是表象真正容易出问题的是编辑器打开的文件不对。Linux/macOS 下~/.gitconfig就在用户主目录下直接用vi、nano都能编辑。Windows 下分两种情况如果用的是 Git Bash~通常指向C:\Users\你的用户名那么~/.gitconfig就是C:\Users\你的用户名\.gitconfig如果直接用 cmd / PowerShell有时%USERPROFILE%和%HOMEDRIVE%%HOMEPATH%指向的位置不一致比如公司域环境下 H 盘映射可能导致我明明改了配置Git 却不认的诡异问题。我的建议是在 Windows 上配置 Git优先用 Git Bash不要用 cmd。这不仅仅是因为 Git Bash 的~解析更符合 Linux 习惯还因为它自带vi、grep、awk等常用工具排查配置时方便很多。如果你偏好直接改配置文件也可以用命令直接打开# Linux / macOS git config --global --edit # Windows Git Bash git config --global --edit这条命令会调用 Git 配置的默认编辑器通常是 vi直接打开全局配置文件可以手工修改、保存。手工编辑时一定要小心文件格式ini格式虽然简单但缩进、[section]名称写错Git 可能静默忽略不报错也不生效。4.2 编码、换行符和路径中的坑说几个我在实际使用中踩过的坑。第一个坑是用户名或邮箱里带中文。Git 本身是支持 UTF-8 的user.name 张三完全合法提交记录里也能正常显示。但问题出在终端环境Windows 的 cmd 默认代码页不是 UTF-8Git Bash 在部分系统上也可能出现中文乱码。所以如果你在 Windows 上工作并且参与的国际项目较多我建议user.name统一用拼音或英文避免跨平台协作时的显示问题。这不是能力限制而是兼容性取舍。第二个坑是邮箱使用了.gitconfig里没加引号导致解析异常。比如用户名中间有空格一定要用双引号括起来git config --global user.name Zhang San不加引号虽然某些情况下也能写入但遇到特殊字符时行为不可预期。第三个坑是换行符CRLF。Windows 仓库的.git/config如果被某些编辑器保存成了带 UTF-8 BOM 的文件Git 读取时可能把 BOM 当成键的一部分导致user.name看起来正常匹配不上。碰到这种情况用git config --show-origin --list看输出里有没有\xef\xbb\xbf之类的前缀基本就能定位。解决办法是用 Git Bash 里的vi或nano重新保存文件为无 BOM 的 UTF-8。4.3 验证配置是否生效的三种方法配置完之后验证是必须的一步。我通常用三种方式交叉确认方式一直接看当前生效值git config user.name git config user.email方式二看配置来源git config --show-origin --get user.name git config --show-origin --get user.email方式三看最近一次提交的实际作者git log -1 --formatname: %an, email: %ae%an是 author name%ae是 author email。这条命令看得是已生成提交里的真实身份比git config更眼见为实。我强烈建议你在第一次提交后立刻看一眼git log防止配置出问题还傻乎乎地一路提交下去。5. 从配置看 Git 的几个反直觉行为5.1 改了 config不会自动改历史前面说过提交对象一旦生成作者信息就被固化了。这里我再补充一个细节Git 提交里有author和committer两套身份。user.name/user.email决定了 author作者身份当发生 rebase、cherry-pick、amend 等操作时committer提交者会被更新为当前执行操作的人而 author 保持不变。所以你会看到一种情况代码是 A 写的但 rebase 之后提交记录里的 committer 变成了 B。这是 Git 的正常行为不是 bug。这篇文章虽然聚焦user.name和user.email的配置但我希望你能透过这个细节明白一件事身份配置影响的不仅仅是提交时打上的标签它还会在整个版本历史演化的过程中不断被引用。所以配置的准确性远比表面看起来重要。5.2 worktree 与 local 配置的联动Git worktree 允许你在同一仓库中同时检出多个工作目录。这种情况下每个 worktree 共享同一个.git目录因此 local 配置也是共享的。换句话说你在主工作目录里git config --local user.name 张三在该仓库的任何 worktree 里都一样生效。这个特性在多任务并行时非常有用。比如公司项目开了一个 hotfix 分支放在单独 worktree 里它的提交身份会自动继承公司项目的 local 配置不会因为路径不同而切到个人身份。这一点在实践中比includeIf更可靠因为includeIf是按路径匹配的而 worktree 可能分散在不同路径下。但同时也要注意worktree 中不能只对某一个 worktree 单独设置 local 配置因为 local 配置本来就属于整个仓库不是属于某个 worktree。如果你确实需要不同 worktree 使用不同身份就得用环境变量或者条件配置来实现普通配置做不到。5.3 团队协作时如何约定身份信息最后从团队角度多说一句。user.name和user.email虽然是个人配置但在团队协作里它直接影响到代码审查、自动化流程比如 commit 信息关联到工单系统、以及责任追溯。我参与过的几个项目分几种做法个人邮箱方案开发者用自己的个人邮箱提交团队成员通过 Git 别名映射到真实身份。优点是配置简单缺点是代码和公司的身份体系割裂。公司邮箱方案所有代码用公司邮箱提交统一在代码平台里关联权限。优缺点正好相反。noreply 邮箱方案GitHub 等平台提供用户名users.noreply.github.com的隐私邮箱避免暴露真实邮箱。开源项目提 PR 时特别建议用这种防止垃圾邮件抓取。不管选哪种方案团队层面至少应该做到统一约定。我在实际项目中见过最混乱的情况是有人用公司邮箱有人用个人邮箱还有人用noreply邮箱导致代码平台的贡献者图谱、邮件通知、代码归属全都对不上号。其实这就是花五分鐘在项目 README 里写一行字能解决的事。还有一点容易被忽略配置身份和配置 SSH key 是完全独立的两件事。有人把user.email配成 GitHub 的noreply邮箱然后问为什么 push 还需要输密码这其实是两个概念身份是你是谁SSH key 是凭什么让你推代码。Git 平台的权限认证主要看 SSH key 或 HTTPS 凭证和提交身份没有直接关系。把这两个概念分开很多困惑就迎刃而解了。Git 的用户名和邮箱配置看起来是新手村任务实际上贯穿了版本控制的整个生命周期。我自己的习惯是每到一个新环境第一步配置 Git 全局身份和换行符规则第二步配置 SSH key第三步 clone 项目前先确认仓库目录归属。这套流程看起来繁琐但能省下后面大量无谓的amend和rebase时间。毕竟工具越顺手你才越能把精力花在真正值得的事情上。