Git 2.41.0 安装教程：多平台下载校验、配置与排错指南

1. 锁定 2.41.0：什么场景值得这么干，什么场景纯属折腾

先把结论放在最前面。Git 2.41.0 安装教程这类内容之所以一直有人搜，核心原因并不是这个版本有什么石破天惊的新能力，而是"版本统一"这件事在真实项目里的权重远比大多数人想象的高。我带过的几个外包交付项目，甲方内网镜像里只放了一个版本的 Git 安装包，开发机、构建机、运维跳板机全都要对齐，谁多装了个新版，git fsck出来的 pack 结构差异、钩子脚本的行为差异，都会在联调那天集中爆发。

所以先分清楚你属于哪一类人。

第一类是交付型团队：代码最终要跑在别人的机器上，构建流水线的镜像已经固化了工具链版本，这时候你装 2.41.0 不是为了尝鲜，是为了两边行为一致。这类情况下，版本号本身就是需求的一部分。

第二类是教学与培训场景：课程讲义、实验手册里写的路径、菜单文案、命令输出，全部基于某个确定版本。学生装了最新版，菜单位置一变，"第 5 步勾选 XXX"就对不上了，答疑成本直接翻倍。

第三类是个人开发者跟着最新版走：这类人其实完全没必要专门装 2.41.0，直接拿当前稳定版就行。Git 的向后兼容做得相当克制，老仓库在新版本上几乎不会出问题。

我个人的判断标准很土但很好用：只要你的机器上有任何一台是"别人给的、你不能随便动"的，就锁版本；全都是你自己的，就跟着新版本走。这条规则帮我省掉了至少十几次无意义的排查。

另外要澄清一个常见的误解：Git 的版本号不是"越大功能越多"的线性关系。Git 长期保持着大致每两三个月一个功能版本的节奏，小版本号里塞的东西经常是性能调优、边界修复、以及给大型仓库做的底层改造。你从 2.30 跳到 2.41.0，日常敲的命令基本感觉不到区别，真正能感觉到差异的是超大仓库的status速度、部分克隆和稀疏检出这类偏工程化的能力。所以不要指望装完就"变快"，它的价值更多体现在稳定和一致上。

2. 拿到正确的安装包：三个平台的下载路径与哈希校验

下载这一环最容易出问题，而且出问题的方式很隐蔽：你装上了，命令也能跑，但某个模块缺失，直到半年后要用git lfs才发现压根没装。

2.1 各平台该拿哪个文件

官方发布页会同时挂出源码包和各平台安装包，命名规则相对固定，认准这几类后缀就不会拿错：

Fetch 版本通常还带一个-rc0之类的后缀，那是候选版本，别拿来做正式环境。

2.2 为什么必须做哈希校验

我知道很多人看到"校验哈希"四个字就直接跳过。但下载安装包这件事有三个现实风险：传输中断导致的截断文件、缓存节点返回的旧文件、以及某些公司内网网关对可执行文件的二次包装。这三种情况的表现都是"能装、能用、偶尔诡异"。

校验命令本身很简单，Windows 上用 PowerShell：

Get-FileHash .\Git-2.41.0-64-bit.exe -Algorithm SHA256

macOS 和 Linux 上：

shasum -a 256 git-2.41.0.tar.xz # 或 sha256sum git-2.41.0.tar.xz

把输出和官方的.sha256文件内容比对，一个字符都不能差。注意哈希比对是大小写不敏感的，但长度必须一致；如果长度都不一样，说明你下的是另一个文件。

提示：比对时建议直接把哈希值复制到文本编辑器里逐段核对。我曾经因为肉眼把c和e看混，白折腾了四十分钟重下一次。

2.3 下载慢怎么办

体积大的源码包在跨区域传输时确实会慢。可行的做法是找可信的开源软件镜像站取包，比如各高校和云厂商维护的公共镜像。但这里有个原则：哈希值一定要以官方发布页为准，镜像站只用来加速传输，不用来替代校验。镜像同步有延迟，也可能同步到错误的文件，校验这一关不能省。

如果实在下不动，还可以直接下便携版或者用包管理器，这条路后面会讲。

3. Windows 安装向导 15 屏逐屏拆解

