Sublime Text 需通过 SublimeGit 插件实现 Git 同步，前提是系统已安装 git 且 PATH 正确、项目为已初始化的 Git 仓库、远程 URL 认证有效；插件不自动初始化仓库或处理凭据，所有操作依赖底层 git 命令行为。
Sublime Text 本身不内置 Git 同步能力，必须通过插件实现；SublimeGit 是最成熟的选择，但它的配置不是“装完就用”，关键在于 git 命令是否在系统 PATH 中、项目根目录是否识别为 Git 仓库、以及远程 URL 是否支持当前认证方式。
确认系统已安装 git 并可被 Sublime 调用
Sublime Git 插件底层调用的是系统命令行的 git，不是自己实现 Git 协议。如果终端能运行 git --version，但 Sublime 里执行 Git: Status 报错 “command not found”，大概率是 PATH 未正确继承。
-
macOS / Linux：检查 Sublime 是否从终端启动（比如在终端输入
subl .），否则 GUI 方式启动时可能读不到 shell 的 PATH - Windows：确认
git安装时勾选了 “Add Git to the system PATH”；若用 Scoop/Chocolatey 安装，需手动把git\cmd或git\bin加入系统环境变量 - 验证方法：Sublime 中按
Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入Git: Show Version—— 应返回类似git version 2.40.1
初始化本地仓库并设置 remote origin
SublimeGit 不会自动帮你 git init 或 git remote add。它只操作已有仓库。如果你打开一个普通文件夹，即使 GitHub 上有同名 repo，Sublime 也完全不知道关联关系。
- 先在项目根目录终端执行：
git init→git add .→git commit -m "init" - 再绑定远程：
git remote add origin https://github.com/username/repo.git（HTTPS）或git@github.com:username/repo.git（SSH） - 注意：HTTPS 方式在 push 时会弹窗要求输入 GitHub 账号密码（或 Personal Access Token）；SSH 方式需提前配置
~/.ssh/id_rsa.pub到 GitHub SSH Keys - Sublime 中执行
Git: Remote Add只是快捷输入，不能替代命令行设置
处理 authentication failed 或 Permission denied 错误
这是同步失败最常见原因，和插件无关，本质是 Git 凭据问题。SublimeGit 调用 git push 时卡住或报错，通常是因为凭据没缓存或 SSH key 未加载。
- HTTPS 用户：运行
git config --global credential.helper store，首次 push 后账号密码会明文存到~/.git-credentials（不安全但对个人开发够用）；更推荐用osxkeychain（macOS）或manager-core（Windows） - SSH 用户：确保
ssh-add -l能列出你的 key；如无输出，运行ssh-add ~/.ssh/id_rsa；Sublime 启动前需完成这步，否则插件无法复用 agent - 别信“Sublime 内置登录框”——
SublimeGit不提供图形化登录界面，所有认证都走系统级 Git 行为
避免误操作：pull / push 前务必检查当前分支与状态
SublimeGit 的 UI 简洁，但缺少 IDE 级别的分支保护提示。比如你在 main 分支修改后直接 Git: Push，它不会提醒你是否已 git add 或是否有 untracked 文件。
- 每次操作前先按
Git: Status（快捷键Ctrl+Shift+P→ 输入该命令），看左侧栏是否显示 staged/unstaged/Untracked -
Git: Pull默认拉取当前分支对应 remote 的最新提交，但不会自动 merge —— 如果本地有未提交变更，会提示 conflict，此时必须切回终端手动git stash或解决冲突 - 慎用
Git: Force Push：它等价于git push --force-with-lease，可能覆盖他人提交，仅限重写自己刚推上去的 commit
真正卡住人的从来不是插件怎么装，而是 git 本身的权限链、工作区状态、分支跟踪关系这些隐性依赖。SublimeGit 只是把命令行操作搬到编辑器里，它不替你理解 Git 模型。
