企业官网建设流程全解析

• 文档
• 教程

VS Code（Visual Studio Code）内置了完整的 Git 源码控制能力，让你无需离开编辑器即可完成变更审查、暂存、提交、推送、拉取、解决合并冲突与查看历史等日常版本管理操作。本文以官方源码控制文档为核心，结合仓库内 quickstart、staging-commits、repos-remotes 等配套指南，系统梳理内置 Git 的完整工作流，帮助你在读完本文后掌握：从初始化/克隆仓库到完成首次提交、按行暂存变更、与远程仓库同步、解决冲突、管理分支/工作树/暂存区，以及通过 Git Output 窗口排查常见故障的完整实战能力。

前置条件：Git 与提交身份配置

要在 VS Code 中使用 Git 功能，你需要满足两个前置条件（详见 快速入门 与 排障指南）：

1. 安装 Git：VS Code 本身不携带 Git，所有 Git 操作都调用你机器上安装的 Git 可执行文件。安装后可在集成终端中验证：

   git --version

   如果命令找不到，重启 VS Code；若仍失败，请参考 源码控制排障。

2. 配置提交作者身份：user.name与user.email会记录在每次提交中，它们标识的是提交作者，不是你的登录凭据：

   git config --global user.name "<your-name>" git config --global user.email "<your-email>"

   --global选项将该身份设为所有仓库的默认值。若提交后会被发布到远程，作者信息也会随之共享。跳过此步骤会导致提交时报错Make sure you configure your "user.name" and "user.email" in git，此时可用git config --get user.name/git config --get user.email检查当前生效值，并针对单个仓库执行不带--global的配置命令修正。

需要澄清的一点：Git 是版本控制工具，GitHub 是托管 Git 仓库并提供 Pull Request 等协作功能的托管服务。使用 Git 做本地版本管理并不需要任何托管账号。

开始使用一个仓库

通过File>Open Folder...打开一个仓库文件夹，即可使用它的 Git 历史。如果你还没有本地仓库，可以从以下三条路径中选择（官方概述）：

路径一：本地初始化并完成首次提交

这是最快上手的方式，无需托管账号或已有项目：

1. 在任意已存在 Git 仓库之外创建空文件夹git-practice，用File>Open Folder...打开（若弹出 Workspace Trust 提示，确认信任自己创建的文件夹，参见 Workspace Trust）。
2. 打开Source Control视图（快捷键Ctrl+Shift+G），选择Initialize Repository。若按钮不可见，可在命令面板（Ctrl+Shift+P）运行Git: Initialize Repository。
3. 在 Explorer 中创建README.md并保存（Ctrl+S）。此时它会出现在 Source Control 视图的Changes区，标记U（untracked，未跟踪）——Git 能看到这个新文件，但它还不属于任何提交。
4. 悬停文件行选择+（Stage Changes）将其移入Staged Changes；在顶部提交消息输入框填写Add practice README，点击Commit。提交成功后文件不再显示为已变更，其内容已写入本地 Git 历史。
5. 展开 Source Control 视图中的Source Control Graph，找到该提交即可验证首次提交成功。

注意：保存文件只是写入磁盘，不会创建 Git 提交；git init也不会上传任何内容到服务器。

路径二：克隆已有仓库

克隆会在本机创建远程仓库的完整副本（包含全部分支、提交与历史），并默认配置名为origin的远程。运行命令面板中的Git: Clone，或在 Source Control 视图点击Clone Repository按钮，输入仓库 URL 即可。若要从 GitHub 浏览仓库，可选择Clone from GitHub登录后从列表挑选；克隆公开仓库的 URL 通常无需登录。

克隆后 VS Code 会询问本地存储位置，并可选择在新窗口中打开。需要说明的是：克隆不授予写入权限，若要推送变更，需使用你有写权限的仓库或先 fork。另外，GitHub 的完整协作能力（Pull Request、Issue 管理）由 GitHub Pull Requests and Issues 扩展 提供，内置 Git 只覆盖克隆、推送等基础操作。

