【万字】Git完全指南：从基础到协作开发的最佳实践

菜菜why

已于 2025-04-07 19:31:24 修改

阅读量979

点赞数 12

CC 4.0 BY-SA版权

分类专栏：嵌入式学习记录文章标签： git

于 2025-04-07 18:44:23 首次发布

本文链接：https://blog.csdn.net/qq_23220445/article/details/147050059

嵌入式学习记录专栏收录该内容

9 篇文章

订阅专栏

一、git基础介绍

Git 是一个 分布式版本控制系统，用于跟踪代码变化、协作开发和版本管理。

（1）Git 安装与配置

1. 安装 Git

Windows: git-scm.com 下载安装
Mac: brew install git
Linux: sudo apt install git

下载完成后，在终端输入git -v，输出版本则安装成功，否则可能是没有添加到环境变量。

2. 全局配置（只需一次）

配置作者名、邮箱和默认编辑器。

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
git config --global core.editor code  # 设置 VSCode 为默认编辑器

（2）基本使用方法：

git有工作区（在电脑上看到的项目目录，在这里你可以直接编辑文件）、暂存区（工作区和本地仓库之间的缓冲区域，用于准备下一次提交）、本地仓库（Git 在你的计算机上存储项目完整历史记录的地方）、远程仓库（托管在服务器上的项目版本，用于团队协作和备份），下面是他们之间的关系。

操作	作用	影响范围
git add	将工作区改动添加到暂存区	工作区 → 暂存区
git commit	将暂存区内容永久保存到本地仓库	暂存区 → 本地仓库
git push	将本地提交同步到远程仓库	本地仓库 → 远程仓库
git pull	拉取远程更新（自动合并）	远程仓库 → 工作区
git fetch	仅下载远程更新，不自动合并	更新远程分支引用

同时，git有一些基本概念：

仓库（Repository）：包含项目的所有历史和配置，是一个被 Git 管理的特殊文件夹，github的每一个工程都是一个仓库，可以用git clone直接下载到本地。且每个开发者本地都有完整的仓库副本（含完整历史），对应git commit之后的本地仓库。同时也有一个远程仓库，就是在github网页上看到的那些，用户可以在本地编辑完成后，提交到远程仓库。

变更（Change）是指代码库中文件内容或结构的任何修改，是版本控制的基本操作单元。当你修改了工作区的任何一个地方，就会产生变更。

提交（Commit）：用于保存当前暂存区中的所有变更，形成可追溯的版本链。通过git commit 可以完成这个动作，从而保存一个变更。

分支（Branch）：是仓库的一个独立的开发线程，它允许开发者在仓库的某个特定版本基础上进行开发，而不影响其他分支的代码。每个分支都有自己的提交历史链，记录了该分支上的所有变更。本质是指向某个提交的可变指针。

（3）Git 核心操作流程

1. 创建/克隆仓库

# 本地新建仓库
mkdir my-project && cd my-project
git init

# 克隆远程仓库（如 GitHub）
git clone https://github.com/用户名/仓库名.git

2. 日常开发循环

# 查看当前状态（随时使用）
git status

# 添加文件到暂存区（打包要提交的内容）
git add 文件名            # 添加单个文件
git add .                # 添加所有修改

# 提交到本地仓库（创建存档点）
git commit -m "描述修改内容"  # 简明扼要的提交信息

#关联远程仓库，在此之前先创建仓库
git remote add origin https://github.com/你的用户名/仓库名.git
# 或 SSH 地址（如 git@github.com:你的用户名/仓库名.git）

# 首次推送代码并建立分支追踪（-u 参数只需第一次使用）
git push -u origin main
# 如果本地默认分支是 master，则替换 main 为 master

# 正常使用时，推送代码到远程仓库（分享你的修改）
git push origin 分支名

创建仓库教程：点击github主页，点击右上角+，选择New repository，创建仓库。填写仓库名称，必须全英文，不要出现中文。然后选择开源协议（具体见下文）并点击创建。

完成代码上传

3. 同步他人代码

# 拉取远程最新代码
git pull origin 分支名

# 如果遇到冲突：
# 1. 手动解决冲突文件中的 <<<<<<< 标记
# 2. 重新添加并提交
git add 冲突文件
git commit -m "解决合并冲突"

（4）分支管理（多人协作核心）

1. 创建与切换分支