Windows 上的 Git 安装向导是这套流程里信息密度最高的部分，十来个界面里有将近三十个选项，而且每个选项下面都有一小段说明文字，绝大多数人的做法是一路 Next。我把每一屏拆开讲，重点说清楚"为什么这么选"。

3.1 目标目录与组件勾选：哪些必须留

目标目录这一步没什么争议，默认C:\Program Files\Git就好。唯一要注意的是路径里不要出现中文和空格，某些构建脚本在处理带空格的路径时不会加引号，这是经典的踩坑点。

组件选择这一屏才是重头戏，逐项说明：

• Additional icons - On the Desktop / Windows Explorer integration：资源管理器右键菜单里的Git Bash Here和Git GUI Here非常实用，强烈建议保留。不想污染右键菜单的可以取消，但不建议。
• Windows Explorer integration 的 Open Git Bash here：这是我最常用的入口，定位到某个目录右键直接开 Bash，比先开终端再cd快得多。
• Git LFS：如果你不确定要不要，留着。它在安装包里几乎不占空间，但等你某天要拉一个用了大文件存储的仓库时，缺了它就只能重新跑一遍安装程序。
• Associate .gitconfiguration files with the default text editor*：会在安装时把.gitconfig、.gitattributes这类文件关联到默认编辑器，对新手挺友好。
• Associate .sh files to be run with Bash：把.sh文件关联到 Git Bash 执行。这一项要谨慎，它会改变系统对.sh的默认打开方式，如果你机器上还有 WSL 或者别的 Shell 环境，可能会互相抢。我个人倾向取消。
• Use a TrueType font in all console windows：让所有控制台窗口使用 TrueType 字体，解决某些老系统下中文显示成方块的问题，建议保留。
• Check daily for Git for Windows updates：每天检查更新。建议取消。理由和前面锁版本是一个逻辑——你既然专门装了 2.41.0，就不要让它在某个安静的下午自己变成别的版本。
• Add a Git Bash Profile to Windows Terminal：如果你用 Windows Terminal，勾上会多一个一键开 Git Bash 的配置项，很舒服。
• Scalar：微软那套为大仓库做优化的工具集，会作为scalar命令提供。它本身不占什么资源，但普通人一年也用不到一次。勾不勾都行，我一般留着，反正不碍事。

3.2 默认编辑器与初始分支名

默认编辑器这一屏，向导会给出 Nano、Vim、Notepad++、Visual Studio Code、Notepad、WordPad 等选项，还有 Custom。

这里的关键认知是：Git 会在需要你写提交信息、处理合并冲突、编辑 rebase 计划时调用这个编辑器。所以标准只有一个——你顺手就行。

• 完全不熟命令行的，选 Notepad 或者已经装好的 VS Code，最不容易卡住。
• 老手选 Vim 或者 Nano，Nano 在界面底部直接标了快捷键，学习成本最低。
• 选 Custom 的要注意写完整路径，而且路径带空格时必须加引号，否则 Git 会找不到程序。

初始分支名这一屏是 Git 2.28 之后才有的，给了你master、main和自定义三个选项，本质是往init.defaultBranch里写值。这一步建议不看习惯看协作方：你的远程仓库默认分支叫什么，本地就跟着叫什么。本地master远程main，第一次push之后就得手动改上游分支，多出来的这一步没有任何意义。

3.3 PATH 三个选项：为什么我永远选中间那个

这一屏是整套流程里最重要的选择，没有之一。

• 第一项Use Git from Git Bash only：不写 PATH，只能从 Git Bash 里用。如果你的机器上要跑任何脚本、任何 IDE 集成，这一项都会让你后悔。
• 第二项Git from the command line and also from 3rd-party software：把 Git 的可执行文件路径加进系统 PATH，同时把 Bash 相关工具留在 Git 自己的目录里。这是官方推荐项，也是我永远的选择。
• 第三项Use Git and optional Unix tools from the Command Prompt：会把 Git 自带的 Unix 工具（比如find.exe、sort.exe、sort相关的一批）也塞进 PATH。听起来很方便，但这意味着系统的find会被 Git 的版本覆盖，某些依赖系统原生find的老脚本会直接报错。

我见过至少三起"装完 Git 之后某个 Java 构建工具就挂了"的案例，最后定位下来都是手快选了第三项。中间那一项能覆盖 99% 的需求，没必要冒险。

3.4 SSH 与 HTTPS 后端：两屏联动