路径三：发布本地仓库到 GitHub

若已有本地仓库但尚未连接远程，运行命令面板中的Publish to GitHub，登录后输入仓库名、选择 public/private，VS Code 会在 GitHub 创建新仓库、添加为远程并推送你的提交。注意区分两个命令：Publish to GitHub创建新的托管仓库；Publish Branch则是把分支上传到已存在的远程并设置其上游分支。若托管仓库已存在，应使用Add Remote添加远程而非再建一个。

源码控制界面：五大组件一览

打开 Source Control 视图（Ctrl+Shift+G）即可审查与提交变更。官方文档归纳了五个核心界面组件（截图来源）：

视图中的文件按暂存状态分两组：Changes列出所有尚未暂存的修改/新增/删除文件；Staged Changes列出已暂存、准备提交的文件。文件前有U（untracked）/M（modified）/D（deleted）状态图标，该指示同样显示在 Explorer 与已修改文件的编辑器标签标题上；活动栏的源码控制图标还会显示受影响文件数的徽标。可通过More Actions（...）>View & Sort在平铺与树形两种视图间切换。

核心工作流详解

工作流一：提交前审查变更

在Changes中选择文件可查看未暂存的编辑，在Staged Changes中选择文件可查看下一个提交将包含的内容。Diff 编辑器的对比对象取决于文件所在列表：

一个文件可能同时出现在两个列表中：编辑并暂存某个文件后再次编辑而不暂存，此时该文件既在 Staged Changes（第一次编辑，待提交）也在 Changes（后续编辑，不在本次提交内）。再次暂存可合并两次编辑，提交暂存版本则把后续编辑留到另一个提交。撤销暂存（Unstage）会保留工作文件中的全部编辑。

Diff 编辑器支持侧边与内联两种布局，默认Automatic布局在空间充足时并排、窗口变窄时自动切换为内联；可通过diffEditor.renderSideBySideInlineBreakpoint调整切换阈值（默认 900 像素），或用diffEditor.renderSideBySide与diffEditor.useInlineViewWhenSpaceIsLimited直接控制底层行为。大文件可用Collapse Unchanged Regions折叠未变更区域，用Next Change/Previous Change快速跳转。编辑器行号旁还有 gutter 指示：绿色标记新增行、蓝色标记修改行、红色三角标记删除行，可点击展开内联 diff 预览，并通过scm.diffDecorations*系列设置（位置、点击动作、图案、可见性、宽度、是否忽略空白差异）自定义。

工作流二：暂存与提交变更

Git 工作流中，保存、暂存、提交、推送是四个独立操作：

暂存捕获的是那一刻选中的内容；此后若再次编辑文件，这些后续编辑不会进入暂存快照，除非再次暂存。暂存文件的方式：悬停Changes中文件点击+，右键选择Stage Changes，或将文件从 Changes 拖拽到 Staged Changes；树形视图下可直接暂存整个文件夹；悬停Changes标题的+可一次暂存全部修改文件。

按行/代码块暂存（Partial Staging）是制作聚焦提交的关键：在 Changes 中选择文件打开 diff 编辑器，选中要暂存的行，点击 gutter 中的Stage按钮，或右键选择Stage Selected Ranges（命令面板中的Git: Stage Selected Ranges亦可）。例如同一文件中的格式化改动与 bug 修复，可拆分为两个带独立提交消息的提交。

提交：在Staged Changes中逐文件复查内容，在提交消息输入框输入描述性消息（如Fix validation for empty names），点击Commit。已提交的变更从 Staged Changes 消失并出现在 Source Control Graph 中，未暂存的编辑仍留在 Changes。提交仅存于本地，直到你推送。提交消息第一行应使用简短摘要，长说明可改用编辑器撰写（见下文）。在输入框内按kb(history.showPrevious)/kb(history.showNext)可循环翻阅历史提交消息。若没有暂存任何内容就点Commit，VS Code 会根据 Git 设置提示你暂存；需要精确控制提交内容时应显式暂存。More Actions>Commit>Commit All可一次性提交全部变更（使用前应复查所有待提交文件）。

