GitGutter正常显示标记的前提是Sublime能调用git命令且文件属于已初始化的Git仓库（根目录含.git）；安装后无反应需先确认Package Control有效、git_binary路径正确并重启，状态栏显示分支名才表示配置成功。
GitGutter 能正常显示修改标记的前提很明确：Sublime 必须能调用 git 命令，且当前文件必须属于一个已初始化的 Git 仓库（即项目根目录下存在 .git 文件夹），否则它压根不会启动 diff 检测逻辑。
GitGutter 安装后没反应？先查 Package Control 和 git_binary
很多人卡在“装了但没图标”，根本不是插件问题，而是底层依赖断了。
- 按
Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS）调出命令面板，输入Package Control: Install Package—— 如果没响应，说明 Package Control 没装好或失效，得重装 - 确认系统终端能执行
git --version；如果不行，Git 没装或没进 PATH，Sublime 就找不到它 - 在
Preferences → Package Settings → GitGutter → Settings中检查"git_binary"：Windows 常见路径是"C:\Program Files\Git\bin\git.exe"，macOS 可能是"/usr/local/bin/git"；改完必须完全退出 Sublime 再重启，否则配置不加载 - 重启后看状态栏右下角是否出现分支名（如
main）；没有就说明git_binary还是错的，可按Ctrl+`打开控制台，搜GitGutter: git not found
为什么新增/删除文件没图标，只有修改行有波浪线？
这是 GitGutter 的设计行为，不是 bug。它默认只对比工作区（working tree）和暂存区（index），而新文件、删除文件若未被 git add 或 git rm，就处于“未跟踪”状态，不在 index 里，自然不标记。
- 运行
git add .后，新增文件会显示+图标 - 执行
git rm <file>后，删除文件才显示- - 想让未跟踪文件也标出来？不行。GitGutter 不支持该模式，它严格遵循 Git 的三棵树模型
- 误删文件但还没
git rm？GitGutter 不会提示，得靠git status或 AYGIT 插件辅助
图标显示错位、空白、全灰？别乱改 gutter_size，先换主题
图标渲染失败，90% 是主题不兼容。GitGutter 依赖 Sublime 主题中定义的 gutter 区域样式，很多自定义主题压根没适配它的 scope（比如 markup.inserted.git_gutter）。
- 先禁用所有其他 gutter 类插件（如
BracketHighlighter、SublimeLinter），排除冲突 - 菜单 →
Preferences → Theme → Default.sublime-theme，切回默认主题看是否恢复 - 若恢复了，说明你当前主题缺资源；可临时用
"gutter_theme": "Default"强制指定，但更稳妥的是在主题文件里补全对应 scope 样式 - 别碰
gutter_size或gutter_padding—— Sublime Text 5+ 已移除这些参数，设了也没用
Windows 中文路径报 fatal: not a git repository 怎么办？
这是 Windows 下 Git 版本太旧导致的编码解析问题，不是 GitGutter 的锅。
- 升级 Git 到 2.30+（推荐 Git for Windows 2.40+），基本解决
- 临时绕过：把项目移到纯英文路径，比如
C:\dev\myproject - 别去改 GitGutter 的 env 编码配置 —— 它不暴露该接口，强行 patch 主题或源码极易失效
- 另外注意：Sublime 必须以项目文件夹方式打开（
File → Open Folder…），不能只打开单个文件或子目录，否则它识别不到.git
最常被忽略的一点：GitGutter 的实时性依赖字体。它用 Unicode 块元素（如 ▌、▐）画图标，非等宽字体（比如“微软雅黑”“苹方”）会导致空白或错位；连字（ligatures）也容易干扰渲染，建议在设置里加 "font_options": ["no_ligatures"]。
