VS Code 内置 Git 支持需正确配置 git.path 并理解其依赖本地 Git、仅识别最外层 .git 目录、提交前必须手动暂存、推送失败应优先检查远程 URL 和凭证。
VS Code 内置的 Git 支持足够日常使用，但默认配置下容易卡在「看不到仓库状态」「提交失败没提示」「分支切换不生效」这几个地方。关键不是装插件，而是把 VS Code 的 Git 集成和本地 Git 二进制打通、并理解它怎么读取 .git 目录。
确认 VS Code 正确识别了 Git 二进制路径
VS Code 不自带 Git，它依赖系统已安装的 git 命令。如果终端能运行 git --version，但 VS Code 底部状态栏不显示分支名或 Git 图标灰掉，大概率是路径没找对。
- 打开 VS Code 设置（
Ctrl+,），搜索git.path - 填入你本地
git可执行文件的绝对路径，例如 Windows 上可能是C:\Program Files\Git\bin\git.exe，macOS 上常用/usr/local/bin/git或/opt/homebrew/bin/git - 改完后重启 VS Code——仅重载窗口不够，必须完全退出再启动
- 验证：打开一个含
.git目录的文件夹，看底部状态栏是否出现分支名（如main）和修改计数
初始化仓库或打开已有仓库时的常见陷阱
VS Code 不会自动初始化 Git 仓库，也不会跨文件夹递归识别子模块。它只认当前打开的**最外层文件夹**是否为 Git 工作区根目录。
适用于以下场景：（1）用户提供 GitHub 仓库 URL 或本地仓库路径，并请求将其转换为其他格式；（2）用户请求导出 GitHub 仓库……
- 新建项目后想用 Git：先在终端里
git init，再用 VS Code 打开该文件夹；直接用 VS Code 新建文件夹再点「初始化 Git 仓库」按钮，本质也是调git init，但失败时 UI 提示极弱 - 项目嵌套（比如 monorepo）：VS Code 默认只激活最外层的
.git。若想同时管理子目录下的独立仓库，需手动添加工作区：用File > Add Folder to Workspace...，每个子仓库单独加 - 打开非根目录（比如只打开
src/文件夹）：Git 功能完全不可用，状态栏无反应——必须打开包含.git的那一级
提交前必须理解「暂存区」在 VS Code 里的表现形式
VS Code 的源代码管理视图（Ctrl+Shift+G）左侧列出的是「未暂存的更改」，点击文件旁的 + 按钮才进入暂存区，这点和命令行的 git add 严格对应。很多人误以为点右上角 √ 就是直接提交，其实它只提交「已暂存的文件」。
- 修改一个文件后，它出现在「CHANGES」下；点击文件名左侧的
+，它会移到「STAGED CHANGES」下 - 输入提交信息后点 √，等同于执行
git commit -m "xxx"；如果没点+，这个提交不会包含该文件的改动 - 想跳过暂存直接提交？VS Code 不支持
git commit -a这种快捷方式。必须手动暂存，或改用终端 - 误点了
+？在「STAGED CHANGES」里右键文件，选Undo Stage即可撤回
推送失败时优先检查远程 URL 和凭证
点击「...」菜单里的 Push 报错 fatal: could not read Username for 'https://github.com': No such device or address 或类似提示，基本是远程地址或认证出了问题，和 VS Code 关系不大。
- 先运行
git remote get-url origin确认远程地址是否正确（尤其注意是https://还是git@） - HTTPS 地址需凭据：Windows 用户建议用 Git Credential Manager，macOS 用 Keychain，Linux 可配
git config --global credential.helper store - SSH 地址需有对应私钥且
ssh-agent已加载；测试命令：ssh -T git@github.com - VS Code 不会弹出任何密码/令牌输入框——所有认证都由底层 Git 处理，它只负责转发结果
真正麻烦的从来不是按钮在哪，而是 VS Code 把 Git 的分层操作（工作区 → 暂存区 → 仓库）藏在了图形界面背后。一旦文件没出现在「STAGED CHANGES」里，就别急着点提交；一旦推送失败，先切到终端跑两行 git 命令，比翻设置快得多。