撤销与丢弃的决策表（注意各操作效果差异巨大，详见 staging-commits）：

其中Discard会删除未提交工作：对已跟踪文件恢复为暂存版本（无暂存编辑时即当前提交版本），对未跟踪文件直接删除文件。git.discardUntrackedChangesToTrash开启且环境支持时，未跟踪文件可移入回收站；远程环境等限制下可能造成永久删除。若已误丢弃，可到 Timeline 视图查看本地历史条目，但两者都不是有保障的备份。

用编辑器写提交消息：确保git.useEditorAsCommitInput开启，在 Source Control 视图不输入消息直接点Commit，会打开名为COMMIT_EDITMSG的编辑器标签；写完后关闭标签或点编辑器内的Commit完成提交，Cancel可取消。若希望终端里的git commit也用编辑器，开启git.terminalGitEditor并重启终端。

AI 辅助（可选）：配置好 Copilot 后，可在 Source Control 视图点击Code Review对未提交变更做 AI 审查，评论以覆盖层形式显示在编辑器中；点击提交消息输入框的 sparkle 图标可生成提交消息（该功能使用chat.utilitySmallModel配置的实用模型，而非对话会话选用的模型，参见 语言模型配置）。git.addAICoAuthor设置可在提交中追加Co-authored-by:Git trailer：off（默认）不添加，chatAndAgent为聊天/Agent 模式生成的代码添加，all覆盖包括行内补全在内的全部 AI 生成代码（仅作用于 VS Code Git 集成，不作用于外部 Git 客户端或终端命令）。

工作流三：与远程仓库同步（Fetch / Pull / Push / Sync）

远程（remote）是一条指向另一个 Git 仓库的命名连接，通常指向 GitHub、Azure DevOps 或 GitLab 等托管服务。克隆时 Git 自动创建名为origin的远程。理解四种操作（repos-remotes）：

上游分支（upstream）将本地分支与远程分支关联，VS Code 用它执行 pull/push/sync 并显示 incoming/outgoing 提交计数；若分支没有上游，推送时会提示先发布分支。发布分支会推送其提交并设置上游。

• Push：先本地提交，再在 Source Control 视图More Actions>Push；指定远程用命令面板Git: Push to...，也可用 Source Control Graph 工具栏的 Push 图标。若推送因远程有新提交被拒绝（non-fast-forward/fetch first），不要反复 sync 或 force push，应按 排障流程：fetch → 审查 incoming/outgoing → 提交或 stash 本地工作 → pull（merge 或 rebase，冲突则解决后继续）→ 重新 push。
• Pull：More Actions>Pull或命令面板Git: Pull from...。拉取前应提交或 stash 未完成工作，避免 Git 因本地改动会被覆盖而中止。Git 默认 fast-forward 或 merge 传入提交；团队要求线性历史且本地提交未共享时，用Git: Pull (Rebase)重放本地提交（⚠️ rebase 会改写历史，勿对他人已使用的提交执行）。
• Sync Changes：先 pull 上游分支再 push 本地提交，仅当你确实要同时做两件事时使用；若 pull 被冲突阻断，sync 不会继续 push。可在 Source Control 视图点击Sync Changes或状态栏同步图标。状态栏同步指示器显示 outgoing（↑）与 incoming（↓）计数，例如↑2 ↓1表示 2 个待推送、1 个待拉取（计数反映的是最近一次已知的远程状态，fetch 可获取更新）。可用git.confirmSync设置控制同步前是否要求确认。
• Fetch：More Actions>Fetch；Git: Fetch From All Remotes从全部远程获取；Git: Fetch (Prune)会清理远程已删除分支的本地跟踪引用（不删除本地分支），用git.pruneOnFetch可让每次 fetch 都自动 prune。后台自动 fetch 由git.autofetch控制（编辑器窗口默认关闭，Agent 窗口默认开启），间隔用git.autofetchPeriod配置（默认 180 秒）；自动 fetch 不会 pull 或 push，但它可能触发重复的认证弹窗（见排障章节）。

