昨天帮一位刚转 Linux 开发的同学排查 git 推不上去的问题绕了二十分钟最后发现不是网络、不是权限而是user.name和user.email这两个最基础的配置没写。这事让我想写一篇关于 Linux 下 git 配置的文章。网上这类教程不少但大多数停留在“照着敲一遍能跑”的层面对配置为什么这么写、出问题时怎么查讲得很浅。这篇内容适合三类人刚把开发机从 Windows 切到 Linux、之前只会git config --global一条龙的新人在服务器上频繁遇到 git 诡异报错、想系统搞懂配置层级的运维还有准备给团队统一 Linux 开发环境规范的组长。我会从安装、基础配置、SSH 通道、高频报错排查到最终的配置模板把这几年在 Linux 上折腾 git 的经验一次性写清楚保证每一条都能直接用、也都能讲出个所以然。1. Linux 上的 git 配置和 Windows 到底差在哪1.1 三层配置优先级绝大多数新手栽在这里Git 的配置不是只有一份而是分成三个层级从低到高分别是 system、global、local。理解这三个层级基本就理解了 Linux 上 git 配置八成的坑。system 级配置文件在/etc/gitconfig影响这台机器上的所有用户。一般由管理员设置比如统一的编辑器、统一的core.autocrlf策略。global 级配置文件在~/.gitconfig只对当前用户生效。个人身份、个人 alias 一般写在这里。local 级配置文件在具体仓库下的.git/config只对当前仓库生效。项目层面的策略比如pull.rebase、remote.origin.url写在这里。三个层级的优先级是local global system也就是说仓库内配置能覆盖全局配置全局配置能覆盖系统配置。我见过最典型的翻车现场是明明设置了全局user.name结果某个仓库里还残留着一个另一个身份提交记录里显示的是别人。遇到这种情况直接看仓库里的.git/config就明白了。这里有个特别容易误导新手的细节直接运行git config user.name xxx很多人以为写的是全局配置实际上如果你正在一个 git 仓库目录里运行它默认写的是local 级如果你不在仓库目录里运行它会直接报fatal: not in a git repository。所以我的建议是凡是想全局生效的配置一律显式带上--global不要偷懒省略。查看所有生效配置用这一条git config --list --show-origin--show-origin会告诉你每条配置来自哪个文件。排查“为什么这个配置没生效”的时候这条命令比什么都好用。配置层级配置文件位置优先级典型用途system/etc/gitconfig最低机器级统一策略global~/.gitconfig中个人身份、aliaslocal.git/config最高单仓库覆写1.2 Linux 和 Windows 的行为差异换行符只是其中一项很多从 Windows 迁移过来的开发者第一次在 Linux 上遇到 git 的“灵异事件”往往不是配置本身错了而是两个平台的文件处理习惯不一样。第一个差异是换行符。Windows 默认用 CRLF回车加换行作为行尾Linux 和 macOS 默认用 LF换行。Git 本身提供了一个自动转换机制core.autocrlfWindows 上装 Git 时通常会被设成true意思是提交时把 CRLF 转成 LF、检出时把 LF 转成 CRLF。于是很多人把 Windows 的习惯带到了 Linux 上上来就git config --global core.autocrlf true结果在 Linux 上会导致仓库里所有文件在检出时变成 CRLFdiff 一片红。在 Linux 上一般建议设成input或保持默认false这个我在后面专门展开讲。第二个差异是文件权限位。Linux 会跟踪文件的可执行位Windows 不关心这个问题。所以一个仓库如果在 FAT/exFAT 分区上、或者通过某些共享挂载方式被 Linux 读取Git 会频繁地告诉你文件被修改了因为权限位一直在变。这时候不是真的有人改了你的代码而是core.fileMode在作怪。第三个差异是大小写敏感。Linux 文件系统默认区分文件名大小写macOS 和 Windows 默认不区分。如果有人在仓库里把README.md改成了readme.md在 Linux 上可能就是两个文件处理起来非常麻烦。这些差异决定了我们在 Linux 上配置 git 时不能无脑复制 Windows 的配置模板必须有针对性地调整。2. 安装这一步没做对后面全是玄学2.1 包管理器安装不同发行版别用错命令配置 git 的前提是先装好 git。Linux 发行版五花八门但安装方式基本都是通过各自的包管理器命令差别很大。发行版安装命令Debian / Ubuntusudo apt update sudo apt install -y gitRHEL / CentOSsudo yum install -y gitFedora / RHEL 9sudo dnf install -y gitopenSUSEsudo zypper install -y gitArch Linuxsudo pacman -S gitAlpine Linuxapk add git我重点提醒一下 Debian/Ubuntu 系的操作顺序先apt update再apt install。很多新手直接sudo apt install git然后报Unable to locate package git第一反应是源有问题其实只是本地的软件包索引太旧还没同步到最新的软件列表。先更新一下索引绝大多数情况下问题就没了。安装完输入git --version验证。如果提示command not found检查是不是没装成功或者当前用户的 PATH 没包含 git 的安装目录。有些系统上 git 装完之后需要重新开一个终端会话因为登录 shell 的 PATH 是登录时加载的。2.2 版本老旧怎么办源码编译的适用场景如果你用的是 CentOS 7 这类还在生命周期内的老系统默认源里的 git 版本可能非常老1.8.x 时代。这种版本有几个明显问题init.defaultBranch这种新配置项不识别、对 SSH 格式的兼容性差、部分新命令缺失。如果不想换系统源码编译新版本是唯一干净的路。以 RHEL/CentOS 7 为例先装编译依赖sudo yum install -y gcc make autoconf automake libcurl-devel expat-devel gettext-devel openssl-devel perl-devel zlib-devel然后下载源码包编译wget https://github.com/git/git/archive/refs/tags/v2.45.0.tar.gz tar xf v2.45.0.tar.gz cd git-2.45.0 make configure ./configure --prefix/usr/local make -j$(nproc) sudo make install hash -r git --version这里有个细节GitHub 上直接下载的 tag 源码包不一定带configure脚本所以需要先执行make configure让 autoconf 生成它。-j$(nproc)是根据 CPU 核数并行编译能省不少时间。编译安装到/usr/local而不是直接覆盖系统自带的 git这样你不用碰系统包的依赖关系。hash -r是清空 shell 的命令哈希表确保后续敲git拿到的是新版本而不是老版本的缓存。我不是鼓励大家都去源码编译如果发行版源里的 git 版本够新直接用包管理器就完事。源码编译只适合那些受限于系统版本、又确实需要新功能的场景。3. 逐条过一遍必须设的和容易踩的配置项3.1 身份三件套user.name、user.email、signingkey身份配置是 git 的第一优先级。没有正确配置身份你提交的代码就没有正确的作者信息团队协作和代码审查都会乱。设置命令很简单git config --global user.name Your Name git config --global user.email youexample.com这里我要强调一个反直觉的点user.name不一定等于你的真实姓名它只是提交记录里显示的“署名”。在开源社区很多人用昵称或者 ID 作为user.name但user.email一定要填对因为很多代码托管平台和 CI 系统是靠邮箱关联账号的。如果你的公司有统一的代码提交邮箱规范务必遵循。进阶一点的配置是 GPG 签名。如果你在团队里要求提交必须经过验证那要设置user.signingKey和commit.gpgsign。这一块很多人忽略但它其实比想象中简单git config --global user.signingKey 你的GPG密钥ID git config --global commit.gpgsign true配置完签名后每次 commit 都要输入 GPG 密钥密码可以用gpg-agent缓存密码来减少输入次数。这个属于“要用的时候再去折腾就行”的配置不是新手第一天的任务。3.2 core.autocrlf 在 Linux 上到底该怎么设这一小节是全文我最想让你记住的部分。core.autocrlf的三种取值true提交时 CRLF 转 LF检出时 LF 转 CRLF。这是 Windows 的默认推荐配置。input提交时 CRLF 转 LF检出时不转换保留 LF。false完全不做转换原样入库、原样检出。Linux 上的正确选择是input或者false。我个人倾向input原因很简单它能防止你把带 CRLF 的文件提交进仓库。git config --global core.autocrlf input设成true在 Linux 上只会带来麻烦。设想一下你在 Linux 上克隆了一个本来全是 LF 的仓库设成true之后所有文件检出时都会被加上 CRLFgit status直接显示所有文件都 modified。这种问题极其迷惑因为文件内容看起来没有任何变化但 Git 就是觉得“改了”。如果你是纯 Linux 环境设成input是最稳的。如果项目里已经有历史包袱最好的方式是仓库根目录放一份.gitattributes文件把换行符规则固定下来* textauto eollf *.bat text eolcrlf *.cmd text eolcrlf.gitattributes的优先级高于core.autocrlf它对团队所有人生效能彻底解决“我机器上好好的、你机器上就 diff 全红”的跨平台问题。这是配置换行符的终极形态。3.3 中文文件名乱码core.quotepathLinux 上另一个高频配置是core.quotepath。默认情况下Git 为了兼容性会把非 ASCII 字符的文件名转成八进制转义序列显示。你在git status里看到的不是测试.txt而是类似\346\265\213\350\257\225.txt的东西。解决方式git config --global core.quotepath false注意这行配置不影响仓库内容只影响 Git 命令在终端里的显示。设完之后git status、git log就能直接显示中文文件名了。顺手检查一下终端的 locale 是否支持 UTF-8可以执行locale | grep LANG如果输出是LANGC或者POSIX终端基本不支持中文显示改一下环境变量export LC_ALLC.UTF-8或者写成export LANGen_US.UTF-8都行。3.4 init.defaultBranch 与 pull.rebase顺手改掉默认行为用git init初始化仓库时老版本默认分支叫master现在主流平台默认分支基本都是main。为了统一习惯建议设置git config --global init.defaultBranch main这样本地新建仓库的主分支就是main推送到托管平台时不容易出现分支名不一致的混乱。pull.rebase是个有争议的选项我先说结论新手和大多数团队建议设成false也就是git pull时执行 merge 而不是 rebase。git config --global pull.rebase false为什么不建议新手一上来就pull.rebase true因为 rebase 会把你的本地提交“挪”到远程分支的顶部如果遇到冲突解决起来比 merge 冲突更复杂需要处理rebase中断状态新手很容易卡住。我见过不少同学把pull.rebase true当成“神优化”抄过去结果第一次冲突就吓得不知所措。等你对 git 的工作流有感觉了想追求线性历史再改成true也不迟。配置不是越激进越好而是越适合你越好。3.5 alias 与 fileMode两个顺手的小优化alias 是配置里性价比最高的部分。把高频命令缩短能显著减少日常操作时间git config --global alias.co checkout git config --global alias.br branch git config --global alias.st status git config --global alias.cm commit -m git config --global alias.lg log --graph --prettyformat:%h %ad %s %d --dateshort git config --global alias.unstage restore --stagedalias.lg是我的最爱一眼就能看清提交历史和分支走向比默认的git log直观太多。注意 alias 里如果有空格和参数要用双引号包住整段内容。core.fileMode这个配置默认在 Linux 上是 true代表 git 会跟踪文件可执行位的变化。如果你的仓库位于某个不稳定的文件系统上或者你经常把仓库挂在 Windows 分区里使用会出现 git 莫名其妙告诉你一堆文件被修改的情况。这时候可以在仓库内临时关掉git config core.fileMode false但要提醒的是这只是“眼不见为净”的权宜之计正常磁盘环境不建议关掉它因为可执行位本来就是一个真实属性关掉反而可能漏掉问题。4. SSH 通道配置从生成密钥到多账号隔离4.1 ed25519 密钥生成与 ssh-agent 常驻配置 SSH 是 Linux 上 git 的必修课因为它不仅解决了“每次推送都要输密码”的烦恼也是更安全的身份认证方式。首先生成密钥ssh-keygen -t ed25519 -C youexample.com -f ~/.ssh/id_ed25519-t ed25519指定用更现代、更安全的算法-C是备注通常写自己的邮箱方便平台识别-f指定密钥保存路径。一路回车的话会生成~/.ssh/id_ed25519私钥和~/.ssh/id_ed25519.pub公钥。生成后把公钥内容复制出来粘贴到 GitHub、GitLab 或公司自建平台的 SSH Keys 设置里。验证连通性用ssh -T gitgithub.com第一次连接如果提示确认主机真实性输入yes回车即可之后 Git 就能通过 SSH 协议拉取和推送了。有些环境还需要把密钥交给 ssh-agent 管理eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519ssh-agent 的作用是让你不用反复输入私钥口令。桌面发行版一般会自动启动 ssh-agent纯命令行的服务器环境需要手动执行一次。这里必须强调权限问题chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519OpenSSH 对私钥文件权限非常敏感如果权限过于开放比如 644它会直接拒绝使用该密钥而且报错信息不一定直观你可能会看到Permission denied (publickey)而完全摸不着头脑。这是一个来自真实教训的提醒。4.2 config 文件实现多账号隔离我的实际配置很多人不止一个代码托管账号公司 GitLab 一个、个人 GitHub 一个。如果只生成一个密钥两个平台都能用倒也可以但想彻底隔离身份、避免误推到错误仓库最好给每个平台单独分配密钥。你需要在~/.ssh/config里写清楚每个 Host 使用哪个私钥。这是我的参考配置Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_work IdentitiesOnly yes配置文件的匹配规则是“第一个匹配到的 Host 块生效”所以把具体的配置写在前面不要把一个宽泛的Host *放在前面否则后面的规则永远不会被用到。IdentitiesOnly yes是关键它告诉 SSH 只使用我们显式指定的私钥文件不要因为 ssh-agent 里恰好有别的密钥就乱试一堆。没有这行你会经常遇到“明明配好了但认证失败”的问题。配好后git clone gitgithub.com:user/repo.git就会自动使用对应密钥不需要手动指定。排查多账号问题最有效的命令是ssh -vT gitgithub.com-v参数会打印完整的 SSH 认证过程你能看到它尝试了哪些密钥、最终哪一步失败比瞎猜快得多。4.3 HTTPS 模式的凭证保存也要挑一种够用的如果你习惯用 HTTPS 方式克隆仓库那要面对的是每次推送都要输入用户名和密码或者 token。解决办法是配置credential.helper。Linux 上常见三种helper行为安全性cache凭据缓存在内存默认 900 秒后过期较高但过期后要重新输入store明文写入 ~/.git-credentials低方便但泄露风险大libsecret调用系统钥匙串保存高适合桌面环境我的建议命令行服务器上优先用 SSH 而不是 HTTPS开发机上如果非要用 HTTPS至少用带超时的 cachegit config --global credential.helper cache --timeout3600意思是把密码存在内存里一个小时。不要轻易用store它虽然省事但等于把密码以明文形式放在磁盘上一旦机器被扫描到后果可想而知。5. 高频报错的排查链路遇到别慌5.1 fatal: not a git repository (or any of the parent directories): .git这个报错可能是 git 新手在 Linux 上遇到的第一道坎。字面意思是当前目录或父目录里都没有.git目录。最常见的场景是你在一个初始化过的仓库里删掉了.git目录或者把仓库目录 tar 备份时没带上隐藏目录。还有一种情况你在一个子目录里执行 git 命令但子目录所在的项目根目录本身就还没git init。排查链路按顺序来pwd ls -la git rev-parse --git-dir echo $GIT_DIR env | grep -i git一步步确认当前路径、是否有.git目录、git 解析的仓库目录在哪、环境变量GIT_DIR是否被人为设置过。最后这条很容易忽略很多 CI 脚本会设置GIT_DIR一旦它指向不存在的路径任何 git 命令都会报这个错。如果目录确实没初始化那就在项目根目录执行git init或者直接git clone。如果只是子目录git 会自己向上找父目录的.git原理上不需要在子目录里额外 init。5.2 Please tell me who you are完整报错长这样*** Please tell me who you are. Run git config --global user.email youexample.com git config --global user.name Your Name这个错误意味着当前提交的作者身份没配好。很多人第一反应是“我明明配过了”然后陷入困惑。注意这里有两个隐藏坑第一你之前可能只在某一个仓库里配置了 local 身份换个仓库就失效了。local 配置只对本仓库生效新克隆的仓库不会继承。第二你之前配置的是 sudo 身份还是普通用户身份。如果用 root 执行了git config --global配置写在/root/.gitconfig而你自己用普通用户身份提交时读的是/home/你的用户名/.gitconfig两者互不相通。所以看到这个报错先执行whoami确认当前用户再执行echo $HOME确认正在读哪个 home 目录最后看~/.gitconfig是否存在。设好全局身份后这个问题通常就消失了。5.3 中文显示成八进制编码和 diff 全是空格的换行符问题中文显示成\346\265\213\350\257\225直接用前面说的core.quotepath false解决。如果git log里 commit message 的中文显示正常只是文件名不对那基本可以确定就是quotepath问题不是 locale 问题。diff 全红、git status显示大量文件 modified但打开文件看内容完全没变这个场景在跨平台协作的仓库里太常见了。我处理过好几次同事的“灵异事件”最后都是同一个原因文件被 Windows 编辑过行尾变成了 CRLF而 Linux 这边 git 严格区分 CRLF 和 LF。处理步骤也说是排查链路git diff --stat git diff HEAD -- 某个文件 | cat -A第二条命令的cat -A会显示出行尾的符号如果每行结尾是^M$基本可以断定是 CRLF。解决方式是让仓库通过.gitattributes固化规则再执行一次git add --renormalize .把历史文件重新规范化。这是我在实际项目里用过多次的组合拳能一次性清掉大量假修改。6. 配置完怎么自查以及我留下的几个小技巧6.1 自查命令确认配置层级生效配置完成后最怕的是你以为生效了、实际没生效。所以自查这一步不能省。git config --list --show-origin这条命令会列出所有生效配置及其来源路径一眼就能看到哪些来自/etc/gitconfig、哪些来自~/.gitconfig、哪些来自仓库内配置。如果发现某个值和你预期的不一样比如user.email显示的既不是 global 也不是 local而是来自某个奇怪的 system 配置那基本就能定位问题。想只看特定配置项用git config --global --get user.name git config --show-origin --get core.autocrlf这样能确认单项配置的实际值和来源。我再强调一下配置项的查找遵循 local 优先如果在仓库内运行git config --list看到的结果可能和仓库外不一样。这是正常行为不是配置污染。6.2 我的 .gitconfig 实例与注释以下是我个人在 Linux 上常用的~/.gitconfig可以直接参考每一条前面都有注释说明用途[user] name Your Name email youexample.com [core] autocrlf input quotepath false editor vim excludesFile ~/.gitignore_global [init] defaultBranch main [push] default simple autoSetupRemote true [pull] rebase false [alias] co checkout br branch st status cm commit -m amend commit --amend --no-edit lg log --graph --prettyformat:%h %ad %s %d --dateshort unstage restore --staged last log -1 HEAD --stat merge merge --no-ff几个值得解释的点core.excludesFile指向一个全局忽略文件可以在~/.gitignore_global里统一忽略.idea、*.log、*.tmp这类不想进仓库的文件不用每个仓库都写一遍.gitignore。push.default simple是老版本 git 的默认值含义是只推当前分支到同名远程分支符合直觉一般不用改。push.autoSetupRemote true是较新 git 的特性第一次git push时自动创建远程跟踪分支省掉手动git push -u origin main的麻烦。老版本 git 不支持这个选项但从 2.37 起可以放心使用。alias.amend commit --amend --no-edit对应热搜里的git commit --amend场景--no-edit表示修改补进上一次提交但不重开编辑器快速修上次提交的遗漏文件时非常好用。alias.merge merge --no-ff是我个人的习惯保留合并提交记录方便回溯功能合入的时间点和来源。6.3 模板与 hook配置的下一步还能这么玩基础配置做完之后真正拉开体验差距的往往是两个东西提交模板和 hooks。提交模板能改变团队的 commit 质量。先写一个模板文件~/.gitmessage# 标题用一句话说明本次改动 # 正文说明背景、改动内容和影响范围 # 示例 # feat: 新增登录接口的校验逻辑 # 原因是原有接口未校验 token存在越权风险。然后配置git config --global commit.template ~/.gitmessage之后执行git commit时编辑器会自动加载这个模板省得每次从头打规范也不用硬背提交规范。配合后面提的 aliases日常 commit 效率会提升不少。hooks 方面core.hooksPath值得关注git config --global core.hooksPath ~/.git-hooks把团队统一的 pre-commit 脚本放到~/.git-hooks目录下git 会自动执行不需要在每个仓库里复制粘贴。常见的用途包括提交前检查邮箱格式、禁止提交密钥文件、自动跑 lint。这个配置尤其适合给团队统一开发环境的组长一条全局路径解决所有仓库的钩子分发。配置到最后其实你会发现 Linux 上 git 的配置思路没有多玄妙核心就是把身份、换行符、访问通道这三个地基打牢。我自己的使用感受是配置不必贪多但凡是动的每一项都要能说出它影响什么、不设的话会遇到什么问题。user.name、user.email、core.autocrlf、core.quotepath这四个想明白了你再遇到 git 的“灵异事件”时基本能靠逻辑而不是瞎猜去定位。剩下的 alias、模板、hooks都是在稳定地基上的增量优化等用到的时候再顺手加上也不迟。