git branch                  # 查看所有分支
git branch 新分支名         # 创建新分支
git checkout 分支名         # 切换分支
git checkout -b 新分支名    # 创建并切换（常用！）

2. 合并分支（示例：将 feature 分支合并到 master）

git checkout master         # 先切换到主分支
git merge feature           # 合并 feature 分支
git push origin master      # 推送合并结果

3. 处理合并冲突

当多人修改同一文件时会出现冲突：

<<<<<<< HEAD
你的代码
=======
别人的代码
>>>>>>> branch-name

<<<<<<< HEAD 到 ======= 之间是你当前的代码。
======= 到 >>>>>>> branch-name 之间是他人提交的代码。

选择保留的代码：

- 方案一：完全保留你的代码，删除别人的代码。
- 方案二：完全保留别人的代码，删除你的代码。
- 方案三：手动合并两者（例如保留双方的功能）。

删除冲突标记：

- 最终文件中不能留下 <<<<<<</=======/>>>>>>> 这些标记

避免冲突的策略：

频繁拉取更新。git pull origin main # 每天开始工作前先同步

小步提交。将大功能拆分成小提交，减少重叠修改。

沟通协作。与团队成员约定不同人负责不同文件/模块。

查看合并历史：

git log --merge -p # 显示导致冲突的提交差异

紧急情况处理：

如果冲突解决错误，可回退到冲突状态

git merge --abort    # 终止合并
git rebase --abort   # 终止 rebase

（5）必备技巧

1. 撤销操作

# 撤销工作区修改（危险！不可恢复）
git checkout -- 文件名

# 撤销暂存区文件
git reset HEAD 文件名

# 修改最后一次提交
git commit --amend

2. 查看历史

git log                 # 详细提交历史
git log --oneline       # 简洁版历史
git log --graph         # 图形化分支结构

3. `.gitignore` 文件

创建 .gitignore 文件，列出不需要跟踪的文件：

# 示例
*.log
node_modules/
.DS_Store

（6）协作开发方法

1.分支策略

- master 分支：仅存放稳定代码
- dev 分支：日常开发集成
- feature/xxx：新功能开发分支

2.提交规范

参考后续的“三、一种提交规范”

type(scope): subject
// 示例
feat(auth): 添加用户登录功能
fix(api): 修复数据接口500错误

3.协作流程

# 标准操作流程
git checkout -b feature/new-login   # 创建特性分支，feature/ 前缀表示功能开发，new-login 描述功能内容

开发代码 -> 测试 -> 提交

git push origin feature/new-login    # 推送分支

# 然后在 GitHub/GitLab 创建 Pull Request

git push --force origin master
# 强制推送到主分支

# 然后在 GitHub/GitLab 创建 Pull Request。这个是什么意思呢？

关于Pull Request (PR) / Merge Request (MR)：

PR（GitHub）/MR（GitLab）是代码变更的评审请求机制，它：

提供代码差异对比
支持团队讨论
触发自动化检查
控制代码合并流程

在提交后通常会自动生成，比如：

也可以手动创建：

导航到仓库 → Pull requests → New pull request，

或者直接访问https://github.com/[用户名]/[仓库名]/compare

关键字段详解：

字段	说明	示例值
Base	要合并到的目标分支（通常是主分支）	`main` 或 `master`
Compare	包含你的修改的源分支	`feature/new-login`
Title	简明描述变更内容（遵循约定式提交更佳）	`feat: 新增登录页验证`
Description	详细说明修改内容和影响（Markdown 支持）	见下文模板

PR 描述模板（最佳实践）:

## 🛠 变更类型
- [ ] 新功能
- [x] Bug修复
- [ ] 代码重构
- [ ] 文档更新

## 📝 功能说明
• 实现基于JWT的登录验证  
• 添加邮箱格式校验功能  
• 优化移动端布局响应式

## 🧪 测试要点
1. 不同浏览器测试：
   - Chrome 最新版
   - Safari 15+
2. 特殊用例验证：
   - 超长邮箱地址处理
   - 特殊字符密码输入

## 📸 效果截图（可选）
| 桌面端 | 移动端 |
|--------|--------|
| ![桌面](url) | ![移动](url) |