状态栏同步操作：左下角显示分支名与同步/发布动作——选择分支名可切换分支；同步状态显示 incoming/outgoing 计数；无上游时显示Publish Branch。同步图标（旋转箭头）同时执行 pull 和 push，仅需 push 或 pull 时请用 Source Control 视图或命令面板。

多仓库场景：Repositories 视图（命令Source Control: Focus on Repositories View）可在单个工作区管理多个 Git 仓库，也能展示关联的 worktrees。scm.alwaysShowRepositories可让该视图常驻显示；scm.repositories.selectionMode可在多仓库模式（显示所有仓库的变更与图谱）与单仓库模式（只显示选中仓库）间切换。操作前务必确认仓库名与分支，避免动作作用于错误的检出。

工作流四：解决合并冲突

当 Git 无法自动合并竞争变更时（如两个分支修改同一文件的相同行、一个分支删除文件而另一个修改它、两个分支在同一位置添加不同内容），冲突可能发生在 merge、pull、rebase、cherry-pick 或 stash 恢复期间（merge-conflicts）。

冲突文件会出现在 Source Control 视图的Merge Changes区。编辑器用三组标记高亮冲突段落：

• <<<<<<< HEAD（或其他标签）：当前侧起点
• =======：分隔两个冲突版本
• >>>>>>> branch-name（或提交标识）：incoming侧终点

重要：“Current”并不总是你的原始功能分支，各操作的语义如下：

rebase 期间 Git 的 ours/theirs 角色与直觉相反：ours 是新基线，theirs 是被重放的你的工作。应检视变更内容而非仅凭名字选边。

内联解决（CodeLens）：每个冲突上方有 CodeLens 动作——Accept Current Change（保留当前侧）、Accept Incoming Change（保留传入侧）、Accept Both Changes（两侧都保留）、Compare Changes（打开 diff 对比）。接受两侧并不保证代码有效，可能仍需手动去重或合并逻辑。解决后保存文件并点击+暂存，文件从 Merge Changes 移入 Staged Changes。复杂冲突也可手动删除标记并编辑内容。

3-way 合并编辑器：适合复杂冲突。右键 Merge Changes 中文件选择Open in Merge Editor。三个面板：Incoming（左）、Current（右）、Result（底部，将被保存的结果文件）。用每个冲突旁的控件选择纳入 Result 的变更，可接受任一侧或合并两侧；都不合适时可直接在 Result 面板手动编辑。全部解决后点Complete Merge（只暂存该文件并关闭编辑器，不会结束整个仓库操作）。面板侧菜单还提供对比 base、重置 result 等选项，More Actions可切换布局或显示 base 视图。

完成操作：解决并保存所有冲突文件后，按中止的操作类型收尾——merge/合并式 pull：在 Source Control 视图输入合并提交消息点Commit；rebase：终端运行git rebase --continue；cherry-pick：运行git cherry-pick --continue；stash 恢复：审阅后正常提交即可（不要求合并提交）。不确定当前操作时运行git status查看 Git 状态与下一步动作。

取消操作：命令面板选择Git: Abort Merge/Git: Abort Rebase/Git: Abort Cherry Pick。⚠️ 中止会丢弃该操作的冲突解决工作，Git 会尝试恢复操作前状态，但未必能重建操作前的未提交变更。

AI 解决冲突（实验性）：需要 Copilot 访问权限。打开冲突文件，点编辑器顶部的Resolve Merge Conflict with AI按钮，AI 会结合合并基线（双方共同祖先）与两侧变更分析并提出保留双方意图的解决方案，审阅后可接受或手动调整，然后暂存并完成操作。

配置 VS Code 为终端默认合并/差异工具：确保code命令可用（见 命令行文档）后，在 Bash 兼容终端执行：