SSH 这一屏是二选一：用 Git 自带的 OpenSSH，还是用系统上已有的外部 OpenSSH。

判断逻辑很简单。如果你机器上有 Windows 自带的 OpenSSH（Windows 10 1809 之后基本都有），并且你在C:\Users\你的用户名\.ssh\下已经存了密钥，选外部的能直接复用；如果是全新环境、什么都没有，选自带的最省事。怕麻烦就选自带的，你所有配置都会落在 Git 自己的目录里，孤立性好，卸载也干净。

HTTPS 传输后端这一屏，选项是 OpenSSL 库和 Windows 原生安全通道库。

• OpenSSL：跨平台行为一致，和 Linux/macOS 上的表现对齐，证书链的处理方式你也熟悉。
• Windows 原生安全通道：能直接复用系统证书存储里的企业根证书，在装了内部 CA 的公司网络里非常省事。

这一屏的取舍取决于你的网络环境有没有自建的证书体系。没有的话选 OpenSSL，有的话选原生安全通道，能帮你省掉大量证书报错的排查时间。

3.5 换行符、终端模拟器与 pull 行为

换行符这一屏三个选项，是 Git 在 Windows 上最容易出问题的地方，必须讲清楚原委。

Windows 的文本换行是CRLF（回车+换行），Linux 和 macOS 上是LF。Git 如果不管这件事，你从 Linux 仓库拉下来的文件在 Windows 上会被记事本显示成一大坨，反过来你提交的文件在构建机上又会带上多余的\r，导致某些脚本报bad interpreter之类的错。

三个选项：

• Checkout Windows-style, commit Unix-style（对应core.autocrlf=true）：检出时把换行转成CRLF，提交时转回LF。仓库里存的始终是LF，本地编辑器看到的是 Windows 风格。这是 Windows 单机开发的推荐项。
• Checkout as-is, commit Unix-style（对应core.autocrlf=input）：检出不动，提交转LF。适合你在 Windows 上主要编辑的是 Shell 脚本或者 Dockerfile 这类对换行敏感的文件。
• Checkout as-is, commit as-is（对应core.autocrlf=false）：完全不管。只有在团队已经用.gitattributes统一管理了换行、或者仓库里确实存在必须保留CRLF的文件时才选它。

我的建议是第一项，然后立刻在项目根目录加一个.gitattributes做更细粒度的控制，这个后面配置章节会讲。

终端模拟器这一屏，MinTTY 和 Windows 默认控制台二选一。MinTTY 支持窗口自由缩放、支持更多终端特性，但它是自己实现的终端，和某些依赖原生控制台的交互式程序（比如某些需要读取控制台句柄的工具）会打架。Windows 默认控制台兼容性更好但体验差。默认选 MinTTY，遇到具体程序不兼容再单独处理。

git pull默认行为这一屏同样三个选项：默认合并、变基、仅快进。这里不展开讲原理，只说结论——保持默认。理由是你一旦在这里改了全局默认，以后接手别人项目时，git pull的实际行为会和对方的预期不一致，冲突处理方式也会不一样。真要变基，敲命令时显式加参数就够了，别改默认值。

3.6 凭据管理器与最后那几项

凭据管理器这一屏，选项是 Git Credential Manager 和 None。

一定要选 Git Credential Manager。它的作用是把你的仓库账号凭据存进系统的凭据存储里，第一次输入之后就不用再输了。不装的话，每次push都要重新敲一遍账号，如果你开了两步验证，还得每次生成一次临时凭据，那个体验能让人当场放弃命令行。

而且这个组件在 Windows 上还能处理浏览器授权流程，配合主流代码托管平台都挺顺畅。它本身是独立维护的开源组件，卸载 Git 时不会自动清掉，这个后面卸载章节会提。

最后一屏是几个额外选项：

• Enable file system caching：启用文件系统缓存，对大仓库的status、add提速明显。建议保留。代价是极小概率下文件状态读取会有短暂延迟，实践中基本感知不到。
• Enable symbolic links：启用符号链接支持。这一项需要管理员权限，而且 Windows 上创建符号链接本身就要特殊权限，建议先不勾，等确实需要时再回来打开，避免安装时弹权限提示。
• Enable experimental support for pseudo consoles：实验性的伪控制台支持，主要是让 Git Bash 里能正常跑一些需要交互输入的 Windows 原生程序（比如 Python 的交互式解释器、Node 的 REPL）。勾上，实用性很高，出问题的概率很低。