## 🔗 相关资源
- 需求文档：[链接](#)
- 设计稿：[Figma链接](#)

合并选项：

合并方式	适用场景
Create merge commit	保留完整历史记录
Squash and merge	合并为单个提交（适合小修改）
Rebase and merge	保持线性历史（需谨慎使用）

本地预览PR：

# 获取他人PR到本地查看
git fetch origin pull/ID/head:pr-branch
git checkout pr-branch

（7）常见问题速查

问题	解决方案
提交了错误文件	`git reset HEAD~1` 回退到上一个提交
误删分支	`git reflog` 查找提交哈希后恢复
忘记切换分支直接修改	`git stash` 暂存当前修改，切换分支后 `git stash pop`

（8）VSCode git工具

VS Code 内置了 Git 工具

核心功能：

- 可视化文件状态（已修改/暂存/未跟踪）
- 行级差异对比
- 提交界面集成（支持提交信息模板）
- 分支切换和合并操作

点击更改栏 “+”，将所有改动加入到 “暂存的更改”（缓冲区）

“+” 旁边的返回键是撤销所有文件所有修改

可以在消息栏写上提交消息并提交

点击左下角“图形”里的提交记录，可以查看对比，背景颜色越深表示修改的越早。

该工具右上角也有许多功能，基本将git指令都实现了，当你阅读了上述的基础介绍，应该能判断分别对应的哪一条指令。

点击右上角工具栏show commit graph，可以看到详细提交记录图表。

此外，当项目绑定上git后，文件可能会显示不同颜色，在右边会有字母，类似于：

具体含义如下：

U Untracked 绿色

表示该文件是未被Git跟踪的文件，Git不会自动将其包含在版本控制中。这意味着该文件不会被提交到版本库中，也不会被包含在Git的快照中。如果希望Git开始跟踪该文件，需要使用git add命令将其添加到暂存区，然后文件的状态会从U（Untracked）变为A（Added）。

A Added 绿色

表示该文件是新添加的文件，已经被Git跟踪，并且将会包含在下一次的提交中。当使用git add命令将新文件添加到暂存区后，文件的状态会从U（Untracked）变为A（Added）。

M Modified 黄色

表示该文件已被修改。当对已跟踪的文件进行了修改后，文件的状态会从A（Added）变为M（Modified）。这意味着该文件在上一次提交之后发生了变化，但尚未被添加到暂存区。

（9）开源协议

GitHub 上的开源许可证（License）定义了其他人如何使用、修改和分发你的项目。以下是你github所有的分支介绍：

None：不选择任何许可证。这意味着你的代码没有明确的开源许可，其他人在使用你的代码时可能需要额外的许可。
Apache License 2.0：这是一个宽松的许可证，允许用户自由使用、修改和分发代码，无论是商业用途还是非商业用途。它还提供了专利授权，以保护贡献者免受专利诉讼。
GNU General Public License v3.0 (GPLv3)：这是一个自由软件许可证，要求任何衍生作品也必须在相同或兼容的许可证下发布。GPLv3 旨在保护软件用户的自由，确保他们有权运行、学习、共享和修改软件。
MIT License：这是一个非常宽松的许可证，允许用户自由使用、修改和分发代码，包括商业用途。它只需要在分发的代码中包含原始版权声明和许可证文本。
BSD 2-Clause "Simplified" License：这是一个宽松的许可证，允许用户自由使用、修改和分发代码，包括商业用途。它只需要在分发的代码中包含版权声明。
BSD 3-Clause "New" or "Revised" License：与两条款 BSD 许可证类似，但增加了一个条款，要求在广告中提及原始作品时不能暗示作者或机构对修改后的作品的认可。
Boost Software License 1.0：这是一个宽松的许可证，允许用户自由使用、修改和分发代码，包括商业用途。它不需要包含版权声明，但要求在分发的代码中包含许可证文本。
Creative Commons Zero v1.0 Universal (CC0)：这不是一个传统的软件许可证，而是一个放弃版权的声明。它允许用户自由使用、修改和分发作品，没有任何条件，甚至不需要署名。
Eclipse Public License 2.0 (EPL 2.0)：这是一个开源许可证，允许自由使用、修改和分发代码。它要求衍生作品也必须在 EPL 2.0 下发布。EPL 2.0 还包含了一些关于专利的条款，以保护贡献者。
GNU Affero General Public License v3.0 (AGPLv3)：这是 GPL 的一个变种，特别适用于网络服务。它要求如果通过网络提供服务，那么服务的源代码也必须公开。AGPLv3 旨在确保用户即使在使用在线服务时也能享有自由软件的四项基本自由。
GNU General Public License v2.0 (GPLv2)：这是最早的 GPL 版本，要求任何衍生作品也必须在相同或兼容的许可证下发布。GPLv2 保护了用户运行、学习、共享和修改软件的权利。
GNU Lesser General Public License v2.1 (LGPLv2.1)：这是一个宽松版本的 GPL，适用于库文件。它允许库文件被包含在非自由软件中，只要库文件本身遵循 LGPL 条款。LGPLv2.1 旨在促进库文件的共享和重用。
Mozilla Public License 2.0 (MPL 2.0)：这是一个开源许可证，旨在平衡贡献者和用户的权利。它允许代码被用于任何目的，包括商业用途，但要求任何修改和分发的代码也必须遵循 MPL 2.0。MPL 2.0 还包含了一些关于专利的条款。
The Unlicense：这是一个放弃版权的声明，允许任何人自由使用、修改和分发作品，没有任何条件。它旨在将作品置于公共领域，允许最广泛的使用和分发。

以上和github创建仓库时的选择协议下拉框一一对应：

（10）上传exe文件供别人下载

在 GitHub 上加入 .exe 文件（或其他二进制文件）通常有以下几种方法：

方法 1：直接上传（适用于小型项目）

进入你的 GitHub 仓库，点击 Add file → Upload files。
将 .exe 文件拖放到上传区域，或手动选择文件。
填写提交信息（Commit message），点击 Commit changes。

适用场景：偶尔上传小型 .exe 文件（<100MB）。
缺点：大文件会导致仓库体积膨胀（Git 不适合存储二进制文件的历史版本）。

方法 2：使用 Git LFS（推荐用于大型文件）

Git LFS（Large File Storage）是 GitHub 官方支持的扩展工具，专为管理大文件（如 .exe、.dll、.zip 等）设计。

步骤：

安装 Git LFS：

# Windows（需先安装 Git）
git lfs install

- macOS/Linux 同样通过 git lfs install 安装。

在仓库中启用 LFS：

# 进入你的本地仓库目录
cd your-repo
git lfs track "*.exe"  # 指定跟踪所有 .exe 文件

提交 LFS 配置：

git add .gitattributes  # 自动生成的配置文件
git commit -m "track .exe files with LFS"
git push origin main    # 推送配置

添加并提交 .exe 文件：

git add your-file.exe
git commit -m "add executable"
git push origin main

优点：

避免仓库体积爆炸。
支持版本控制，但只保存最新版本的二进制文件（历史版本存储在 GitHub 服务器）。

方法 3：通过 Releases 发布（推荐正式版本分发）

GitHub Releases 适合分发编译后的程序（如软件的安装包或稳定版 .exe）。

步骤：

进入仓库 → Releases → Draft a new release。
填写版本号（如 v1.0.0）和标题。
将 .exe 文件拖到 “Assets” 区域上传。
发布后，用户可直接从 Releases 页面下载，无需克隆仓库。

优点：

独立于代码仓库，不占用仓库空间。
提供清晰的版本管理和下载链接（如 https://github.com/用户名/仓库/releases）。

二、用git协作开发

（1）、基础 Git 操作流程

1. 初始化仓库（若为新项目）

git init
git add .
git commit -m "feat: 项目初始化"
git remote add origin https://github.com/yourname/project.git
git push -u origin master

2. 开发新功能/策略的完整流程

# 从 master 创建新分支（分支命名规范）
git checkout -b feature/strategy-momentum master

# 开发代码...
vim strategies/momentum.py

# 提交原子化修改（Atomic Commits）
git add strategies/momentum.py
git commit -m "feat(strategies): 添加动量策略基础框架"

# 同步远端分支（首次推送）
git push -u origin feature/strategy-momentum

# 开发完成后触发测试（本地验证）
pytest tests/strategies/test_momentum.py

（2）、分支合并与冲突处理

1. 合并前准备（关键步骤）

# 切换到 master 获取最新代码
git checkout master
git pull origin master

# 回到特性分支进行变基（Rebase）
git checkout feature/strategy-momentum
git rebase master

# 解决可能出现的冲突（示例）：
# 1. 用编辑器手动解决冲突文件
# 2. 标记冲突已解决
git add conflicted_file.py
git rebase --continue

# 强制推送更新分支（慎用！）
git push -f origin feature/strategy-momentum

2. 发起合并请求（Pull Request/Merge Request）

# GitHub 环境
gh pr create --base master --head feature/strategy-momentum --title "feat: 新增动量策略"

# GitLab 环境
git push origin feature/strategy-momentum
# 然后通过 Web 界面创建 Merge Request

3. Code Review 后合并

# 管理员操作（保护分支时需通过 PR/MR）
git checkout master
git merge --no-ff feature/strategy-momentum
git push origin master

# 清理旧分支
git branch -d feature/strategy-momentum
git push origin --delete feature/strategy-momentum

（3）、高级协作技巧

1. 使用 `.gitattributes` 避免无意义冲突

# 文件示例：.gitattributes
*.ipynb merge=union   # 保留双方修改（Jupyter Notebook）
*.json merge=union    # JSON 配置文件合并策略
*.md diff=markdown    # 指定 Markdown 差异显示方式

2. 通过 `pre-commit` 规范代码

# 文件示例：.pre-commit-config.yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
  rev: v4.3.0
  hooks:
    - id: trailing-whitespace
    - id: end-of-file-fixer
    - id: check-yaml
- repo: https://github.com/psf/black
  rev: 22.10.0
  hooks:
    - id: black

3. 利用 Git Hooks 自动化

# 示例：添加 pre-push 钩子检查测试
vim .git/hooks/pre-push

#!/bin/sh
# 阻止未通过测试的推送
if ! pytest --cov=strategies tests/; then
  echo "测试未通过！禁止推送"
  exit 1
fi
chmod +x .git/hooks/pre-push

（4）、可视化工作流示意图

Master 分支
│
├── feature/strategy-A (开发者A)
│   ├── commit: "feat: 策略A基础框架"
│   └── commit: "fix: 修复策略A边界条件"
│
├── feature/strategy-B (开发者B)
│   ├── commit: "feat: 初始化策略B"
│   └── commit: "docs: 添加策略B API说明"
│
└── hotfix/issue-123 (紧急修复)
    └── commit: "fix: 解决数据加载异常"

（5）、常见问题解决方案

场景1：多人同时修改同一文件

# 先 stash 本地修改
git stash

# 拉取远端最新代码
git pull origin master

# 恢复本地修改并解决冲突
git stash pop
# 手动解决冲突后提交
git add .
git commit -m "fix: 合并冲突"

场景2：误操作分支恢复

# 查看 reflog 找到丢失的 commit
git reflog

# 重置到指定提交（示例）
git reset --hard HEAD@{5}

场景3：拆分大文件提交

# 交互式重置（保留修改）
git reset HEAD~3 --soft

# 分批次提交
git add src/strategies/part1.py
git commit -m "feat: 策略模块第一部分"
git add src/strategies/part2.py
git commit -m "feat: 策略模块第二部分"

（6）、推荐工具链

1. GUI 客户端：

- Fork（macOS/Windows）
- GitKraken（全平台）

2. 命令行增强：

# 安装增强工具
brew install git-extras tig

# 常用别名配置（~/.gitconfig）
[alias]
    st = status -sb
    lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset'
    undo = reset HEAD~1 --mixed

三、一种提交规范

（1）基本介绍

Conventional Commits 规范

Conventional Commits 是一种标准化的 Git 提交信息格式，它提供了一套简单的规则来创建明确的提交历史。

当使用 git commit 时，按照规范格式编写提交信息：

git commit -m "feat: add user authentication"

或使用编辑器编写更详细的提交信息：

git commit
# 然后在编辑器中输入：
# feat(auth): add JWT authentication
#
# Added JWT token generation and verification middleware
# 
# BREAKING CHANGE: Changes authentication mechanism from session-based to JWT

参考链接：

Conventional Commits

（2）提交信息的格式

Conventional Commits 规范定义了提交信息的格式，通常包含三个部分：

复制

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

1. 类型（Type）

类型是一个简短的单词，用于描述提交的性质。常见的类型包括：

feat：新功能（feature）
fix：修复错误（bug fix）
docs：文档更新
style：代码格式化（不影响代码运行的变动，如空格、分号等）
refactor：代码重构（既不是新功能也不是修复错误）
test：添加测试或更新测试
chore：构建过程或辅助工具的变动（如配置文件的更新）

2. 作用域（Scope）

作用域是可选的，用于指定提交影响的范围。它可以是一个文件名、模块名或功能区域。例如：

feat: add new feature to user profile

或者

feat(user-profile): add new feature

3. 描述（Description）

描述是提交信息的核心部分，应该简洁明了地说明这次提交的主要内容。例如：

feat: add new feature to user profile

4. 详细说明（Body）

详细说明是可选的，用于提供更详细的上下文信息。例如：

复制

feat: add new feature to user profile

This commit adds a new feature that allows users to update their profile information.

5. 脚注（Footer）

脚注是可选的，通常用于提供额外的信息，如关闭的 Issue 或相关的提交。例如：

复制

feat: add new feature to user profile

This commit adds a new feature that allows users to update their profile information.

Closes #123

（3）示例

以下是一些符合 Conventional Commits 规范的提交信息示例：

feat: add new feature to user profile
fix: fix bug in user authentication
docs: update README with new instructions
style: fix formatting in main.js
refactor: simplify user profile component
test: add tests for new feature
chore: update build script

（4）为什么使用 Conventional Commits？

一致性：团队成员可以以一致的方式编写提交信息，便于理解和协作。
自动化：工具可以解析提交信息，自动生成变更日志（CHANGELOG）或自动化版本控制。
语义化版本控制：通过提交信息的类型，可以自动推断版本号的变更（如 feat 对应 minor 版本，fix 对应 patch 版本）。

四、关于readme文档：

readme文档一般用MD语法编写。

我已经为工程编写了相关的readme文档：

以下是 Markdown（MD）常见语法详解，包含基础到进阶的用法示例：

标题

# 一级标题（H1）
## 二级标题（H2）
### 三级标题（H3）
#### 四级标题（H4）

段落与换行

这是第一段（末尾加两个空格表示换行）  
这是同一段的第二行

这是新段落（空一行分隔）

注意：普通换行需在行尾加 两个空格，或段落间空一行。

文字样式

*斜体* 或 _斜体_  
**粗体** 或 __粗体__  
***粗斜体*** 或 ___粗斜体___  
~~删除线~~  
`行内代码`

列表

1. 无序列表

- 项目1
- 项目2
  - 子项目（缩进2或4空格）
* 也可用星号

2. 有序列表

1. 第一项
2. 第二项
   1. 子项（缩进对齐上级数字）

链接与图片

[链接文字](https://example.com "可选标题")

![图片描述](图片路径/图片.png "可选标题")

代码块

1. 行内代码

`单行代码`

2. 多行代码块

```python
# 指定语言高亮
def hello():
    print("Markdown!")
```

表格

| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:-------:|-------:|
| 单元格 | 单元格  | 单元格 |
| **加粗** | `代码` | ~~删除~~ |

引用

> 这是引用内容  
> 多行需每行加 `>`
>> 嵌套引用

分割线

--- 或 *** 或 ___

进阶语法

1. 任务列表（GitHub扩展）

- [x] 已完成
- [ ] 未完成

2. 脚注

这是一个脚注示例[^note]

[^note]: 这里是脚注内容

3. 内嵌HTML（部分支持）

<details>
<summary>点击展开</summary>
隐藏的内容
</details>

转义字符

用 \ 转义特殊字符：

\* 正常显示星号而不是斜体

流程图（mermaid扩展语法）

```mermaid
graph LR
    A[开始] --> B{条件}
    B -->|是| C[执行]
    B -->|否| D[结束]
```

兼容性说明

基础语法（标题、列表等）全平台通用（GitHub、Typora、VS Code等）
流程图、任务列表等需特定渲染器支持（如GitHub、Obsidian）

掌握这些语法后，可以高效编写文档、README、技术博客等！

在VSCode编写md文档

在vscode中，推荐用插件Markdown All in one

按Ctrl+Shift+V就能显示预览

以下是基本使用方法：

1.快捷键大全：

快捷键	功能
Ctrl+Shift+V	显示预览
`Ctrl+B`	加粗选中文本
`Ctrl+I`	斜体选中文本
`Alt+S`	添加删除线
`Ctrl+Shift+]`	提升标题级别（如 H2→H1）
`Ctrl+Shift+[`	降低标题级别（如 H1→H2）
`Alt+C`	切换任务列表勾选状态
`Alt+Shift+F`	格式化表格对齐

2. 目录生成

在文档中输入 [toc] 并保存，自动生成目录13。
或通过命令面板（Ctrl+Shift+P）搜索 Create Table of Contents 手动生成3。

3. 实时预览

分屏预览：Ctrl+Shift+V 或右键选择 Open Preview to the Side47。
同步滚动：预览窗口与编辑窗口内容实时同步。

4. 表格与列表优化

表格格式化：选中表格后按 Alt+Shift+F 自动对齐23。
任务列表：输入 - [ ] 创建待办项，Alt+C 切换完成状态27。

5. 数学公式支持

行内公式： $E=mc^2$

块级公式：

$$
\sum_{i=1}^n a_i=0
$$

6.自动补全

- 输入 [ 自动补全链接格式，! 补全图片插入语法35。
- 引用链接：[text][id] + 底部定义 [id]: url。

7.代码块管理

- 使用 ```语言指定语法高亮（如 ```python）56。
- 快捷键 Ctrl+Shift+K 快速插入代码块10。

8.导出与协作

- 通过插件 Markdown Preview Enhanced 导出为 HTML/PDF15。
- 结合 GitLens 管理版本历史1。

五、`.gitignore` 文件详解

.gitignore 是一个纯文本文件，用于 告诉 Git 哪些文件或目录应该被忽略，不纳入版本控制。它通常放置在 Git 仓库的根目录下。

1. 为什么需要 `.gitignore`？

避免提交无关文件（如临时文件、日志、编译产物等）
减少仓库体积（二进制文件、依赖库等无需版本控制）
保护敏感信息（如配置文件中的密码、API 密钥）

2. 基本语法规则

(1) 匹配单个文件

# 忽略根目录下的 `debug.log`
debug.log

(2) 匹配特定目录下的文件

# 忽略 `logs/` 目录下的所有文件
logs/

(3) 通配符匹配

# 忽略所有 `.tmp` 文件
*.tmp

# 忽略所有 `.log` 文件，但 `important.log` 除外
*.log
!important.log

(4) 注释

# 这是一个注释，不会被 Git 解析

(5) 忽略特定路径的文件

# 仅忽略根目录下的 `temp.txt`，不忽略子目录的
/temp.txt

(6) 递归匹配

# 忽略所有目录下的 `node_modules/`
**/node_modules/

3. 常见用例

(1) 忽略操作系统临时文件

# macOS
.DS_Store

# Windows
Thumbs.db

(2) 忽略开发环境文件

# IDE 配置文件（如 VS Code、IntelliJ）
.vscode/
.idea/

# Python
__pycache__/
*.py[cod]

(3) 忽略编译产物

# C/C++
*.o
*.out

# Java
*.class
*.jar

(4) 忽略依赖目录

# Node.js
node_modules/

# Python
venv/

(5) 忽略敏感信息

# 配置文件（如 `.env` 含 API 密钥）
.env
*.secret

4. 高级用法

(1) 全局 `.gitignore`

如果你希望所有 Git 项目都忽略某些文件（如 .DS_Store），可以配置全局忽略：

git config --global core.excludesfile ~/.gitignore_global

然后在 ~/.gitignore_global 里添加规则。

(2) 强制添加被忽略的文件

即使文件在 .gitignore 里，也可以强制添加：

git add -f secret-file.txt

(3) 检查哪些文件被忽略

git check-ignore -v some-file.txt

5. 注意事项

`.gitignore` 只对未跟踪的文件生效

- 如果文件已经被 Git 跟踪（git add 过），即使后来添加到 .gitignore，Git 仍会继续跟踪它。

解决方法：

git rm --cached file-to-ignore.txt

`.gitignore` 文件本身需要提交

git add .gitignore
git commit -m "Add .gitignore"

6. 示例 `.gitignore` 文件

# 操作系统文件
.DS_Store
Thumbs.db

# 开发工具
.vscode/
.idea/

# 日志和缓存
*.log
*.tmp
__pycache__/

# 依赖管理
node_modules/
venv/

# 敏感数据
.env
*.key

7.总结

功能	示例
忽略文件	`*.log`
忽略目录	`logs/`
排除例外	`!important.log`
全局忽略	`git config --global core.excludesfile`
强制添加	`git add -f`