git config --global merge.tool vscode git config --global mergetool.vscode.cmd 'code --wait --merge "$REMOTE" "$LOCAL" "$BASE" "$MERGED"' git config --global diff.tool vscode git config --global difftool.vscode.cmd 'code --wait --diff "$LOCAL" "$REMOTE"'

之后 Git 操作报告冲突时运行git mergetool启动编辑器（Git 不会在冲突发生时自动启动），用git difftool对比变更。

工作流五：分支、工作树与暂存

分支是历史中指向特定提交的轻量可移动指针。当前分支显示在状态栏、Repositories 视图与 Source Control Graph。切换分支即 “checkout”：选择状态栏分支名或运行Git: Checkout to，从本地/远程/最近分支列表中挑选；若存在未提交变更，Git 可能阻止切换以免丢失工作，建议先提交或 stash。

• 创建分支：Git: Create Branch...从当前提交（HEAD）创建，建议使用feature/user-authentication这类描述性名称；Git: Create Branch From...可从main、origin/main等分支或标签创建。两者创建后都会自动切换。VS Code 还能生成随机分支名，由git.branchRandomName.enable与git.branchRandomName.dictionary控制。
• 重命名/删除分支：Git: Rename Branch重命名当前分支；Git: Delete Branch删除分支（不能删除当前激活分支，需先切走；删除远程分支用Delete Remote Branch）。⚠️ 删除分支会从本地仓库永久移除，请先确认其已合并或不再需要。
• 合并分支：切到目标分支（通常main），运行Git: Merge...选择要合并的分支；冲突会高亮并可用冲突解决工具处理。Publish Branch把分支发布到远程。

Stash（暂存未完成工作）：把选中的未提交变更临时存储，无需创建提交。命令面板或More Actions菜单中：Git: Stash存储已跟踪变更；Git: Stash (Include Untracked)连新增未跟踪文件一起存储；Git: Stash Staged只存储 Staged Changes（需 Git 2.35+）。存储后工作目录中移除这些变更，范围之外的保持不变。Git: View Stash检视内容；Git: Apply Stash...恢复并保留 stash 列表，Git: Pop Stash...恢复并移除，另有 Apply/Pop Latest Stash 快捷操作。Git: Drop Stash.../Git: Drop All Stashes...删除 stash（⚠️ 删除难以撤销）。

Worktree（工作树）：让同一仓库的多个分支同时在不同文件夹中检出。仓库通常有一个主工作树（primary worktree），linked worktree 是同一仓库的另一个工作目录，各有独立的检出文件、暂存区与未提交变更，但共享仓库历史、分支、标签与远程；Git 不允许同一本地分支同时在多个 worktree 中检出。适合并行开发多个功能、并排运行不同版本、跨分支对比实现，以及隔离并行 Agent 会话 的变更。

在Source Control Repositories视图中选中仓库，More Actions>Worktrees>Create Worktree创建，选择分支与位置后 VS Code 会新建文件夹并检出分支。可在新窗口/当前窗口打开 worktree，或直接打开其文件夹（VS Code 自动识别）。Compare with Workspace对比 worktree 变更，Git: Migrate Worktree Changes...把未提交变更（含未跟踪文件）迁移到主 worktree（迁移不合并提交，带提交的变更需 merge 分支）。Git: Delete Worktree...删除工作树（只删工作目录不删分支）；⚠️ 删除同时移除文件夹中的被忽略文件，若含修改或未跟踪文件，VS Code 会提供Force Delete，除非确定丢弃否则应取消。

worktree 相关实验性设置：git.worktreeIncludeFiles用 glob 把.gitignore排除的文件复制进新 worktree（如node_modules、.env），git.worktreeSymlinkFolders则对忽略文件夹做符号链接共享（修改会作用于所有关联 worktree）。git.detectWorktrees开启后自动检测仓库中已有的 worktree，检测数量上限由git.detectWorktreesLimit控制（默认 50）。

工作流六：查看提交历史