点完 Install 就是等待解压和写注册表，几十秒的事。

4. Linux：包管理器与源码编译两条路怎么选

Linux 上装 Git 有两个思路，选错了会浪费大量时间。

4.1 发行版自带版本够不够用

Debian/Ubuntu 系和 RHEL/CentOS 系都有现成的包：

# Debian / Ubuntu sudo apt update sudo apt install git # RHEL / CentOS / Fedora sudo yum install git # 或 sudo dnf install git

问题在于，发行版仓库里的 Git 版本通常落后官方好几个身位，尤其是那些以稳定为卖点的长期支持发行版。如果你只是要个能用的 Git，装完就完事；如果你必须精确到 2.41.0，包管理器这条路基本走不通。

想查当前能装到哪个版本：

apt-cache policy git # 或 yum info git

输出里会直接列出候选版本号，一目了然。如果候选版本不是你要的，又不想编译，还有第三条路：用第三方维护的新版软件源。这条路能用，但要接受"这个源由谁维护、会不会哪天停止更新"的风险，生产机器上我一般不用。

4.2 从源码编译的完整链路

要精确锁 2.41.0，源码编译是唯一可靠的方式。整个流程分四步。

第一步，装编译依赖。Git 的核心依赖不多，但缺一个都会导致功能缺失：

# Debian / Ubuntu sudo apt install -y build-essential libssl-dev libcurl4-openssl-dev \ libexpat1-dev gettext zlib1g-dev libz-dev libpcre2-dev # RHEL / CentOS sudo yum install -y gcc make curl-devel expat-devel gettext-devel \ openssl-devel zlib-devel perl-devel

这里面几个关键项的作用值得说清楚：libcurl是 HTTPS 传输的基础，缺了它git clone https://...直接不可用；expat负责解析 XML 格式的仓库元数据；gettext提供多语言支持，缺了它 Git 的输出全是原始英文标识符；openssl负责 TLS 握手。

第二步，解压并配置。

tar -xf git-2.41.0.tar.xz cd git-2.41.0 ./configure --prefix=/usr/local --with-openssl --with-curl --with-expat

--prefix=/usr/local把 Git 装到独立目录，不会和系统自带的抢位置，出问题也好回退。如果你希望编译出来的文档也能用，可以加--with-doc，但要额外装asciidoc之类的工具，编译时间会显著变长，服务器上通常不需要。

第三步，编译并安装。

make -j$(nproc) sudo make install

-j$(nproc)让 make 用满所有 CPU 核心，比单线程快好几倍。这台机器如果是虚拟机且只分了一两个核，那就老老实实等着，源码编译十几分钟很正常。

第四步，处理路径冲突。这一步最容易被忽略。系统里原本可能有一个/usr/bin/git，新装的是/usr/local/bin/git，两者谁生效取决于PATH的先后顺序。

which -a git git --version

which -a会列出所有匹配到的 Git，如果顺序不对，就调整PATH，或者直接给编译出来的版本做软链。我强烈建议先which -a看清楚，再动手，盲目创建软链会把系统工具链搞乱。

提示：源码编译的 Git 不会自动获得补全脚本。需要手动把contrib/completion/git-completion.bash复制到 shell 的补全目录，否则你敲git ch按 Tab 什么都不会发生。

5. macOS 上的三种装法对比

macOS 有个特殊之处：系统自带一个 Git，但那个版本通常很老，而且是被 Xcode 命令行工具"借用"的身份存在的。所以第一步是先看看现状：

git --version xcode-select -p

如果git --version能输出，但版本号很老，说明系统那套在生效。三种装法各有适用面。

Homebrew 装法是最主流的：

brew install git

它会装到 Homebrew 自己的前缀目录下（Intel 机器是/usr/local，Apple Silicon 是/opt/homebrew），然后靠PATH顺序覆盖系统版本。装完之后which git应该指向 Homebrew 的路径，如果还指向/usr/bin/git，就去检查 shell 配置文件里的PATH顺序。要注意 Homebrew 默认装的是当前最新版，不保证给你 2.41.0，需要锁版本得去翻它的版本历史，比较折腾。

