第10章：常见问题与避坑指南

第10章常见问题与避坑指南本章目标汇总 Git / TortoiseGit 使用中最高频的 30 个问题症状 → 原因 → 解决。建议遇到问题时用CtrlF搜索报错关键字。1. 中文乱码问题1.1 git log / git status 中文显示为八进制\344\275\240原因Git 默认对非 ASCII 字符做转义。解决gitconfig--globalcore.quotepathfalse1.2 git log 提交信息中文乱码gitconfig--globali18n.commitEncoding utf-8gitconfig--globali18n.logOutputEncoding utf-8# 如果是在 Windows 控制台GBK 环境看日志乱码可临时git-ci18n.logOutputEncodinggbk log1.3 TortoiseGit 日志窗口乱码设置 → 常规 → 字体编码相关选项选择 UTF-8 或跟随系统确保系统区域设置不是奇怪的兼容模式2. 换行符问题CRLF/LF2.1 症状每次操作都提示LF will be replaced by CRLF多人协作时整个文件被标记为全部修改其实只差换行符2.2 解决# Windows 推荐配置检出转 CRLF提交转 LFgitconfig--globalcore.autocrlftrue# 或者统一仓库内始终使用 LF跨平台项目推荐配合 .gitattributesgitconfig--globalcore.autocrlf input# 项目级保险.gitattributesecho* textauto.gitattributes[!tip] 已经乱了的文件怎么修gitrm--cached-r.gitreset--hard重新规范化换行符注意reset --hard会丢弃未提交的改动执行前先提交或备份团队协作时需统一操作。3. 认证与网络问题3.1 push 提示 Permission denied (publickey)排查顺序# 1. 确认密钥存在ls~/.ssh# 2. 测试连接分别测两个平台ssh-Tgitgitee.comssh-Tgitgithub.com# 3. 看使用了哪把密钥-v 详细输出ssh-vTgitgithub.com常见原因公钥没粘贴到平台 / 粘贴时丢字符密钥文件权限问题Linux 上常见TortoiseGit 的 SSH 客户端设置与密钥体系不匹配见 第6章TortoiseGit安装与配置#2.6 关键选项SSH 客户端的选择公司网络封 22 端口 → 用 443 端口方案3.2 GitHub 提示 Support for password authentication was removed解决HTTPS 方式必须用Personal Access Token见 第9章提交项目到GitHub#4.2 HTTPS Token 方式不用 SSH 时或改配 SSH。3.3 换账号后仍然推送失败 / 总是旧账号原因Windows 凭据管理器缓存了旧凭据。解决控制面板 → 用户账户 → 凭据管理器 →Windows 凭据找到git:https://github.com或 gitee条目 →删除重新推送输入新账号TortoiseGit 用户也可在设置 → 已保存的凭据 → 清除。3.4 GitHub 推送超时 / 连不上# 给 GitHub 配置代理端口换成你自己代理软件的gitconfig--globalhttp.https://github.com.proxy http://127.0.0.1:7890# 取消gitconfig--global--unsethttp.https://github.com.proxy验证代理是否生效git config --list | findstr proxy4. 推送与拉取问题4.1 推送被拒绝! [rejected] … (non-fast-forward)原因远程有你本地没有的提交通常是别人推了或你在网页上改过。解决# 方案一拉取并变基历史干净推荐gitpull--rebaseorigin maingitpush# 方案二拉取并合并gitpull origin main# 解决可能的冲突后gitpush# 方案三确认远程内容不重要时才用强制推送gitpush --force-with-lease[!warning] 不要无脑 force-f会覆盖别人的提交。确认远程多出来的提交真的可以丢弃时再用。4.2 refusing to merge unrelated histories原因两边历史没有共同祖先典型场景远程建库时勾选了 README本地又git init自己提交。解决gitpull origin main --allow-unrelated-histories# 如有冲突解决后gitpush-uorigin main预防建远程仓库时选不初始化推荐见第8、9章。4.3 git pull 时工作区有改动报错 “Your local changes would be overwritten”解决三选一# 1. 先提交gitadd.gitcommit-m保存当前进度# 2. 先暂存现场拉完再恢复gitstashgitpullgitstash pop# 3. 确认不要了就丢弃危险gitrestore.4.4 src refspec main does not match any原因本地根本没有main分支一次都没提交过或分支名是 master。解决gitadd.gitcommit-mfirst commit# 先制造提交gitbranch-Mmain# 确保分支名gitpush-uorigin main5. 提交与撤销问题5.1 提交信息写错了怎么办# 还没推送gitcommit--amend-m正确的信息# 已推送谨慎团队协作时先沟通gitcommit--amend-m正确信息gitpush --force-with-lease5.2 提交里漏了文件 / 多提交了文件# 漏了加入后 amendgitadd漏掉的文件gitcommit--amend--no-edit# 多了从提交中移除但不删本地文件gitrm--cached多提交的文件gitcommit--amend--no-edit5.3 想撤销最近一次提交场景命令提交没推送想彻底撤销但保留改动git reset --soft HEAD~1提交没推送改动也想重来git reset --mixed HEAD~1默认提交没推送改动也不要了git reset --hard HEAD~1危险提交已推送要安全撤销git revert hash然后 push5.4 误删文件/误 reset如何找回核心工具git refloggitreflog# 找到误操作之前的那条记录如 abc1234 HEAD{3}: commit: xxx# 方式一直接重置回去gitreset--hardabc1234# 方式二先用分支接住确认没问题再处理gitbranch rescue abc1234gitswitch rescue[!tip] 什么能救、什么不能救曾经 commit 过的内容基本都能通过 reflog 找回默认保留 90 天从未被 Git 跟踪过的内容被git clean或手动删除后救不回来只能靠编辑器/系统备份5.5 撤销单个文件的修改gitrestore 文件# 丢弃工作区修改不可恢复gitrestore--staged文件# 仅从暂存区撤出保留修改TortoiseGit右键文件 → 还原Revert/ 在提交窗口取消勾选。5.6 git reset 之后发现搞错了马上git reflog找到 reset 之前的 HEAD 位置再git reset --hard回去。6. .gitignore 相关问题6.1 .gitignore 写了但不起作用原因文件已被跟踪曾经提交过忽略规则不生效。解决gitrm-r--cached.gitadd.gitcommit-mchore: 应用 .gitignoreTortoiseGit右键文件 →Unversion and add to ignore list。6.2 想忽略已提交的文件但保留本地文件gitrm--cached文件echo文件.gitignoregitcommit-mchore: 停止跟踪文件6.3 空文件夹无法提交Git 只跟踪文件不跟踪空文件夹。需要提交空目录时在其中放一个占位文件touch空目录/.gitkeep7. 大文件与仓库体积7.1 推送提示文件超过 100MBGitee/GitHub 单文件上限 100MB解决不提交大文件加进 .gitignore把文件放网盘使用Git LFSgitlfsinstallgitlfs track*.psdgitadd.gitattributesgitadd.gitcommit-mchore: 使用 LFS 管理大文件7.2 已误提交大文件普通删除后仓库还是很大大文件留在历史里git rm只删最新版本。彻底清理需要重写历史较复杂且修改共享历史有风险# 使用 git filter-repo需单独安装或 BFG 工具# 单人仓库也可用gitfilter-branch --tree-filterrm -f 大文件HEAD[!warning] 提示改写历史后必须强推且所有协作者都要重新克隆。个人项目清理前也建议先完整备份一份。8. TortoiseGit 特有问题问题解决右键没有菜单重装勾选 Shell 扩展重启资源管理器任务管理器 → 重启Windows 资源管理器图标不显示/显示错乱图标覆盖数量超限设置 → 图标覆盖 → 调整优先级/排除或卸载冲突软件提示找不到 git.exe设置 → Git → 重新指定C:\Program Files\Git\binSSH 总是认证失败检查 SSH 客户端选择ssh.exe vs TortoiseGitPlink与密钥体系是否匹配提交对话框看不到目标文件检查文件是否被忽略、是否在正确目录每次都要输密码用 Pageant 加载密钥SSH或让凭据管理器保存HTTPS合并工具打不开设置 → 合并工具 → 重新指定 TortoiseGitMerge 路径显示日志很慢大仓库正常可在日志窗口缩小范围只显示当前路径、限制分支9. 操作前保命三原则[!warning] 危险操作黑名单执行前三思git reset --hard丢弃未提交修改git clean -fdx删除未跟踪被忽略的文件不进回收站git push --force覆盖远程历史git rebase公共分支改写别人也在用的历史TortoiseGit 的「Clean up」「Revert」无确认的本地删除保命习惯危险操作前先git status 提交一次或git stash重要项目多远程备份Gitee GitHub见 第9章提交项目到GitHub#7. 一个项目同时推送到 Gitee 和 GitHub进阶拿不准就先别敲回车先搜索报错原文10. 问题速查总表症状关键词对应小节中文乱码、\3441CRLF、LF、换行符2Permission denied、publickey3.1password authentication、Token3.2旧账号、凭据缓存3.3推送超时、代理3.4non-fast-forward、rejected4.1unrelated histories4.2would be overwritten4.3refspec does not match4.4提交信息写错、漏文件5.1撤销提交、reset5.3找回、reflog、误删5.4.gitignore 不生效6.1空文件夹6.3100MB、大文件、LFS7TortoiseGit 菜单/图标/SSH811. 本章小结90% 的事故都能用三招解决看 status、查 reflog、用 stash认证问题分清 HTTPSToken/凭据管理器与 SSH密钥/客户端选择两条线排查推送被拒先 pull 再 push永不无脑强推公共分支.gitignore 不生效 文件已被跟踪先rm --cached危险操作前三思reset --hard、clean -fdx、push -f、rebase 公共分支