Git 仓库操作与 VSCode 使用指南

环境：macOS（快捷键以 Mac 为主，括号内附 Windows/Linux 对应键）；Git 命令在三大平台一致。

适用：Gitee / GitHub / GitLab 等任意 Git 远程仓库、任意语言的项目。

照着复制命令即可操作。文中 <...> 为需要替换成你自己信息的占位符。

最近用到的，以及让ai总结的

[第一部分：Git 常用操作](#第一部分：Git 常用操作)

[1. 核心概念（先搞懂这 4 个区）](#1. 核心概念（先搞懂这 4 个区）)

[2. 首次使用：安装与配置](#2. 首次使用：安装与配置)

[3. 克隆仓库（第一次把项目下载到本地）](#3. 克隆仓库（第一次把项目下载到本地）)

[4. 日常开发四板斧（status / add / commit / pull+push）](#4. 日常开发四板斧（status / add / commit / pull+push）)

[5. 查看历史](#5. 查看历史)

[6. 分支操作](#6. 分支操作)

[7. 合并（merge）](#7. 合并（merge）)

[7.1 把开发分支的最新代码合并进自己的功能分支](#7.1 把开发分支的最新代码合并进自己的功能分支)

[7.2 功能分支合并回开发分支](#7.2 功能分支合并回开发分支)

[7.3 进阶：只把某个目录/文件从一个分支合并到另一个分支](#7.3 进阶：只把某个目录/文件从一个分支合并到另一个分支)

[8. 冲突处理（必会）](#8. 冲突处理（必会）)

[9. 撤销与回退（危险操作，看清再做）](#9. 撤销与回退（危险操作，看清再做）)

[10. 暂存当前工作（stash）](#10. 暂存当前工作（stash）)

[11. fetch 与 pull、常见报错](#11. fetch 与 pull、常见报错)

[12. .gitignore：哪些文件不进仓库](#12. .gitignore：哪些文件不进仓库)

[13. 命令速查表](#13. 命令速查表)

[第二部分：VSCode 使用入门](#第二部分：VSCode 使用入门)

[1. 安装与打开项目](#1. 安装与打开项目)

[2. 界面分区](#2. 界面分区)

[3. 扩展推荐（按你的技术栈选装，扩展面板 ⇧⌘X 搜索）](#3. 扩展推荐（按你的技术栈选装，扩展面板 ⇧⌘X 搜索）)

[4. 内置终端](#4. 内置终端)

[5. 图形化 Git 操作（不想记命令时）](#5. 图形化 Git 操作（不想记命令时）)

[6. 实用编辑功能](#6. 实用编辑功能)

[第三部分：VSCode 常用快捷键](#第三部分：VSCode 常用快捷键)

[1. 通用](#1. 通用)

[2. 编辑](#2. 编辑)

[3. 查找替换](#3. 查找替换)

[4. 光标与导航](#4. 光标与导航)

[5. Git 相关](#5. Git 相关)

[6. 先记住这 8 个最高频](#6. 先记住这 8 个最高频)

附：通用团队协作工作流速记

第一部分：Git 常用操作

1. 核心概念（先搞懂这 4 个区）

工作区（你正在编辑的文件）

│ git add

▼

暂存区（本次准备提交的文件）

│ git commit

▼

本地仓库（.git，只在你电脑上）

│ git push

▼

远程仓库（Gitee/GitHub/GitLab 上的代码，团队共享）

工作区：你在文件夹里看到、正在改的文件。
暂存区 ：git add 之后、"打算放进下一次提交"的文件清单。
本地仓库 ：git commit 后生成的一条历史记录（有唯一编号，如 8a1b22e）。
远程仓库 ：服务器上的仓库；git push 上传本地提交，git pull 下载并合并别人的提交。

常见分支约定（不同项目命名可能不同，以团队规定为准）：

分支类型	常见名称	用途
主干分支	`main`（老仓库可能叫 `master`）	稳定可发布版本，不要直接在上面开发
开发分支	`dev` / `develop`	日常集成，功能完成后合入
功能分支	`feature/xxx`	每个新功能/每个 bug 一条，开发完合并回 dev
修复分支	`fix/xxx`、`hotfix/xxx`	修缺陷，紧急修复可从主干切出

查看远程仓库地址用 git remote -v，先确认你连的是哪个仓库。

2. 首次使用：安装与配置

Mac 一般自带 git，终端执行 git --version 验证；没有则 brew install git。

Windows 安装 Git for Windows（自带 Git Bash）。

第一次用必须配置身份（提交记录里显示的名字和邮箱，建议与代码平台一致）：

bash 复制代码

git config --global user.name  "<你的用户名>"
git config --global user.email "<你的邮箱@example.com>"

# 可选：彩色输出
git config --global color.ui auto
# 可选：指定 pull 默认用合并方式，避免分叉提示
git config --global pull.rebase false

配置分三个层级：

--global（当前用户所有仓库）、

--local（仅当前仓库，默认）、

--system（整台机器）。

查看某项配置：git config user.name。

SSH 免密登录（推荐，配一次以后 pull/push 不用输密码）：

bash 复制代码

# 1. 生成密钥（一路回车）
ssh-keygen -t id -C "<你的邮箱@example.com>"

# 2. 复制公钥
#    Mac:   cat ~/.ssh/id.pub | pbcopy
#    Windows(在 Git Bash 里): cat ~/.ssh/id.pub | clip
#    或直接用记事本打开 C:\Users\<用户名>\.ssh\id.pub 全选复制

# 3. 粘贴到代码平台的 SSH 公钥设置页：
#    Gitee:  头像 → 设置 → SSH 公钥
#    GitHub: 头像 → Settings → SSH and GPG keys → New SSH key
#    GitLab: 头像 → Preferences → SSH Keys

# 4. 测试连接（首次会问 yes/no，输入 yes）
ssh -T git@gitee.com   # GitHub 用 ssh -T git@github.com
# 出现 "successfully authenticated" 即成功

3. 克隆仓库（第一次把项目下载到本地）

在你想存放代码的目录下打开终端，执行：

bash 复制代码

# SSH 方式（推荐，配过密钥后免密）
git clone <git@gitee.com:用户名/仓库名.git>

# HTTPS 方式（推送时需输入账号 + 私人访问令牌，而非登录密码）
git clone <https://gitee.com/用户名/仓库名.git>

克隆后进入目录、查看并切换分支：

bash 复制代码

cd <仓库名>
git branch -a          # 查看所有本地与远程分支（* 号是当前分支）
git checkout dev       # 切到团队的开发分支（分支名以项目为准）

只想获取仓库最新代码、不保留历史（极少数场景）才用 --depth 1，日常开发不要用浅克隆。

4. 日常开发四板斧（status / add / commit / pull+push）

bash 复制代码

# ① 看当前改了什么（提交前永远先 status）
git status

# ② 看具体改动内容
git diff                  # 工作区 vs 暂存区
git diff --cached         # 暂存区 vs 上次提交（即本次将提交什么）

# ③ 把改动加入暂存区
git add <文件路径>          # 加指定文件
git add <目录>/            # 加整个目录
git add -A                # 加全部增/删/改（慎用，先 status 确认没有混入无关文件）

# ④ 提交（-m 后写提交说明，讲清"做了什么、为什么"）
git commit -m "<类型>: <说明>"

# ⑤ 先拉取远程最新代码（减少冲突），再推送
git pull origin <分支名>
git push origin <分支名>

提交信息建议格式 ：类型(范围): 做了什么

类型：feat 新功能、fix 修 bug、style 格式调整、refactor 重构、docs 文档、test 测试、chore 构建/杂务
示例：feat(login): 增加图形验证码、fix: 修复列表分页越界

关键认知：commit 只存在于本地，忘了 push 队友看不到；没 commit 的改动 push 不上去。

建议小步勤提交：完成一个可运行的小改动就提交一次，而不是攒一大堆。

5. 查看历史

bash 复制代码

git log --oneline -10        # 最近 10 条提交（一行一条）
git log --oneline --graph    # 带分支合并图形
git show <提交编号>           # 看某次提交具体改了什么
git blame <文件路径>          # 看文件每一行最后是谁、哪次提交改的
git log --oneline <文件路径> # 只看某个文件的修改历史

6. 分支操作

bash 复制代码

git branch                       # 查看本地分支
git branch <新分支名>             # 新建分支（不切换）
git checkout -b <新分支名>        # 新建并切换（最常用）
git switch <分支名>               # 切换到已存在分支（Git 新命令）
git switch -c <新分支名>          # 新建并切换的新写法
git branch -d <分支名>            # 删除已合并的本地分支
git push origin --delete <分支名> # 删除远程分支（确认无用后）

典型功能开发流程：

bash 复制代码

git checkout dev
git pull origin dev                 # 先更新开发分支
git checkout -b feature/<功能名>     # 从 dev 切功能分支
# ...编码，多次 add / commit...
git push -u origin feature/<功能名>  # 首次推送，-u 建立跟踪，以后直接 git pull / git push
# 然后在代码平台上发 Pull Request（GitHub）/ Merge Request（GitLab、Gitee）申请合并回 dev

7. 合并（merge）

7.1 把开发分支的最新代码合并进自己的功能分支

bash 复制代码

git checkout feature/<功能名>
git fetch origin                 # 先下载远程最新引用（不改工作区，安全）
git merge origin/dev             # 合并
# 无冲突自动完成；有冲突见第 8 节

7.2 功能分支合并回开发分支

bash 复制代码

git checkout dev
git pull origin dev
git merge feature/<功能名>
git push origin dev

7.3 进阶：只把某个目录/文件从一个分支合并到另一个分支

适用场景：源分支上混着多个模块的改动，但本次只想把其中一个目录同步到目标分支，其他一律不动。思路是基于最新目标分支开一个隔离工作树，只检出需要的目录。

bash 复制代码

git fetch origin

# ① 基于目标分支创建隔离工作树（不影响你当前工作区）
git worktree add -b <临时分支名> /tmp/<临时目录> origin/<目标分支>
cd /tmp/<临时目录>

# ② 用源分支的指定目录整体替换
git rm -r -q <要同步的目录>
git checkout <源分支> -- <要同步的目录>
# 只同步若干文件则用：git checkout <源分支> -- 文件1 文件2

# ③ 提交前务必核对：暂存内容必须都在预期目录内
git diff --cached --name-only | awk -F/ '{print $1}' | sort | uniq -c

# ④ 提交并推送到目标分支（正常推送，禁止 force）
git commit -m "chore: 同步<模块名>到<目标分支>"
git push origin HEAD:<目标分支>

# ⑤ 清理临时工作树与临时分支
cd -
git worktree remove /tmp/<临时目录>
git branch -D <临时分支名>

8. 冲突处理（必会）

git pull 或 git merge 时，若你和别人改了同一文件的同一位置 ，Git 无法自动决定，会报 CONFLICT：

bash 复制代码

Auto-merging src/app.js
CONFLICT (content): Merge conflict in src/app.js
Automatic merge failed; fix conflicts and then commit the result.

处理步骤：

git status 查看冲突文件（标记为 both modified）。
打开文件，会看到冲突标记：

bash 复制代码

<<<<<<< HEAD
这是你当前分支的代码
=======
这是合并进来的分支的代码
>>>>>>> origin/dev

人工决定保留哪段（可保留其一，也可把两边融合），然后把 <<<<<<<、=======、>>>>>>> 三行标记全部删除。
保存后：

bash 复制代码

git add <冲突文件>
git commit            # 保存默认的合并提交说明即可
# 中途想放弃本次合并：
git merge --abort

原则：冲突标记一个都不能留；看不懂对方代码就先沟通，不要盲目选一边。VSCode 提供图形按钮，见第二部分第 5 节。

9. 撤销与回退（危险操作，看清再做）

bash 复制代码

# 改乱了、还没 add：丢弃某文件的工作区修改（不可恢复！）
git checkout -- <文件>          # 新写法：git restore <文件>

# 已 git add、还没 commit：撤出暂存区（改动仍保留在工作区）
git restore --staged <文件>     # 旧写法：git reset HEAD <文件>

# 已 commit、还没 push：撤销最近一次提交，改动保留
git reset --soft HEAD~1

# 已 commit、想连改动一起丢弃（危险！）
git reset --hard HEAD~1

# 已 push 到远程的错误提交：用"反向提交"抵消（安全，推荐）
git revert <提交编号>
git push origin <分支名>

铁律：

已 push 到共享分支的提交，绝不要用 reset --hard 加强推（force push）改写历史，会冲掉队友的提交。
拿不准的撤销，先沟通，或先 git stash、手动复制备份。

10. 暂存当前工作（stash）

改了一半要临时切去别的分支处理问题、又不想提交半成品时：

bash 复制代码

git stash                 # 收起当前改动，工作区变干净
git stash list            # 查看暂存列表
# ...切换分支处理问题...
git checkout <原分支>
git stash pop             # 恢复最近一次暂存的改动
git stash drop            # 删除最近一条暂存

11. fetch 与 pull、常见报错

bash 复制代码

git fetch origin    # 只下载远程最新信息，不动你的文件（安全，可随时执行）
git pull            # = fetch + merge，下载并直接合并到当前分支

Your local changes would be overwritten ：你有未提交改动会被覆盖。先 git stash 或先 commit，再 pull，之后 git stash pop。
rejected / non-fast-forward / fetch first ：远程已有别人的新提交，你落后了。先 git pull、解决冲突后再 push。
failed to push some refs：同上，先拉取合并。
误提交了密钥/密码 ：立即在对应平台改密/作废令牌；仅删除再提交无法抹除历史，需用 git filter-repo 等工具清理并通知协作者。

12. .gitignore：哪些文件不进仓库

仓库根目录的 .gitignore 定义忽略规则，每行一条，支持通配符：

bash 复制代码

node_modules/        # 依赖目录
dist/ build/         # 构建产物
*.log                # 所有日志
.env                 # 环境变量/密钥
.DS_Store            # Mac 系统文件
.idea/ .vscode/      # IDE 个人配置（按团队约定）

通用原则：

依赖目录、编译/打包产物、日志、本地环境配置、密钥证书、系统临时文件都不应提交；

能通过安装命令重新生成的东西通常不入库。

让某个已被跟踪的文件改为忽略：

bash 复制代码

git rm --cached <文件>     # 从仓库移除但保留本地文件
# 在 .gitignore 加入规则后，git add .gitignore && git commit

13. 命令速查表

目的	命令
看状态	`git status`
看改动	`git diff` / `git diff --cached`
暂存	`git add <文件>` / `git add -A`
提交	`git commit -m "说明"`
只下载不合并	`git fetch origin`
拉取并合并	`git pull origin <分支>`
推送	`git push origin <分支>`
新建并切分支	`git checkout -b <分支>`
切分支	`git switch <分支>`
合并	`git merge <分支>`
放弃合并	`git merge --abort`
临时收起/恢复改动	`git stash` / `git stash pop`
看历史	`git log --oneline --graph`
丢弃未暂存修改	`git restore <文件>`
撤销已 push 的提交	`git revert <提交号>`
看远程地址	`git remote -v`

第二部分：VSCode 使用入门

1. 安装与打开项目

官网下载安装：https://code.visualstudio.com （Mac 按芯片选 Apple Silicon / Intel；Windows 选 System Installer）。
菜单 文件 → 打开文件夹...（File → Open Folder），选择项目根目录 （含 .git 的那一层），不要只打开某个子目录，否则 Git 根、路径引用会不对。
首次打开弹窗选择"是，我信任此作者"。

2. 界面分区

┌──────────┬─────────────────────┬──────────┐

│ 活动栏 │ 侧边栏（资源管理器） │ 编辑区 │

│ (一列图标)│ 文件树/搜索/Git │ 代码标签页│

├──────────┴─────────────────────┴──────────┤

│ 面板区（终端/问题/输出） │

└───────────────────────────────────────────┘

状态栏（左下：分支 / 报错 / 编码）

活动栏图标：资源管理器（文件）、搜索、源代码管理（Git）、运行和调试、扩展。
底部状态栏左下角直接显示当前 Git 分支，点击即可切换/新建分支。

3. 扩展推荐（按你的技术栈选装，扩展面板 `⇧⌘X` 搜索）

扩展	适用
Chinese 中文语言包	菜单汉化
Prettier	保存自动格式化（前端通用）
ESLint	JavaScript / TypeScript / Vue / React 代码检查
Vue - Official（Volar）	Vue 3 项目
Python	Python 项目
Extension Pack for Java Language Support for Java Spring Boot Extension Pack	Java / Spring 项目
GitLens	增强 Git：行内显示每一行是谁改的、文件历史、分支图
Error Lens	报错信息直接显示在代码行尾

不需要全部安装，按当前项目语言挑对应几个即可。

4. 内置终端

快捷键 `⌃`` （Control + 反引号，Esc 下方）打开/关闭，默认就在项目根目录，直接敲 Git 命令。
面板右上角 + 新建终端，可分屏并列。

5. 图形化 Git 操作（不想记命令时）

点左侧「源代码管理」图标或按 ⌃⇧G。

改动文件分组列出：更改（未暂存）/ 暂存的更改。
鼠标悬停文件点 + = git add；点 - 取消暂存；点文件本身可左右对比差异。
顶部消息框写提交说明，按 ⌘Enter = commit。
点状态栏左下角分支名切换/新建分支；点 ... 菜单执行 Pull / Push / Sync。

解决冲突：冲突文件中会出现 "Accept Current Change（采用当前）/ Accept Incoming（采用传入）/ Accept Both（保留双方）" 按钮，点选后保存即可，无需手删标记，再去提交。

6. 实用编辑功能

⌘P：按文件名快速跳转（最常用）。
⇧⌘F：全项目搜索文字；搜索框右侧可开启全局替换。
⇧⌘O（文件内）：跳转到符号（函数/变量）。
保存自动格式化：⌘, 打开设置 → 搜索 format on save → 勾选 Editor: Format On Save。
安装 GitLens 后，编辑器行尾会显示该行的最近提交信息，右键可看文件历史。

第三部分：VSCode 常用快捷键

Mac 符号：⌘ Command、⌃ Control、⌥ Option、⇧ Shift。

1. 通用

功能	Mac	Windows / Linux
命令面板（功能都能在这里搜到）	`⇧⌘P`	`Ctrl+Shift+P`
设置	`⌘,`	`Ctrl+,`
快速打开文件	`⌘P`	`Ctrl+P`
终端开/关	```⌃``	```Ctrl+``
侧边栏开/关	`⌘B`	`Ctrl+B`

2. 编辑

功能	Mac	Windows / Linux
复制当前行到下/上一行	`⇧⌥↓/↑`	`Shift+Alt+↓/↑`
删除当前行	`⇧⌘K`	`Ctrl+Shift+K`
上/下移动整行	`⌥↓ / ⌥↑`	`Alt+↓/↑`
选中下一个相同词（多光标批量改）	`⌘D`	`Ctrl+D`
上/下方插入光标	`⌥⌘↑/↓`	`Ctrl+Alt+↑/↓`
缩进 / 反缩进	`⌘] / ⌘[`	`Tab / Shift+Tab`
单行注释切换	`⌘/`	`Ctrl+/`
块注释	`⇧⌥A`	`Shift+Alt+A`
撤销 / 重做	`⌘Z / ⇧⌘Z`	`Ctrl+Z / Ctrl+Y`
跳到指定行号	`⌃G`	`Ctrl+G`
格式化文档	`⇧⌥F`	`Shift+Alt+F`

3. 查找替换

功能	Mac	Windows / Linux
文件内查找	`⌘F`	`Ctrl+F`
文件内替换	`⌥⌘F`	`Ctrl+H`
全项目搜索	`⇧⌘F`	`Ctrl+Shift+F`
全项目替换	`⇧⌘H`	`Ctrl+Shift+H`

4. 光标与导航

功能	Mac	Windows / Linux
行首 / 行尾	`⌘← / ⌘→`	`Home / End`
文件顶 / 底	`⌘↑ / ⌘↓`	`Ctrl+Home / End`
跳到定义	`F12`（或 `⌘点击`）	`F12`（`Ctrl+点击`）
行内预览定义	`⌥F12`	`Alt+F12`
后退 / 前进（跳转历史）	`⌃- / ⌃⇧-`	`Alt+← / Alt+→`
关闭当前标签	`⌘W`	`Ctrl+W`
切换标签	`⌃⇥`	`Ctrl+Tab`

5. Git 相关

功能	Mac	Windows / Linux
打开源代码管理面板	`⌃⇧G`	`Ctrl+Shift+G`
在提交框提交	`⌘Enter`	`Ctrl+Enter`
在命令面板执行 Git 命令	`⇧⌘P` → 输入 `Git:`	`Ctrl+Shift+P` → `Git:`

6. 先记住这 8 个最高频

⌘P 找文件；
⇧⌘F 全局搜；
⌘D 多选相同词批量改；
⌘/ 注释；
⇧⌥↓ 复制行；
⌃`` 终端；
F12 跳定义；
⇧⌘P` 不会的功能先在这里搜。

附：通用团队协作工作流速记

bash 复制代码

# 开工：更新开发分支，切功能分支
git checkout dev && git pull origin dev
git checkout -b feature/<功能名>

# 开发中：小步勤提交
git status → git add → git commit -m "feat(范围): 内容"

# 完成：先拉后推，冲突在 VSCode 里点按钮解决 → add → commit
git pull origin dev
git push -u origin feature/<功能名>

# 在代码平台发 PR/MR，评审通过后合并到 dev；dev 稳定后再由负责人合并到主干