官方图形安装包是唯一能精确指定版本的方式。下载对应.dmg，双击挂载，运行里面的安装脚本。它会装到/usr/local/git并把链接放到/usr/local/bin，重启终端后PATH里如果有/usr/local/bin就会生效。

Xcode 命令行工具这条路是xcode-select --install，装的是系统配套的版本，版本号完全不受你控制，只适合"我只要有个 Git 能用"的场景。

我自己的做法是：主力用 Homebrew 的，需要精确版本时用官方安装包，并且从不删系统自带的那个。系统自带的 Git 是很多底层工具的依赖，动了它可能引发一堆莫名其妙的报错，收益远小于风险。

6. 装完之后必须先做的几项初始配置

安装程序跑完不等于能干活。下面这几项配置，缺了任何一项都会在你开工之后某一天突然咬你一口。

6.1 身份标识与换行符

第一件事是告诉 Git 你是谁：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

这两个值会写进每一个提交记录，而且是永久留在历史里的。邮箱填错，你会在一堆提交上看到错误的署名，改起来要重写历史，非常麻烦。命令行里区分全局和仓库级靠--global参数，不加就是只对当前仓库生效，这个区别要记牢。

邮箱建议和你托管平台的账号邮箱保持一致，否则提交记录不会和你的账号头像、贡献图关联起来。这算是使用体验上的小事，但强迫症会很难受。

换行符的处理，前面安装向导里选过全局默认值，但更靠谱的方式是在每个项目根目录放一个.gitattributes：

* text=auto *.sh text eol=lf *.bat text eol=crlf *.png binary *.jpg binary *.zip binary

这几行的含义是：默认由 Git 自动判断文本文件并统一为LF；Shell 脚本强制LF，避免在 Linux 上执行时报解释器错误；批处理文件强制CRLF；图片和压缩包明确标记为二进制，禁止任何换行转换。二进制文件被误判为文本是极其严重的问题，转换过程会损坏文件内容，而且损坏是静默的。

6.2 让中文不再乱码

Windows 上装完 Git，git status里中文文件名显示成一堆\344\275\240这样的八进制转义字符，是非常经典的场景。原因是 Git 默认不把非 ASCII 字节序列当作文本对待。

解法是三条命令：

git config --global core.quotepath false git config --global i18n.commitEncoding utf-8 git config --global i18n.logOutputEncoding utf-8

第一条关掉路径的转义输出，中文文件名就能正常显示；后两条分别指定提交信息和日志输出的编码方式。这三条我建议所有中文环境都加上，加上之后终端里看着舒服太多。

如果提交信息里的中文在别人的机器上是乱码，还要检查对方的终端编码，而不是急着改 Git 配置——Windows 老版本控制台的默认代码页不是 UTF-8，改终端的代码页或者换 Windows Terminal 才是正解。

6.3 别名与长路径

Git 的子命令名有些挺长，可以定义别名省事：

git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.lg "log --oneline --graph --decorate --all"

其中lg这个别名最值得配，一行命令就能看到带分支图提交历史的紧凑视图，比默认的log输出直观得多。

Windows 上还有一个必须配的：

git config --global core.longpaths true

Windows 的路径长度历史默认上限是 260 个字符。某些项目（尤其是前端项目）的node_modules嵌套目录，路径长度轻松超过这个限制，症状是clone到一半报"文件名或扩展名太长"。开启长路径支持能解决这个问题，但它需要系统层面也开启对应策略，只在 Git 里配可能不生效。

另外还有一个容易被忽略的：

git config --global core.ignorecase true

macOS 和 Windows 的文件系统默认大小写不敏感，Linux 敏感。这个配置让 Git 在大小写不敏感的系统上少做一些无谓的误判。唯一要小心的是：如果你把Readme.md改名成README.md，在大小写不敏感的系统上 Git 可能认为你什么都没改，这时候要用git mv两步走，先改成临时名再改回目标名。

6.4 凭据保存与全局忽略文件

凭据保存，Windows 上安装时选了 Git Credential Manager 就已经配好了，Linux 和 macOS 需要手动配：

# macOS，用系统钥匙串 git config --global credential.helper osxkeychain # Linux，用缓存方式，默认缓存 15 分钟 git config --global credential.helper cache # 改成缓存一小时 git config --global credential.helper 'cache --timeout=3600' # 想要长期保存，可以用文件方式存储 git config --global credential.helper store

