TortoiseGit 是 Windows 上最省心的一层 Git 图形外壳装好之后资源管理器右键就能提交、拉取、推送、切分支不用整天对着黑框敲命令。这篇内容我按自己这几年帮同事装环境、排故障的实际流程整理从 Git for Windows 和 TortoiseGit 的安装顺序、版本匹配到 configure git.exe 识别不到、中文包不生效、图标不显示、切分支报错这些高频坑全部给到可复现的步骤和参数。适合刚接手公司代码仓库的新人、习惯图形界面的开发者以及需要给团队批量配环境的人参考如果你已经在命令行里活得很好也能从里面挑到几个提效技巧。1. 先搞清楚这层图形壳的定位再动手1.1 命令行与图形界面各自的分工很多人对 TortoiseGit 有个误解觉得它是一套独立的版本控制工具装了它就不用管 Git 本体。实际情况是TortoiseGit 本身不实现任何仓库逻辑它只是把 git.exe 的能力包装成 Windows 资源管理器里的右键菜单和一串对话框。真正干活的是 Git for Windows也就是官方那个 Git 发行版小乌龟负责的是把命令翻译成点击这件事。理解这层关系之后很多现象就顺了。比如第一次启动 TortoiseGit 时它会弹一个向导让你指定 git.exe 的位置很多人卡在这一步本质就是因为它找不到底层引擎。再比如你在图形界面里点了提交弹出的进度窗口里其实会打印一行行真实执行的命令那串命令你完全可以复制到命令行里复现一遍。我的建议是把两者当成一套组合拳日常的查看日志、对比差异、勾选文件提交、一键切分支用图形界面效率确实高涉及 rebase、cherry-pick、filter-branch 这类复杂操作还是回到命令行更可控。图形界面降低的是入门门槛和日常操作成本不是替你把 Git 的模型学会。1.2 三类人适合用两类场景建议绕开从实际接触的情况看下面这几类人装小乌龟收益最明显。第一类是刚从 SVN 或者纯手工备份迁移过来的团队右键菜单的交互习惯和资源管理器高度贴合学习曲线平滑得多。第二类是经常需要我只想提交改动的这三个文件这种细粒度操作的人图形界面里勾选框比git add -p直观太多。第三类是做代码评审、看历史改动的人Show log 那个窗口的图形化分支线和差异对比读起来比命令行舒服。但有两种场景我建议直接放弃图形界面。一种是需要写脚本做批量自动化比如一次性给几十个仓库打标签、跑钩子命令行加循环才是正解。另一种是在服务器或者没有图形环境的机器上工作小乌龟依赖 Windows 资源管理器进程根本跑不起来。还有个容易被忽略的点小乌龟的某些对话框会阻塞你的操作习惯。比如它默认在提交前会做一些检查习惯命令行的老手可能觉得啰嗦。这些都是可以调的后面配置章节会讲。1.3 装之前先确认你手里的环境动手之前花两分钟确认几件事能省掉后面一半的麻烦。第一确认系统是 64 位还是 32 位安装包必须对应混装会出现右键菜单缺失或者直接报错。第二确认账号有没有本机管理员权限安装程序要写注册表、装 shell 扩展权限不够会出现装完了但右键没有菜单的情况。第三确认机器上是否已经装过旧版 Git 或者旧版小乌龟多版本共存是版本冲突的主要来源。提示如果机器上已经有别人装过的 Git先别急着卸载。打开命令行执行git --version记下版本号再决定是复用还是重装盲目卸载可能把同事配好的凭据和 SSH 配置一起清掉。另外把安装包都下载到本地同一个文件夹里包括 Git 主程序、TortoiseGit 主程序、对应版本的中文语言包。三件套齐了再开始装避免装到一半发现语言包版本对不上又要重新去找。2. 安装顺序和版本匹配是两件不能马虎的事2.1 为什么必须先装 Git for Windows顺序这件事听起来像废话但确实是新手翻车率最高的地方。TortoiseGit 安装向导里有一屏专门让你指定 git.exe 路径如果此时系统里没有 Git这一屏就只能空着跳过装完之后右键菜单是灰的点提交直接弹错误。反过来先装 Git向导大概率能自动探测到路径一路下一步就完事。还有一个更隐蔽的原因TortoiseGit 依赖 Git 的一些附属工具比如用于 SSH 的组件、凭据管理组件、以及做差异对比时的辅助程序。这些组件随 Git for Windows 一起安装单独装小乌龟是拿不到的。你可能会发现自己的 SSH 认证怎么都配不通根源就在这里。所以标准流程固定为Git for Windows → TortoiseGit 主程序 → 中文语言包。中间任何一步失败了不要跳过继续装下一步先解决掉否则问题会叠加排查成本成倍上升。2.2 版本对应关系怎么判断版本匹配的规则很朴素TortoiseGit 主程序版本必须和中文语言包版本完全一致。小乌龟的翻译不是内嵌的而是通过一个独立的语言包安装程序把翻译文件释放到主程序目录主程序再按版本号去加载。版本差一个小号都可能导致语言包装上去但菜单里选不到中文。Git 版本和小乌龟版本之间没有严格的一一绑定但存在兼容下限。小乌龟每个版本发布时都会声明支持的最低 Git 版本太老的 Git 配合太新的小乌龟某些功能会失灵。我的经验是让 Git 保持在一个相对新的稳定版本小乌龟用最近一两个稳定版一般不会出问题。组件版本选择原则常见踩坑点Git for Windows官方稳定版不追 RC版本过旧导致新功能报错TortoiseGit 主程序与语言包同版本装成 32 位、与系统不匹配中文语言包与主程序同版本号版本差一位菜单里没有中文选项系统安装包位数与系统一致64 位系统装了 32 位包菜单缺失2.3 下载和验包的几个细节安装包一律从官方渠道获取不要去各种软件下载站拿绿色版精简版。这类包最常见的问题是被人为裁剪了组件或者夹带了改动过的安装脚本装完之后各种诡异问题你还找不到原因。官方下载页会同时列出主程序、语言包、以及校验信息。拿到文件之后先看文件名里的版本号和位数两段信息。文件名里通常包含类似主版本号加位数标识的结构主程序和语言包这两段必须一模一样只有最后的中文标识部分不同。注意下载下来的 msi 文件如果被浏览器标记过安装时可能提示此程序可能不安全确认来源无误后放行即可不要图省事去点别人转发的网盘链接。3. 手把手走完整个安装流程3.1 Git for Windows 安装时值得留意的选项Git 的安装向导屏数不少大部分人一路下一步也能用但有几个选项值得停一下。第一处是 PATH 环境变量的选择我一般选Git from the command line and also from 3rd-party software这样命令行和图形工具都能同时找到 git 命令。如果选了只有 Git Bash 的选项小乌龟和你的编辑器插件就可能找不到它。第二处是换行符处理。Windows 用 CRLFLinux 和 macOS 用 LF团队协作时这个设置不一致会导致整个文件被标记为改动。默认选项通常够用但如果你的项目里有明确的换行符规范文件建议选Checkout as-is, commit as-is并让项目规范来统一避免 Git 自动转换把二进制文件搞坏。第三处是凭据管理和终端选择。凭据管理默认开启就好它负责把密码安全地存进 Windows 凭据管理器省掉反复输入。终端选默认的 MinTTY 即可这个和小乌龟关系不大。3.2 TortoiseGit 主程序安装逐屏拆解主程序安装向导里第一屏是欢迎和许可协议。第二屏会让你选择要安装的组件这里有两个容易忽略的勾选项一个是命令行工具另一个是 SSH 客户端。命令行工具建议勾上它会在 PATH 里放一些辅助程序SSH 客户端的选择要看你平时用什么方式认证如果团队统一用 OpenSSH就选对应选项如果习惯 PuTTY 那套密钥格式就选 TortoiseGitPlink。后面几屏是安装路径和开始菜单项。安装路径建议保持默认不要装到带中文或空格的目录下某些组件对路径中的非 ASCII 字符处理不好会引发难以定位的失败。装到一半如果杀毒软件弹窗拦截先放行shell 扩展需要注册到系统里被拦截会导致右键菜单不完整。装完之后会提示重启这个重启不是客套。资源管理器的 shell 扩展是在进程启动时加载的不重启的话右键菜单可能显示不出来或者显示成旧的。3.3 首次启动向导和语言包的安装时机第一次右键调出 TortoiseGit 菜单时会弹出一个首次运行向导。这一屏就是前面反复提到的 git.exe 指定页。正常情况下它会自动填好检测到的路径你只需要核对一下目录是否存在。如果它是空的点浏览按钮手动定位到 Git 安装目录下的可执行文件注意这里有两个候选位置具体选哪个后面单独讲。接着向导会让你填写姓名和邮箱这两个值会写进全局配置成为你所有提交记录里的作者信息。填的时候注意别用错别字提交记录一旦推送到远端就很难干净地修改了。向导走完再去装中文语言包。语言包安装程序非常简单基本就是确认一下主程序目录。装完之后需要在设置里手动切换语言具体位置和失效排查下一章展开。4. git.exe 识别不到和中文包不生效的排查路径4.1 configure git.exe 报错的四种成因这个报错我见过太多次成因基本能归到四类。第一类是确实没装 Git先装再回头配。第二类是路径指错了目录Git 安装目录下有多个位置存在类似名字的可执行文件其中一个是给命令行环境用的另一个是给 Bash 环境用的小乌龟需要的是能直接在 Windows 上运行的那个。第三类是被环境变量干扰。有些机器上装了多个 Git 或者 IDE 自带的 GitPATH 里排序靠前的那个是残缺版本小乌龟按 PATH 去找就找错了。这种情况最稳妥的做法是在设置里显式写死绝对路径不要依赖自动探测。第四类是权限问题安装目录在受保护的位置当前用户没有读取权限看起来像文件不存在。排查顺序建议这样先确认git --version在命令行里能正常输出再打开小乌龟的设置页看当前配置的路径是什么然后手动去文件管理器里验证这个路径真实存在。三步下来基本能定位。4.2 中文包装完没有反应怎么办中文包装完却发现菜单还是英文先别急着卸载重装按下面这个顺序查。第一步确认语言包版本号和主程序版本号完全一致差一个数字都不行这是最常见的元凶。第二步确认语言包确实装到了主程序所在的目录有人机器上装了两个版本的小乌龟语言包装到了另一个目录里。第三步去设置里的常规页面检查语言下拉框看里面有没有中文选项。如果没有说明语言包没被识别到如果有但选了没效果多半是资源管理器进程还缓存着旧的资源。第四步重启资源管理器或者干脆重启系统这一步能解决相当一部分明明装了却没生效的情况。提示切换语言后已经打开的对话框不会实时刷新关掉重新打开才会显示新语言这不是安装失败。4.3 一份可以照着走的验证清单装完之后我习惯跑一遍下面的清单确认环境是完整可用的避免用了一段时间才发现某个功能是坏的。命令行执行git --version能输出版本号。右键空白处能看到小乌龟菜单且菜单项不是灰色。打开设置页git.exe 路径显示为绿色或正常状态不是红色警示。设置页里的语言选项能找到中文并切换成功。全局配置里的姓名和邮箱正确无误。在测试目录里初始化一个仓库能成功提交一次并看到日志。资源管理器里能看到文件角标图标如果开了这个功能。5. 用户名密码和密钥的配置方法5.1 全局用户信息的设置与验证姓名和邮箱这套信息在首次向导里填过但很多人是在多个仓库、多台机器之间切换需要回头改。图形界面里可以在设置页的 Git 配置区域编辑也可以直接在命令行执行全局配置命令两边是同一份数据改哪边都一样。git config --global user.name Your Name git config --global user.email youexample.com git config --global --list验证的时候看输出里有没有这两项值是否正确。这里有个容易忽略的点项目级别的配置会覆盖全局配置如果你在某个仓库里发现提交作者不对先检查那个仓库自己的配置文件而不是怀疑全局设置。还有一类场景是同一台机器上要区分工作身份和个人身份。全局只放一个另一个通过每个仓库单独设置或者用条件包含的写法按目录自动切换。这属于进阶用法新手先用全局等真的有需要再折腾。5.2 为什么每次都让我输密码密码反复弹窗的原因通常是凭据没有被正确存储。Git 有专门的凭据管理机制配合 Windows 凭据管理器保存账号密码。检查方法是打开系统的凭据管理器看里面有没有对应托管平台的条目。如果每次都要输入说明保存环节没走通。可能的原因有几个一是 Git 安装时没勾选凭据管理组件二是配置里把凭据辅助程序关了三是远端地址用的是 HTTP 而不是 SSH同时平台开启了两步验证密码字段需要填的是访问令牌而不是登录密码。最后这条特别常见很多人卡在这里以为是软件坏了。用 SSH 方式可以绕开这个循环。密钥认证一旦配好后续操作全程无感这也是我更推荐团队统一用 SSH 的原因之一。5.3 生成密钥并配置到远端TortoiseGit 自带一个密钥生成工具也可以在命令行用 OpenSSH 的工具生成。两者格式不同选哪种取决于你安装时选的 SSH 客户端类型。下面是命令行方式的流程。ssh-keygen -t ed25519 -C youexample.com # 一路回车默认保存在用户目录的 .ssh 下 # 然后把公钥内容复制出来 cat ~/.ssh/id_ed25519.pub生成出来的公钥需要粘贴到代码托管平台的个人设置里。私钥文件绝对不能外传也不要提交到任何仓库里。配好之后用下面的命令验证连通性第一次连接会提示确认主机指纹输入 yes 即可。ssh -T gityour-host如果用的是 PuTTY 那套格式就在小乌龟自带的工具里生成生成后需要把公钥导出成 OpenSSH 格式再上传因为多数平台只认这个格式。这一步格式转换很多人会漏导致上传上去的密钥验证失败。6. 日常最高频的几组操作6.1 右键菜单里真正好用的那几个入口菜单项看着多实际天天用的就那么几个。在仓库目录里右键第一组是提交、更新、推送这几个动作对应命令行里的 addcommit、pull、push。第二组是显示日志这是查历史的主入口。第三组是设置和帮助。在单个文件上右键菜单会多出对比、回退、查看修改记录这些针对文件的操作。工作流上我一般这么走先拉取远端最新再看状态确认本地改了什么勾选要提交的文件写清楚提交信息提交完立刻推送。这个顺序能避免大部分提交历史分叉反复合并的麻烦。刚开始用的人容易漏掉推送这一步以为提交了就同步了其实只是写到本地仓库。注意提交和推送是两个动作中间隔着本地仓库这一层。理解这一点很多关于我的代码怎么没上去的疑问就自动解开了。6.2 切换分支的正确姿势和报错处理切换分支在小乌龟里叫 Switch/Checkout在右键菜单里能找到。这个功能用得最多也最容易报错。最常见的报错是提示本地改动会被覆盖原因是你有未提交的修改而这些文件在目标分支上的内容不一样切换过去就会丢失改动所以 Git 主动拦住了。处理方式有三种把改动提交掉、把改动暂存起来、或者把改动丢弃。暂存是图形界面里最好用的一个功能能把当前工作区的修改临时存起来切换分支处理完事情再恢复回来。命令行里对应 stash 那套命令小乌龟把它做成了菜单项和对话框勾选一下就行。切换之前还有一个习惯值得养成先看当前分支有没有落后于远端如果落后很多先拉取再切能避免一些莫名其妙的冲突。另外新建分支和切换分支是两个动作小乌龟的对话框里把它们放在同一个界面处理勾选新建选项并填好名字就行顺带还能勾上切换后跟踪远端分支。6.3 合并冲突的处理流程合并冲突是绕不开的。触发方式通常是先拉取或者合并另一个分支如果同一个文件的同一区域两边都改过就会冲突。小乌龟会列出冲突文件并且给每个文件提供编辑冲突的入口打开的是它自带的合并工具三个窗格分别是本地、远端和合并结果。处理思路是逐个冲突块决定保留哪边或者两边都保留后手工调整改完保存并标记为已解决全部处理完再提交。最容易犯的错误是直接删掉冲突标记就提交代码里残留的那些尖括号标记如果没清理干净编译直接失败。所以提交前一定要全文搜一遍冲突标记符号。git diff --check # 快速检查有没有遗留的冲突标记和空白错误如果冲突处理到一半想放弃回到冲突前的状态可以在日志里找到合并前的那次提交做一次重置操作。重置有三种模式软重置保留改动混合重置保留工作区改动但清空暂存硬重置全部丢弃。硬重置会真的丢数据操作前确认清楚。6.4 日志窗口和撤销相关操作日志窗口是被低估的功能。它能图形化展示提交历史看分支线、合并点、标签还能直接在某次提交上右键做各种操作回退到这次提交、从这次提交新建分支、对比两次提交的差异、查看某个文件在历史中的演变。排查这行代码是谁什么时候改的这类问题时比在命令行里翻 blame 快得多。这里说一个反直觉的点撤销在 Git 里不是单一动作。想改最后一次提交的说明是修改提交想撤掉多次提交但保留改动是重置想撤销某次提交引入的改动但保留历史是反向应用那个提交。小乌龟把这些都放进了菜单但你需要先想清楚目标是哪种选错模式可能把提交历史搞乱。我个人建议涉及已推送到远端的历史尽量别做重置用新增提交去修正这样团队的其他人不需要处理历史重写的麻烦。7. 常见问题速查和几条踩坑经验整理一份速查表遇到问题先按现象对号入座能省不少搜索时间。现象常见原因处理方向右键没有小乌龟菜单未重启资源管理器、安装被拦截、位数不匹配重启系统、检查安装日志、重装对应位数包提示找不到 git.exe未装 Git、路径指向错误目录、PATH 被其他版本污染手动指定绝对路径菜单全是英文语言包版本不匹配、未切换语言、资源管理器缓存对齐版本号、设置里切换、重启文件角标图标不显示系统覆盖图标数量超限、被其他同步软件抢占调整注册表项排序、减少同步软件拉取时反复弹密码框凭据未保存、HTTP 远端加两步验证检查凭据管理器、改用 SSH 或访问令牌切换分支被拒绝存在未提交改动提交、暂存或丢弃改动后再切提交时提示行尾符变更换行符配置不一致统一配置或加入忽略规则关于文件角标不显示这里展开说一下因为这是新手最容易困惑、又最难搜到答案的问题。Windows 的图标覆盖机制有个硬性上限系统只允许注册有限数量的覆盖图标处理器而且按注册表键名的字母顺序决定优先级。很多同步网盘、压缩工具都会抢占名额。解决办法是打开注册表编辑器找到图标覆盖处理器的注册位置把 TortoiseGit 相关项的键名前面加上空格空格在排序上靠前这样它就能排进可用名额里。注意动注册表之前先导出备份。改完需要重启资源管理器才能生效如果操作后图标完全不显示了用备份还原回去即可。最后几条纯经验的东西。第一不要把仓库建在同步网盘的目录里网盘会在后台改文件时间戳和加锁Git 会误判大量文件被修改甚至把索引搞坏。第二仓库路径尽量短、尽量用英文深层嵌套的长路径在 Windows 上容易碰到路径长度限制。第三提交信息别偷懒写更新修改三个月后你自己都看不懂。第四刚开始用的时候在本地建个练习仓库把各种操作都点一遍别直接拿公司仓库练手有些操作真的会丢数据。装环境这件事本身不难难的是版本匹配和几个隐藏的配置点。把 Git 装对、语言包版本对齐、git.exe 路径写死后面的使用过程基本就顺了。真遇到问题先看小乌龟设置页里的状态提示再去日志窗口看它实际执行了什么命令比到处搜答案快得多。
TortoiseGit 安装配置与故障排查：版本匹配、中文包、git.exe
TortoiseGit 是 Windows 上最省心的一层 Git 图形外壳装好之后资源管理器右键就能提交、拉取、推送、切分支不用整天对着黑框敲命令。这篇内容我按自己这几年帮同事装环境、排故障的实际流程整理从 Git for Windows 和 TortoiseGit 的安装顺序、版本匹配到 configure git.exe 识别不到、中文包不生效、图标不显示、切分支报错这些高频坑全部给到可复现的步骤和参数。适合刚接手公司代码仓库的新人、习惯图形界面的开发者以及需要给团队批量配环境的人参考如果你已经在命令行里活得很好也能从里面挑到几个提效技巧。1. 先搞清楚这层图形壳的定位再动手1.1 命令行与图形界面各自的分工很多人对 TortoiseGit 有个误解觉得它是一套独立的版本控制工具装了它就不用管 Git 本体。实际情况是TortoiseGit 本身不实现任何仓库逻辑它只是把 git.exe 的能力包装成 Windows 资源管理器里的右键菜单和一串对话框。真正干活的是 Git for Windows也就是官方那个 Git 发行版小乌龟负责的是把命令翻译成点击这件事。理解这层关系之后很多现象就顺了。比如第一次启动 TortoiseGit 时它会弹一个向导让你指定 git.exe 的位置很多人卡在这一步本质就是因为它找不到底层引擎。再比如你在图形界面里点了提交弹出的进度窗口里其实会打印一行行真实执行的命令那串命令你完全可以复制到命令行里复现一遍。我的建议是把两者当成一套组合拳日常的查看日志、对比差异、勾选文件提交、一键切分支用图形界面效率确实高涉及 rebase、cherry-pick、filter-branch 这类复杂操作还是回到命令行更可控。图形界面降低的是入门门槛和日常操作成本不是替你把 Git 的模型学会。1.2 三类人适合用两类场景建议绕开从实际接触的情况看下面这几类人装小乌龟收益最明显。第一类是刚从 SVN 或者纯手工备份迁移过来的团队右键菜单的交互习惯和资源管理器高度贴合学习曲线平滑得多。第二类是经常需要我只想提交改动的这三个文件这种细粒度操作的人图形界面里勾选框比git add -p直观太多。第三类是做代码评审、看历史改动的人Show log 那个窗口的图形化分支线和差异对比读起来比命令行舒服。但有两种场景我建议直接放弃图形界面。一种是需要写脚本做批量自动化比如一次性给几十个仓库打标签、跑钩子命令行加循环才是正解。另一种是在服务器或者没有图形环境的机器上工作小乌龟依赖 Windows 资源管理器进程根本跑不起来。还有个容易被忽略的点小乌龟的某些对话框会阻塞你的操作习惯。比如它默认在提交前会做一些检查习惯命令行的老手可能觉得啰嗦。这些都是可以调的后面配置章节会讲。1.3 装之前先确认你手里的环境动手之前花两分钟确认几件事能省掉后面一半的麻烦。第一确认系统是 64 位还是 32 位安装包必须对应混装会出现右键菜单缺失或者直接报错。第二确认账号有没有本机管理员权限安装程序要写注册表、装 shell 扩展权限不够会出现装完了但右键没有菜单的情况。第三确认机器上是否已经装过旧版 Git 或者旧版小乌龟多版本共存是版本冲突的主要来源。提示如果机器上已经有别人装过的 Git先别急着卸载。打开命令行执行git --version记下版本号再决定是复用还是重装盲目卸载可能把同事配好的凭据和 SSH 配置一起清掉。另外把安装包都下载到本地同一个文件夹里包括 Git 主程序、TortoiseGit 主程序、对应版本的中文语言包。三件套齐了再开始装避免装到一半发现语言包版本对不上又要重新去找。2. 安装顺序和版本匹配是两件不能马虎的事2.1 为什么必须先装 Git for Windows顺序这件事听起来像废话但确实是新手翻车率最高的地方。TortoiseGit 安装向导里有一屏专门让你指定 git.exe 路径如果此时系统里没有 Git这一屏就只能空着跳过装完之后右键菜单是灰的点提交直接弹错误。反过来先装 Git向导大概率能自动探测到路径一路下一步就完事。还有一个更隐蔽的原因TortoiseGit 依赖 Git 的一些附属工具比如用于 SSH 的组件、凭据管理组件、以及做差异对比时的辅助程序。这些组件随 Git for Windows 一起安装单独装小乌龟是拿不到的。你可能会发现自己的 SSH 认证怎么都配不通根源就在这里。所以标准流程固定为Git for Windows → TortoiseGit 主程序 → 中文语言包。中间任何一步失败了不要跳过继续装下一步先解决掉否则问题会叠加排查成本成倍上升。2.2 版本对应关系怎么判断版本匹配的规则很朴素TortoiseGit 主程序版本必须和中文语言包版本完全一致。小乌龟的翻译不是内嵌的而是通过一个独立的语言包安装程序把翻译文件释放到主程序目录主程序再按版本号去加载。版本差一个小号都可能导致语言包装上去但菜单里选不到中文。Git 版本和小乌龟版本之间没有严格的一一绑定但存在兼容下限。小乌龟每个版本发布时都会声明支持的最低 Git 版本太老的 Git 配合太新的小乌龟某些功能会失灵。我的经验是让 Git 保持在一个相对新的稳定版本小乌龟用最近一两个稳定版一般不会出问题。组件版本选择原则常见踩坑点Git for Windows官方稳定版不追 RC版本过旧导致新功能报错TortoiseGit 主程序与语言包同版本装成 32 位、与系统不匹配中文语言包与主程序同版本号版本差一位菜单里没有中文选项系统安装包位数与系统一致64 位系统装了 32 位包菜单缺失2.3 下载和验包的几个细节安装包一律从官方渠道获取不要去各种软件下载站拿绿色版精简版。这类包最常见的问题是被人为裁剪了组件或者夹带了改动过的安装脚本装完之后各种诡异问题你还找不到原因。官方下载页会同时列出主程序、语言包、以及校验信息。拿到文件之后先看文件名里的版本号和位数两段信息。文件名里通常包含类似主版本号加位数标识的结构主程序和语言包这两段必须一模一样只有最后的中文标识部分不同。注意下载下来的 msi 文件如果被浏览器标记过安装时可能提示此程序可能不安全确认来源无误后放行即可不要图省事去点别人转发的网盘链接。3. 手把手走完整个安装流程3.1 Git for Windows 安装时值得留意的选项Git 的安装向导屏数不少大部分人一路下一步也能用但有几个选项值得停一下。第一处是 PATH 环境变量的选择我一般选Git from the command line and also from 3rd-party software这样命令行和图形工具都能同时找到 git 命令。如果选了只有 Git Bash 的选项小乌龟和你的编辑器插件就可能找不到它。第二处是换行符处理。Windows 用 CRLFLinux 和 macOS 用 LF团队协作时这个设置不一致会导致整个文件被标记为改动。默认选项通常够用但如果你的项目里有明确的换行符规范文件建议选Checkout as-is, commit as-is并让项目规范来统一避免 Git 自动转换把二进制文件搞坏。第三处是凭据管理和终端选择。凭据管理默认开启就好它负责把密码安全地存进 Windows 凭据管理器省掉反复输入。终端选默认的 MinTTY 即可这个和小乌龟关系不大。3.2 TortoiseGit 主程序安装逐屏拆解主程序安装向导里第一屏是欢迎和许可协议。第二屏会让你选择要安装的组件这里有两个容易忽略的勾选项一个是命令行工具另一个是 SSH 客户端。命令行工具建议勾上它会在 PATH 里放一些辅助程序SSH 客户端的选择要看你平时用什么方式认证如果团队统一用 OpenSSH就选对应选项如果习惯 PuTTY 那套密钥格式就选 TortoiseGitPlink。后面几屏是安装路径和开始菜单项。安装路径建议保持默认不要装到带中文或空格的目录下某些组件对路径中的非 ASCII 字符处理不好会引发难以定位的失败。装到一半如果杀毒软件弹窗拦截先放行shell 扩展需要注册到系统里被拦截会导致右键菜单不完整。装完之后会提示重启这个重启不是客套。资源管理器的 shell 扩展是在进程启动时加载的不重启的话右键菜单可能显示不出来或者显示成旧的。3.3 首次启动向导和语言包的安装时机第一次右键调出 TortoiseGit 菜单时会弹出一个首次运行向导。这一屏就是前面反复提到的 git.exe 指定页。正常情况下它会自动填好检测到的路径你只需要核对一下目录是否存在。如果它是空的点浏览按钮手动定位到 Git 安装目录下的可执行文件注意这里有两个候选位置具体选哪个后面单独讲。接着向导会让你填写姓名和邮箱这两个值会写进全局配置成为你所有提交记录里的作者信息。填的时候注意别用错别字提交记录一旦推送到远端就很难干净地修改了。向导走完再去装中文语言包。语言包安装程序非常简单基本就是确认一下主程序目录。装完之后需要在设置里手动切换语言具体位置和失效排查下一章展开。4. git.exe 识别不到和中文包不生效的排查路径4.1 configure git.exe 报错的四种成因这个报错我见过太多次成因基本能归到四类。第一类是确实没装 Git先装再回头配。第二类是路径指错了目录Git 安装目录下有多个位置存在类似名字的可执行文件其中一个是给命令行环境用的另一个是给 Bash 环境用的小乌龟需要的是能直接在 Windows 上运行的那个。第三类是被环境变量干扰。有些机器上装了多个 Git 或者 IDE 自带的 GitPATH 里排序靠前的那个是残缺版本小乌龟按 PATH 去找就找错了。这种情况最稳妥的做法是在设置里显式写死绝对路径不要依赖自动探测。第四类是权限问题安装目录在受保护的位置当前用户没有读取权限看起来像文件不存在。排查顺序建议这样先确认git --version在命令行里能正常输出再打开小乌龟的设置页看当前配置的路径是什么然后手动去文件管理器里验证这个路径真实存在。三步下来基本能定位。4.2 中文包装完没有反应怎么办中文包装完却发现菜单还是英文先别急着卸载重装按下面这个顺序查。第一步确认语言包版本号和主程序版本号完全一致差一个数字都不行这是最常见的元凶。第二步确认语言包确实装到了主程序所在的目录有人机器上装了两个版本的小乌龟语言包装到了另一个目录里。第三步去设置里的常规页面检查语言下拉框看里面有没有中文选项。如果没有说明语言包没被识别到如果有但选了没效果多半是资源管理器进程还缓存着旧的资源。第四步重启资源管理器或者干脆重启系统这一步能解决相当一部分明明装了却没生效的情况。提示切换语言后已经打开的对话框不会实时刷新关掉重新打开才会显示新语言这不是安装失败。4.3 一份可以照着走的验证清单装完之后我习惯跑一遍下面的清单确认环境是完整可用的避免用了一段时间才发现某个功能是坏的。命令行执行git --version能输出版本号。右键空白处能看到小乌龟菜单且菜单项不是灰色。打开设置页git.exe 路径显示为绿色或正常状态不是红色警示。设置页里的语言选项能找到中文并切换成功。全局配置里的姓名和邮箱正确无误。在测试目录里初始化一个仓库能成功提交一次并看到日志。资源管理器里能看到文件角标图标如果开了这个功能。5. 用户名密码和密钥的配置方法5.1 全局用户信息的设置与验证姓名和邮箱这套信息在首次向导里填过但很多人是在多个仓库、多台机器之间切换需要回头改。图形界面里可以在设置页的 Git 配置区域编辑也可以直接在命令行执行全局配置命令两边是同一份数据改哪边都一样。git config --global user.name Your Name git config --global user.email youexample.com git config --global --list验证的时候看输出里有没有这两项值是否正确。这里有个容易忽略的点项目级别的配置会覆盖全局配置如果你在某个仓库里发现提交作者不对先检查那个仓库自己的配置文件而不是怀疑全局设置。还有一类场景是同一台机器上要区分工作身份和个人身份。全局只放一个另一个通过每个仓库单独设置或者用条件包含的写法按目录自动切换。这属于进阶用法新手先用全局等真的有需要再折腾。5.2 为什么每次都让我输密码密码反复弹窗的原因通常是凭据没有被正确存储。Git 有专门的凭据管理机制配合 Windows 凭据管理器保存账号密码。检查方法是打开系统的凭据管理器看里面有没有对应托管平台的条目。如果每次都要输入说明保存环节没走通。可能的原因有几个一是 Git 安装时没勾选凭据管理组件二是配置里把凭据辅助程序关了三是远端地址用的是 HTTP 而不是 SSH同时平台开启了两步验证密码字段需要填的是访问令牌而不是登录密码。最后这条特别常见很多人卡在这里以为是软件坏了。用 SSH 方式可以绕开这个循环。密钥认证一旦配好后续操作全程无感这也是我更推荐团队统一用 SSH 的原因之一。5.3 生成密钥并配置到远端TortoiseGit 自带一个密钥生成工具也可以在命令行用 OpenSSH 的工具生成。两者格式不同选哪种取决于你安装时选的 SSH 客户端类型。下面是命令行方式的流程。ssh-keygen -t ed25519 -C youexample.com # 一路回车默认保存在用户目录的 .ssh 下 # 然后把公钥内容复制出来 cat ~/.ssh/id_ed25519.pub生成出来的公钥需要粘贴到代码托管平台的个人设置里。私钥文件绝对不能外传也不要提交到任何仓库里。配好之后用下面的命令验证连通性第一次连接会提示确认主机指纹输入 yes 即可。ssh -T gityour-host如果用的是 PuTTY 那套格式就在小乌龟自带的工具里生成生成后需要把公钥导出成 OpenSSH 格式再上传因为多数平台只认这个格式。这一步格式转换很多人会漏导致上传上去的密钥验证失败。6. 日常最高频的几组操作6.1 右键菜单里真正好用的那几个入口菜单项看着多实际天天用的就那么几个。在仓库目录里右键第一组是提交、更新、推送这几个动作对应命令行里的 addcommit、pull、push。第二组是显示日志这是查历史的主入口。第三组是设置和帮助。在单个文件上右键菜单会多出对比、回退、查看修改记录这些针对文件的操作。工作流上我一般这么走先拉取远端最新再看状态确认本地改了什么勾选要提交的文件写清楚提交信息提交完立刻推送。这个顺序能避免大部分提交历史分叉反复合并的麻烦。刚开始用的人容易漏掉推送这一步以为提交了就同步了其实只是写到本地仓库。注意提交和推送是两个动作中间隔着本地仓库这一层。理解这一点很多关于我的代码怎么没上去的疑问就自动解开了。6.2 切换分支的正确姿势和报错处理切换分支在小乌龟里叫 Switch/Checkout在右键菜单里能找到。这个功能用得最多也最容易报错。最常见的报错是提示本地改动会被覆盖原因是你有未提交的修改而这些文件在目标分支上的内容不一样切换过去就会丢失改动所以 Git 主动拦住了。处理方式有三种把改动提交掉、把改动暂存起来、或者把改动丢弃。暂存是图形界面里最好用的一个功能能把当前工作区的修改临时存起来切换分支处理完事情再恢复回来。命令行里对应 stash 那套命令小乌龟把它做成了菜单项和对话框勾选一下就行。切换之前还有一个习惯值得养成先看当前分支有没有落后于远端如果落后很多先拉取再切能避免一些莫名其妙的冲突。另外新建分支和切换分支是两个动作小乌龟的对话框里把它们放在同一个界面处理勾选新建选项并填好名字就行顺带还能勾上切换后跟踪远端分支。6.3 合并冲突的处理流程合并冲突是绕不开的。触发方式通常是先拉取或者合并另一个分支如果同一个文件的同一区域两边都改过就会冲突。小乌龟会列出冲突文件并且给每个文件提供编辑冲突的入口打开的是它自带的合并工具三个窗格分别是本地、远端和合并结果。处理思路是逐个冲突块决定保留哪边或者两边都保留后手工调整改完保存并标记为已解决全部处理完再提交。最容易犯的错误是直接删掉冲突标记就提交代码里残留的那些尖括号标记如果没清理干净编译直接失败。所以提交前一定要全文搜一遍冲突标记符号。git diff --check # 快速检查有没有遗留的冲突标记和空白错误如果冲突处理到一半想放弃回到冲突前的状态可以在日志里找到合并前的那次提交做一次重置操作。重置有三种模式软重置保留改动混合重置保留工作区改动但清空暂存硬重置全部丢弃。硬重置会真的丢数据操作前确认清楚。6.4 日志窗口和撤销相关操作日志窗口是被低估的功能。它能图形化展示提交历史看分支线、合并点、标签还能直接在某次提交上右键做各种操作回退到这次提交、从这次提交新建分支、对比两次提交的差异、查看某个文件在历史中的演变。排查这行代码是谁什么时候改的这类问题时比在命令行里翻 blame 快得多。这里说一个反直觉的点撤销在 Git 里不是单一动作。想改最后一次提交的说明是修改提交想撤掉多次提交但保留改动是重置想撤销某次提交引入的改动但保留历史是反向应用那个提交。小乌龟把这些都放进了菜单但你需要先想清楚目标是哪种选错模式可能把提交历史搞乱。我个人建议涉及已推送到远端的历史尽量别做重置用新增提交去修正这样团队的其他人不需要处理历史重写的麻烦。7. 常见问题速查和几条踩坑经验整理一份速查表遇到问题先按现象对号入座能省不少搜索时间。现象常见原因处理方向右键没有小乌龟菜单未重启资源管理器、安装被拦截、位数不匹配重启系统、检查安装日志、重装对应位数包提示找不到 git.exe未装 Git、路径指向错误目录、PATH 被其他版本污染手动指定绝对路径菜单全是英文语言包版本不匹配、未切换语言、资源管理器缓存对齐版本号、设置里切换、重启文件角标图标不显示系统覆盖图标数量超限、被其他同步软件抢占调整注册表项排序、减少同步软件拉取时反复弹密码框凭据未保存、HTTP 远端加两步验证检查凭据管理器、改用 SSH 或访问令牌切换分支被拒绝存在未提交改动提交、暂存或丢弃改动后再切提交时提示行尾符变更换行符配置不一致统一配置或加入忽略规则关于文件角标不显示这里展开说一下因为这是新手最容易困惑、又最难搜到答案的问题。Windows 的图标覆盖机制有个硬性上限系统只允许注册有限数量的覆盖图标处理器而且按注册表键名的字母顺序决定优先级。很多同步网盘、压缩工具都会抢占名额。解决办法是打开注册表编辑器找到图标覆盖处理器的注册位置把 TortoiseGit 相关项的键名前面加上空格空格在排序上靠前这样它就能排进可用名额里。注意动注册表之前先导出备份。改完需要重启资源管理器才能生效如果操作后图标完全不显示了用备份还原回去即可。最后几条纯经验的东西。第一不要把仓库建在同步网盘的目录里网盘会在后台改文件时间戳和加锁Git 会误判大量文件被修改甚至把索引搞坏。第二仓库路径尽量短、尽量用英文深层嵌套的长路径在 Windows 上容易碰到路径长度限制。第三提交信息别偷懒写更新修改三个月后你自己都看不懂。第四刚开始用的时候在本地建个练习仓库把各种操作都点一遍别直接拿公司仓库练手有些操作真的会丢数据。装环境这件事本身不难难的是版本匹配和几个隐藏的配置点。把 Git 装对、语言包版本对齐、git.exe 路径写死后面的使用过程基本就顺了。真遇到问题先看小乌龟设置页里的状态提示再去日志窗口看它实际执行了什么命令比到处搜答案快得多。