历史检视有三个层次（history）：

Source Control Graph：显示提交历史与分支关系，有上游分支时标注 incoming/outgoing。选择提交可展开变更文件列表，再选文件打开 diff；右键提交选择Open Changes查看多文件 diff（二进制文件显示Binary file changed，可Open Diff打开图像 diff 等）。右键Compare with...可将提交与本地/远程分支或标签对比（参考在左、提交在右），Compare with Remote与Compare with Merge Base为快捷方式。Cherry Pick把提交的变更应用到当前分支；Checkout (Detached)检出确切修订（⚠️ 会令HEAD脱离分支，需先建分支再提交）。图谱用scm.graph.showIncomingChanges、scm.graph.showOutgoingChanges控制 incoming/outgoing 显示，用scm.graph.pageSize配置初始加载及每次加载的提交数。

Timeline 视图：在 Explorer 中展开Timeline，显示活动文件的 Git 提交与本地保存事件；右键 Git 提交选Select for Compare，再右键另一提交选Compare with Selected可对比同一文件的两个修订版本（仅对比文件修订，不对比提交中全部文件）。

Git blame：标识最后修改某行的提交与作者，可显示为编辑器内联装饰或状态栏条目（Git: Toggle Git Blame Editor Decoration/Git: Toggle Git Blame Status Bar Item），悬停查看提交详情，悬停内容含 co-author trailers。相关设置：git.blame.statusBarItem.enabled、git.blame.editorDecoration.enabled、git.blame.editorDecoration.disableHover、git.blame.ignoreWhitespace；模板设置git.blame.editorDecoration.template与git.blame.statusBarItem.template控制显示哪些提交信息，例如：

{ "git.blame.editorDecoration.template": "${subject}, ${authorName} (${authorDateAgo})" }

颜色可用git.blame.editorDecorationForeground主题色定制。

与 GitHub Pull Request 和 Issue 协作

克隆、推送等基础 GitHub 操作由内置 Git 支持完成；创建/审查 Pull Request 与管理 Issue 则需要安装 GitHub Pull Requests and Issues 扩展。安装后点击活动栏 GitHub 图标登录，即可使用Pull Requests视图：创建 PR（选择 base 仓库/分支、填写标题描述，未发布分支时可选择推送到 fork）、以 Review Mode 检出 PR 分支本地审查（提交或 stash 当前变更后Checkout，完成后Exit Review Mode返回原分支）。githubPullRequests.queries用 GitHub 搜索语法 定制 PR 列表，例如：

{ "githubPullRequests.queries": [ { "label": "Assigned To Me", "query": "is:open assignee:${user}" } ] }

Issues 视图支持创建 Issue（含从 TODO 注释经 Code Action 创建，触发词由githubIssues.createIssueTriggers配置，默认["TODO", "todo", "BUG", "FIXME", "ISSUE", "HACK"]）、Start Working on Issue自动创建分支（分支名由githubIssues.issueBranchTitle配置，可用githubIssues.useBranchForIssues关闭自动建分支）、提交消息自动填充（githubIssues.workingIssueFormatScm）等功能。编辑器内支持@用户与#Issue 的悬停与补全建议。若只想浏览/编辑远程仓库而不克隆，可改用 GitHub Repositories 扩展 打开虚拟工作区——注意虚拟文件系统下任务、调试与集成终端等能力受限，提交会直接推送到远程。

其他源码控制提供方

内置 Git 之外，可通过扩展使用 Subversion、Mercurial 等其他版本控制系统：在扩展视图（Ctrl+Shift+X）搜索@category:"scm providers"浏览 SCM 提供方扩展，或在扩展市场按 SCM Providers 分类筛选。托管在 Azure DevOps 的 Git 仓库直接使用内置 Git 集成。对扩展作者而言，如何实现一个 SCM 提供方可参考仓库中的 SCM Provider 扩展指南——它基于vscode.scmAPI 注册 Source Control 视图、资源组与操作，这正是其他 SCM 扩展接入 VS Code 界面的机制。