最后那个store会把凭据明文写在用户目录下的.git-credentials文件里。个人机器上问题不大，共享机器、跳板机、CI 环境上绝对不要用，这一点没有商量余地。

还有一个我强烈推荐配的全局忽略文件：

git config --global core.excludesfile ~/.gitignore_global

然后在这个文件里写上各种机器相关的垃圾文件，比如编辑器产生的临时目录、系统生成的元数据文件、编译产物缓存等。这样你就不必在每个项目里都重复添加一遍，也不会因为手一滑把.DS_Store或者Thumbs.db提交进去。

7. 验证安装是否真的成功

"装完了"和"装对了"是两回事。下面这几条命令建议逐条跑一遍，任何一条不符合预期都要回头查。

git --version which -a git git config --list --show-origin git config --global --list

第一条输出必须精确是git version 2.41.0，注意后面可能跟着.windows.1之类的发行方后缀，那是正常的。第二条列出所有生效的 Git 路径，确认排在最前面的就是你要的那个。第三条会显示每个配置项的来源文件，排查"某个配置到底从哪来"的时候极其有用，这是我用得最多的一条排错命令。第四条只列全局配置，确认你刚才写的那些值都进去了。

再补几条功能性验证：

# 测试本地仓库能否正常初始化 mkdir /tmp/git-test && cd /tmp/git-test git init echo "hello" > a.txt git add a.txt git commit -m "test" git log --oneline

这一套跑通，说明核心功能、提交签名、日志输出都正常。如果commit报错说不知道你是谁，说明前面身份配置那一步漏了。

再测一下网络相关的能力，用ls-remote这类只读命令比直接clone轻量得多：

git ls-remote https://github.com/git/git.git HEAD

能输出一串哈希值，说明 HTTPS 传输后端、证书链、DNS 全都是好的。这条命令是判断"网络问题还是 Git 问题"的分水岭，我排错时第一步就是跑它。如果 SSH 方式也要用，再测一条：

ssh -T git@github.com

看到欢迎语就说明密钥配置没问题。注意这个命令返回的退出码可能是非零的，那不代表失败，看输出内容判断。

8. 排查手册：我踩过的那些坑

前面都是"应该怎么做"，这一节讲"做错了会怎样"。这些都是我在真实环境里遇到过的，每一条都花过时间。

8.1 git 不是内部或外部命令

这是最高频的一个。装完了，命令行敲git说找不到。

排查顺序是固定的：先开一个全新的终端窗口再试。安装程序修改的是系统环境变量，已经打开的终端进程用的是它启动时的那份快照，不会自动刷新。这一条能解决一半以上的"装完不能用"。

新窗口还是不行，就检查 PATH。Windows 上在终端里敲：

$env:Path -split ';'

看看里面有没有C:\Program Files\Git\cmd这一条。没有的话，说明安装时 PATH 选的是第一项，需要手动加，或者重跑一次安装程序选第二项。有的话，再确认这个目录下的git.exe是不是真的存在——有时候是因为装到了别的位置，配置里写的却是默认路径。

Linux 上类似，用echo $PATH看/usr/local/bin是否在列表里，且排在/usr/bin前面。

8.2 中文乱码的三种不同表现

中文乱码要分情况，症状不同根因也不同。

表现一：文件名显示成八进制转义。比如\346\226\207\344\273\266.txt。这是core.quotepath的问题，前面 6.2 节的三条命令能解决。

表现二：终端里中文能显示，但日志里是乱码。这是终端编码和 Git 输出编码不匹配。检查i18n.logOutputEncoding，再检查终端的代码页设置。

表现三：提交信息在别人机器上乱码。这是对方终端的问题，不是你的问题。但如果对方用同样的终端看英文提交信息正常，那就得怀疑提交时写进去的编码不对，检查i18n.commitEncoding。

这三种情况我都遇到过，关键是不要一看到乱码就无脑复制三行配置，先看清楚是文件名乱码还是内容乱码，是本地显示问题还是提交记录问题。

8.3 大仓库克隆到一半失败

现象是clone或fetch跑到 80% 左右卡住，然后报传输错误或者超时。大仓库常见。

可调的参数有几个：

git config --global http.postBuffer 524288000 git config --global http.lowSpeedLimit 0 git config --global http.lowSpeedTime 999999