常见故障排查：用 Git Output 窗口定位问题

遇到 Git 报错时，第一件事是打开Git Output 窗口（troubleshooting）：Source Control 视图More Actions>Show Git Output，或命令面板Git: Show Git Output，或 Output 面板频道列表选Git。它记录 Git 可执行文件、命令、错误、时间戳与耗时；默认仅在命令失败时显示标准输出，可用git.commandsToLog设置强制记录指定命令的输出。Output 面板支持按日志级别（默认info）与类别（选git聚焦 Git 执行的命令）过滤，搜索框支持正则。

常见症状与对策：

• Git not found：在打开仓库的那个环境（远程工作区需检查远程环境而非仅本地）运行git --version；命令有效但 VS Code 找不到时，检查 Git Output 尝试过的路径，必要时设置git.path为可执行文件完整路径并重启。
• 提交失败提示缺少 user.name/user.email：按上文前置条件配置仓库级或全局身份（登录托管服务不会配置该身份）。
• 忽略的文件仍出现在 Source Control：.gitignore只作用于未跟踪文件。用git ls-files -- "<file>"检查是否已被跟踪；若已提交需按 “停止跟踪但保留本地副本” 流程处理：在.gitignore加规则 →git rm --cached -- "<file>"→ 提交。用git check-ignore -v -- "<file>"检查生效的忽略规则（!开头模式会重新纳入匹配文件）。注意files.exclude设置只在 Explorer 中隐藏文件，不改变 Git 跟踪或忽略规则。
• 推送被拒绝（non-fast-forward）：按同步章节的流程 fetch → 审查 → pull → 重新 push；不要用 force push 绕过。
• 权限/只读/受保护分支：先看 Git Output 中失败的命令与完整错误，运行git remote -v确认 fetch/push URL。Authentication failed/Permission denied (publickey)检查凭据（HTTPS 检查 credential helper，SSH 检查密钥）；无写权限则申请或推送到自己的 fork；受保护分支规则无法靠改凭据或 force push 绕过；本地Permission denied/Read-only file system则检查文件系统权限与挂载方式。
• push/pull/sync 不结束：通常是 Git 在等待不可见的认证提示。检查 Git Output 中最新命令是否认证错误，配置系统 credential helper（Windows/macOS/Linux 推荐 Git Credential Manager），重新操作并完成登录。
• 认证提示反复出现：若git.autofetch开启，后台 fetch 会触发认证；确认 Git Output 中触发命令，配置 credential helper 存储凭据，或关闭git.autofetch。
• 初始化仓库后 Git 动作不可用：push/pull/sync 需要远程仓库，git init不会创建远程；用Add Remote连接已存在的托管仓库，或Publish to GitHub新建。
• 仓库 “potentially unsafe”：Git 会阻止操作其他系统用户拥有的仓库。选择Manage Unsafe Repositories审查后标记安全（写入 Git 的safe.directory配置）。Windows 上常发生于：管理员身份应用克隆的仓库后来被非管理员身份打开。
• 父文件夹中的仓库未被检测：VS Code 默认不自动打开父文件夹中的仓库（避免暴露预期文件夹之外的变更）；检测到时用通知或欢迎视图打开，或设git.openRepositoryInParentFolders为always。

日志信息不足时，可在 Git Output 窗口点齿轮图标选择Trace级别并复现问题。注意 trace 日志可能包含仓库路径、远程 URL、分支名等开发信息，分享前请脱敏。

下一步学习路径

• 在引导式练习项目中完成 你的第一次提交。
• 观看 Git 入门视频 获取可视化讲解。
• 查看 源码控制 FAQ 了解 Git 客户端、认证与其他提供方的兼容性。
• 按需深入：按行暂存制作聚焦提交（staging-commits）、分支/工作树/暂存管理（branches-worktrees）、远程同步策略（repos-remotes）、历史检视（history）与冲突解决（merge-conflicts）。

• 文档
• 教程