第一条把 HTTP 传输缓冲区调大（单位是字节，这里大约是 500MB）。默认值在某些网络条件下会导致大数据量推送失败，报RPC failed; HTTP 413之类的错。后两条关掉低速连接的中断判断，避免网络抖动导致长时间传输被掐断。

要注意的是，postBuffer调大只是缓解，真正的大仓库更应该用浅克隆：

git clone --depth 1 <仓库地址>

只拉取最近一次提交，速度提升是数量级的。代价是丢失完整历史，需要的时候可以用git fetch --unshallow补齐。浅克隆是应对超大仓库的第一选择，改缓冲区配置是第二选择，很多人顺序搞反了，先去调参数折腾半天。

另外，如果clone反复失败在同一位置，先怀疑本地磁盘空间和路径长度，而不是网络。我遇到过一次是目标目录所在分区只剩几百兆，Git 跑到一半写不下去，报的错误信息却完全是网络相关的，很有误导性。

8.4 图形客户端与命令行版本打架

TortoiseGit、SourceTree、以及各家 IDE 内置的 Git 集成，都会用到 Git 命令行的某一部分。常见问题有两个。

问题一：客户端用的是它自带的 Git，不是你装的那个。TortoiseGit 有独立的设置项指定 Git 可执行文件的路径，默认可能指向它自己打包的版本。如果你专门装了 2.41.0，一定要去客户端设置里把路径指过去，否则你以为在用 2.41.0，实际用的是别的版本，行为差异排查起来非常费劲。

问题二：IDE 报"Git 版本过低"。某些 IDE 的新版本会要求 Git 达到某个最低版本才启用某些功能。2.41.0 在主流 IDE 上不存在这个问题，但如果你装 2.41.0 是因为某个老项目的构建脚本要求，而你的 IDE 又比较新，可能会出现 IDE 抱怨配置项缺失的情况。这时候的做法不是升级 Git，而是在 IDE 设置里关掉对应的实验性集成。

判断到底用的是哪个版本，最可靠的方式是在 IDE 的终端里敲git --version，因为 IDE 内置终端继承的环境变量和它自己调用的环境可能不是同一个。

8.5 卸载重装时的残留清理

Git 装坏了要重装，这一步比想象中麻烦，因为安装目录之外还有好几处残留。

Windows 上需要检查的位置：安装目录本身（默认C:\Program Files\Git）、C:\Program Files\Git LFS、用户目录下的.gitconfig和.git-credentials、系统环境变量 PATH 里手动加过的条目、以及 Git Credential Manager 这个独立组件。最后这个不会跟着 Git 一起卸载，要单独在"应用和功能"里找。

Linux 上源码编译装的，卸载就是sudo make uninstall，但如果你之前改过PATH或者做过软链，那些要手动清掉。包管理器装的用对应的 remove 命令。

用户目录下的.gitconfig我个人建议保留。它只包含你的身份信息和偏好设置，重装之后直接复用，没有任何副作用。删掉反而要重新配一遍。

注意：如果你在.git-credentials里存过明文凭据，卸载前记得手动删掉这个文件，不要让它留在磁盘上。

8.6 一个关于分支名的小麻烦

最后这个坑不算报错，但很烦人。安装时如果初始分支名选了main，而你拉下来的老仓库默认分支是master，第一次push会提示上游分支不存在：

git push -u origin master

加-u参数把上游关联起来就行。如果本地分支名和远程不一致，还要先改名：

git branch -m master main

改完之后远程分支还叫原来的名字，需要重新推送并调整仓库的默认分支设置。这套操作本身不难，但如果团队里有十几台机器各自装成不同的默认值，每次新人进来都要解释一遍，那才是真的麻烦。所以还是那句话：装的时候看一眼协作方的默认分支叫什么，一次选对，永远省事。

我个人在实际操作中的体会是，Git 的安装过程本身十分钟就能搞定，真正花时间的是装完之后那几项配置，以及遇到问题时判断"到底是 Git 的问题还是环境的问题"。前面反复强调的那条命令git ls-remote，以及那条git config --list --show-origin，把这两个用熟，能帮你把绝大多数看起来玄学的问题缩小到一个很具体的范围里。至于版本号，装 2.41.0 也好装更新的也好，只要团队内部统一、并且你清楚自己为什么选它，就没问题。