1. 什么是代码版本管理#

代码版本管理，也叫版本控制，是对项目文件变化进行记录、比较、回退、审查和协作管理的过程。

它不是简单地“备份一份代码”，而是把软件开发中的每一次有效变更都整理成可追踪的历史记录。通过版本管理，团队可以知道代码从哪里来、为什么变成现在这样、某个问题是从哪次修改开始出现的，以及需要时如何恢复到某个稳定状态。

可以把代码版本管理理解为软件项目的“时间线系统”：

1
初始代码 -> 第一次提交 -> 第二次提交 -> 修复 bug -> 新增功能 -> 发布版本

每一个节点都记录了项目在某个时刻的状态。

1. 版本管理到底管理什么

版本管理工具通常管理的不只是代码文件，还包括和项目交付有关的文本型工程资产。

常见管理对象：

• 源代码：如 .kt、.java、.py、.js、.cpp
• 配置文件：如 yml、json、xml、properties
• 构建脚本：如 Gradle、Maven、Makefile
• 文档：如 README.md、接口文档、设计文档
• 测试代码：单元测试、集成测试、自动化测试脚本
• 脚本工具：部署脚本、数据迁移脚本、辅助工具
• 项目元信息：依赖版本、CI/CD 配置、代码规范配置

一般不建议直接用普通 Git 仓库管理频繁变化的大型二进制文件，例如：

• 视频
• 大型图片源文件
• 模型文件
• 编译产物
• 压缩包
• 临时缓存

这类文件要么放到制品仓库，要么使用 Git LFS、对象存储或专门的资产管理系统。

2 版本管理解决的核心问题

它解决的问题包括：

• 谁改了代码
• 什么时候改的
• 为什么改
• 改了哪些文件
• 如何回到旧版本
• 多人同时开发如何合并
• 如何把开发、测试、发布流程串起来

这些问题背后，其实对应软件工程中的几个核心能力：

3. 为什么不能只靠复制文件备份

很多初学者一开始会用复制文件夹的方式保存版本：

1
project/
2
project_backup/
3
project_2026_07_16/
4
project_final/
5
project_final_2/

这种方式看起来简单，但很快会失控。

主要问题：

• 不知道每个版本具体改了什么
• 不知道哪个版本是稳定的
• 不知道某个 bug 是什么时候引入的
• 多人协作时无法合并修改
• 文件夹越来越多，命名越来越混乱
• 很难只回退某一次局部修改

版本控制系统相比普通备份的关键区别是：

所以，备份解决的是“文件丢了怎么办”，版本管理解决的是“软件如何持续演进并保持可控”。

4. 版本管理在开发流程中的位置

版本管理贯穿软件研发全过程。

典型流程：

1
需求提出
2
  -> 创建分支
3
  -> 编写代码
4
  -> 本地提交
5
  -> 推送远程仓库
6
  -> 创建 PR/MR
7
  -> 代码审查
8
  -> 自动化测试
9
  -> 合并主分支
10
  -> 打 tag 发布
11
  -> 线上问题追踪和回滚

在这个流程里，Git 不只是保存代码，它连接了需求、开发、测试、评审、发布和维护。

例如：

• Issue 描述需求或 bug
• Branch 隔离开发任务
• Commit 记录具体变更
• Pull Request 组织评审
• CI 验证代码质量
• Tag 标记发布版本
• Revert 处理线上回滚

5. 代码版本管理的工程价值

对个人开发者:

版本管理可以帮助个人开发者：

• 保存每个阶段的进度
• 不怕大胆重构
• 快速回退错误修改
• 对比自己的改动
• 整理学习和项目历史

比如做实验性重构时，可以先提交一个稳定版本，再放心修改。如果改坏了，随时回退。

对团队协作

版本管理可以帮助团队：

• 分工开发
• 合并代码
• 审查变更
• 避免覆盖彼此工作
• 统一发布节奏
• 追踪线上问题来源

在团队中，版本管理不是可选项，而是基础设施。

对项目交付

版本管理可以支撑：

• 自动化构建
• 自动化测试
• 自动化部署
• 版本发布
• 回滚方案
• 变更日志生成

现代 CI/CD 基本都依赖 Git 事件，例如：

• push 触发测试
• PR 触发代码检查
• tag 触发发布
• main 分支合并触发部署

6. 学习版本管理时要建立的思维

学习版本管理，不要只背命令，而要建立几个思维：

1. 每次提交都应该表达一个明确目的。
2. 分支是隔离工作内容的工具。
3. 提交历史是项目的工程档案。
4. 公共历史要谨慎修改。
5. 主分支应该尽量保持稳定。
6. 版本发布要有明确标记。
7. 提交信息应该能解释变更原因。

后面学习 Git 命令、分支策略和 Commit Message 规范，本质上都是围绕这些思维展开。

2. 版本控制系统分类#

版本控制系统可以按架构和协作方式分为三类：

• 本地版本控制
• 集中式版本控制
• 分布式版本控制

这三类不是简单的新旧替代关系，而是代表了不同阶段的软件协作方式。

1
project_v1.zip
2
project_v2.zip
3
project_final.zip
4
project_final_final.zip

1
本地文件 -> 本地版本记录 -> 本地恢复

1
开发者 A  \
2
开发者 B   -> 中央版本库 -> 统一保存历史
3
开发者 C  /

1
从服务器 checkout/update
2
  -> 本地修改
3
  -> 解决可能的冲突
4
  -> commit 到中央服务器

1
svn checkout <repo-url>
2
svn update
3
svn commit -m "fix login validation"

1
开发者 A 本地完整仓库 <-> 远程仓库
2
开发者 B 本地完整仓库 <-> 远程仓库
3
开发者 C 本地完整仓库 <-> 远程仓库

1
clone 远程仓库
2
  -> 本地创建分支
3
  -> 本地多次 commit
4
  -> push 到远程
5
  -> 创建 PR/MR
6
  -> review 后合并

1
git clone <repo-url>
2
git switch -c feature/login
3
git add .
4
git commit -m "feat(auth): add login validation"
5
git push -u origin feature/login

3. 常见代码管理工具#

代码管理工具可以分成两类：

1. 版本控制工具：负责记录代码历史，例如 Git、SVN、Mercurial。
2. 代码托管与协作平台：基于版本控制工具提供远程仓库、评审、Issue、CI/CD 等能力，例如 GitHub、GitLab、Gitee、Bitbucket。

这两类经常被混在一起说，但它们不是一回事。

1
Git        = 版本控制工具
2
GitHub     = 基于 Git 的代码托管和协作平台
3
GitLab     = 基于 Git 的代码托管和 DevOps 平台
4
Gitee      = 基于 Git 的国内代码托管平台
5
Bitbucket  = 基于 Git 的代码托管平台

工具总览

注意：

Git 是版本控制工具。
GitHub、GitLab、Gitee 是基于 Git 的代码托管和协作平台。

1
git init
2
git clone <url>
3
git status
4
git add .
5
git commit -m "feat: add feature"
6
git branch
7
git switch -c feature/demo
8
git merge feature/demo
9
git push
10
git pull

1
svn checkout <repo-url>
2
svn update
3
svn status
4
svn add file.txt
5
svn commit -m "update document"

1
hg clone <url>
2
hg status
3
hg add
4
hg commit -m "update"
5
hg push
6
hg pull

1
版本控制工具：Git
2
代码托管平台：GitHub / GitLab / Gitee
3
本地操作方式：Git CLI + IDE Git 工具

4. Git 是什么#

Git 是一个分布式版本控制系统，最初由 Linus Torvalds 为 Linux 内核开发。

它的主要任务是记录项目历史，并让开发者可以高效地进行分支开发、合并协作、版本回退和发布管理。

一句话理解：

1
Git = 用提交记录管理项目演进历史的分布式版本控制工具

Git 解决的核心问题

Git 主要解决软件开发中的这些问题：

• 如何记录每次代码变更
• 如何知道代码是谁改的
• 如何比较两个版本的差异
• 如何回退错误修改
• 如何支持多人并行开发
• 如何隔离不同功能开发
• 如何把多个分支的代码合并起来
• 如何标记发布版本
• 如何让代码历史可审查、可追踪

它不是项目管理工具，也不是代码托管平台。
Git 本身只负责版本控制；GitHub、GitLab、Gitee 这类平台才负责远程协作、PR、Issue、CI/CD 等能力。

Git 的核心特点

Git 的核心特点：

• 分布式
• 分支轻量
• 本地操作快
• 数据完整性强
• 支持非线性开发
• 适合大型协作项目

这些特点决定了 Git 特别适合现代软件工程。

1. 分布式

每个开发者本地都有一份完整仓库历史。

这意味着：

• 本地可以提交
• 本地可以查看日志
• 本地可以创建分支
• 本地可以回退版本
• 没有网络也能继续开发

远程仓库只是协作中心，不是唯一的历史保存点。

2. 分支轻量

Git 的分支本质上是指向某个提交的指针。

创建分支非常快：

1
git switch -c feature/login

这让 Git 很适合：

• 一个需求一个分支
• 一个 bugfix 一个分支
• 一个实验一个分支
• 一个发布版本一个分支

3. 本地操作快

大部分 Git 操作都在本地完成，例如：

1
git status
2
git log
3
git diff
4
git branch
5
git commit

这些命令通常不需要访问远程服务器。

4. 数据完整性强

Git 用哈希值标识对象和提交。

每一次提交都有一个类似这样的提交 ID：

1
a1b2c3d4e5f6...

这个 ID 和提交内容相关。内容变化后，哈希也会变化。
因此 Git 能较好地保证历史记录不被无声篡改。

5. 支持非线性开发

Git 允许多个分支并行演进：

1
main:    A---B---C------F
2
              \        /
3
feature:       D---E---

这就是非线性开发。

它非常适合多人协作，因为每个人都可以在自己的分支上独立工作，最后再合并。

Git 记录的是快照，不只是差异

很多人以为 Git 只记录文件每次修改的差异。
实际上，Git 更像是在每次提交时保存项目的一份快照。

可以这样理解：

1
commit A = 项目在 A 时刻的完整状态
2
commit B = 项目在 B 时刻的完整状态
3
commit C = 项目在 C 时刻的完整状态

如果某个文件没有变化，Git 不会重复保存一份完整内容，而是复用已有对象。
所以 Git 既保留了快照模型的清晰性，又通过对象复用节省空间。

快照模型的好处：

• 容易回到某个历史版本
• 容易比较两个版本差异
• 容易创建分支
• 容易标记发布状态

Git 的基本工作模型

Git 的日常工作可以理解为四步：

1
修改 -> 暂存 -> 提交 -> 推送

对应命令：

1
git status
2
git add .
3
git commit -m "feat: add user profile"
4
git push

更完整的协作模型：

1
远程仓库
2
   ↓ clone / pull
3
本地仓库
4
   ↓ checkout / switch
5
工作区
6
   ↓ add
7
暂存区
8
   ↓ commit
9
本地仓库
10
   ↓ push
11
远程仓库

其中：

• clone：复制远程仓库到本地
• pull：拉取远程更新
• add：把修改放入暂存区
• commit：把暂存区内容记录为提交
• push：把本地提交推送到远程仓库

Git 与远程仓库的关系

Git 可以完全在本地使用，不一定必须连接 GitHub 或 GitLab。

例如：

1
git init
2
git add .
3
git commit -m "initial commit"

这已经是一个完整的本地 Git 仓库。

但是团队协作通常需要远程仓库：

• GitHub
• GitLab
• Gitee
• Bitbucket
• 自建 Git 服务

远程仓库的作用：

• 统一代码同步位置
• 支持多人协作
• 作为备份
• 支持 PR / MR
• 触发 CI/CD
• 管理权限

Git 适合管理什么

Git 适合管理：

• 源代码
• 配置文件
• Markdown 文档
• 测试脚本
• 构建脚本
• 小型文本资源

Git 不适合直接管理：

• 频繁变化的大型二进制文件
• 编译产物
• 临时缓存
• 日志文件
• 依赖下载目录
• 密钥和敏感配置

这些不适合 Git 管理的内容，通常应该放进：

• .gitignore
• Git LFS
• 制品仓库
• 对象存储
• 密钥管理系统

Git 的优势和代价

优势

Git 的主要优势：

• 速度快
• 分支灵活
• 离线可用
• 生态强大
• 支持复杂协作
• 支持代码审查和 CI/CD 流程
• 能精确追踪历史

代价

Git 的代价主要是学习曲线：

• 概念多
• 命令多
• reset、rebase、checkout 等命令容易误用
• 冲突处理需要经验
• 团队需要统一提交和分支规范

所以学 Git 时，不能只记命令，还要理解它背后的模型。

什么情况下不应该用 Git

Git 很强，但不是所有文件管理问题都应该用 Git 解决。

不适合 Git 的场景：

• 管理大量图片、视频、模型等大文件
• 管理每天自动生成的大量日志
• 管理数据库运行时数据
• 管理敏感密钥
• 替代网盘做普通文件同步
• 替代项目管理工具做需求排期

Git 的边界是：

1
适合管理可审查、可比较、可演进的项目文件。
2
不适合管理大量不可读、不可 diff、频繁变化的二进制数据。

初学需要理解

学习 Git 最重要的是先抓住这些核心关系：

1
工作区 -> 暂存区 -> 本地仓库 -> 远程仓库

然后理解：

• add 是选择下次提交内容
• commit 是保存一次历史
• branch 是创建独立开发线
• merge 是合并开发线
• rebase 是整理提交基底
• reset 是移动当前分支指针
• revert 是用新提交撤销旧提交
• push 是上传本地提交
• pull 是拉取并整合远程提交

后面的章节会围绕这些关系展开。

5. Git 的四大核心区域#

理解 Git，必须理解它的几个核心区域。

很多 Git 命令看起来复杂，本质上都是在这些区域之间移动文件状态。

最常见的三大区域是：

1
工作区 Working Tree
2
暂存区 Staging Area / Index
3
本地仓库 Local Repository

如果考虑团队协作，还要加上远程仓库：

1
工作区 -> 暂存区 -> 本地仓库 -> 远程仓库

对应命令：

1
修改文件 -> git add -> git commit -> git push

1
git status
2
git diff

1
Untracked files:
2
  notes.md

1
git add notes.md

1
git diff

1
git add file.txt

1
git restore file.txt

1
nothing to commit, working tree clean

1
git add <file>

1
工作区：我当前改了什么
2
暂存区：我准备把哪些改动放进下一次提交

1
git add file.txt
2
git add .
3
git add -p
4
git diff --cached
5
git restore --staged file.txt

1
git add src/login.kt
2
git commit -m "fix(auth): validate login token"
3

4
git add README.md
5
git commit -m "docs: update setup guide"
6

7
git add app/src/main/res/layout/login.xml
8
git commit -m "style(ui): adjust login button spacing"

1
git commit

1
git commit
2
git log
3
git show <commit>
4
git reset
5
git revert
6
git reflog

1
git show <commit>

1
git push

1
git commit = 写入本地历史
2
git push   = 推送到远程仓库

1
git remote -v
2
git fetch origin
3
git pull
4
git push
5
git push -u origin feature/login

1
origin -> 远程仓库地址

1
git remote -v

1
修改文件 -> git add -> git commit
2
工作区 -> 暂存区 -> 本地仓库

1
远程仓库
2
   ↓ git clone / git pull
3
本地仓库
4
   ↓ git switch / git checkout
5
工作区
6
   ↓ 修改文件
7
工作区变更
8
   ↓ git add
9
暂存区
10
   ↓ git commit
11
本地仓库
12
   ↓ git push
13
远程仓库

1
git add file.txt

1
git commit -m "fix: update file"

1
git push

1
git fetch

1
git pull

1
未跟踪 untracked
2
  -> git add
3
已暂存 staged
4
  -> git commit
5
已提交 committed
6

7
已提交 committed
8
  -> 修改文件
9
已修改 modified
10
  -> git add
11
已暂存 staged

6. 为什么 Git 需要暂存区#

暂存区的价值是精确控制：

1
下一次提交到底包含哪些修改

如果没有暂存区，Git 只能把工作区里的所有修改一次性提交。
这会让提交很容易变得混乱：修 bug、改样式、写文档、调试代码全部混在一个 commit 里。

暂存区的存在，让 Git 提交从“保存当前全部文件”变成“选择一组相关修改并保存为一次清晰提交”。

暂存区的本质

暂存区，也叫 Index。

它位于工作区和本地仓库之间：

1
工作区 Working Tree
2
   ↓ git add
3
暂存区 Staging Area / Index
4
   ↓ git commit
5
本地仓库 Local Repository

可以这样理解：

暂存区不是备份区，也不是远程仓库。
它只是下一次 commit 的“候选清单”。

没有暂存区会有什么问题

假设你在一次开发中同时做了这些事情：

• 修复登录 bug
• 调整登录按钮样式
• 更新 README
• 临时添加一行调试日志

如果没有暂存区，你可能只能一次性提交：

1
fix login and update docs and style

问题是：

• 提交目的不清楚
• 代码评审很难看
• 回滚时会把无关修改一起回滚
• 后续查 bug 很难定位
• 提交历史不可读

暂存区让你可以把这些修改拆成多个独立提交。

暂存区让提交更清晰

例如你同时做了三件事：

• 修复登录 bug
• 修改按钮样式
• 更新 README

它们最好拆成三次提交：

1
git add src/login.kt
2
git commit -m "fix(auth): validate login token"
3

4
git add app/src/main/res/layout/login.xml
5
git commit -m "style(ui): adjust login button spacing"
6

7
git add README.md
8
git commit -m "docs: update setup guide"

这样历史更清晰，也更容易回滚。

提交历史会变成：

1
fix(auth): validate login token
2
style(ui): adjust login button spacing
3
docs: update setup guide

比下面这种好得多：

1
update login page

暂存区支持部分提交

有时候同一个文件里也可能包含多个不同目的的修改。

例如 UserService.kt 里同时改了：

• 修复 token 校验
• 重命名一个变量
• 删除调试日志

如果直接：

1
git add UserService.kt

整个文件的修改都会进入暂存区。

如果想只选择其中一部分，可以使用：

1
git add -p UserService.kt

-p 表示 patch，Git 会把修改拆成小块，让你逐块选择是否暂存。

常见交互选项：

这对写出高质量提交非常重要。

暂存区支持提交前检查

暂存后，不要立刻提交。建议先看一下暂存区内容。

查看工作区未暂存差异：

1
git diff

查看已经暂存、即将提交的差异：

1
git diff --cached

也可以使用：

1
git diff --staged

--cached 和 --staged 在这个场景下基本等价。

推荐提交流程：

1
git status
2
git diff
3
git add -p
4
git diff --cached
5
git commit -m "fix(auth): validate login token"

这个流程能明显减少误提交。

暂存区可以撤销

如果误把文件加入暂存区，可以取消暂存。

1
git restore --staged file.txt

这条命令只会把文件从暂存区移回工作区，不会删除你的修改。

也就是说：

1
暂存区 -> 工作区

取消暂存但保留修改

1
git restore --staged file.txt

结果：

1
staged -> modified

文件内容还在，只是不参与下一次提交。

丢弃工作区修改

1
git restore file.txt

结果：

1
modified -> clean

注意：这会丢弃未提交修改。

修改最近一次提交

1
git add missing-file.txt
2
git commit --amend

适合忘记把某个文件加入最近一次提交时使用。

暂存区在团队协作中的价值

暂存区不只是个人方便，它直接影响团队协作质量。

好的暂存习惯可以带来：

• 更小的 commit
• 更清楚的变更目的
• 更容易 review
• 更容易 revert
• 更容易生成 changelog
• 更容易定位 bug

代码评审时，审查者最怕看到这种提交：

1
update all files

因为它可能同时包含：

• 业务逻辑修改
• 格式化修改
• 文档修改
• 临时调试代码
• 依赖升级

而这些内容应该被拆成独立提交。

暂存区和 Commit Message 的关系

Commit Message 写得好不好，前提是暂存区选得好不好。

如果暂存区里混入了多个无关修改，再好的 commit message 也很难准确描述。

合理关系应该是：

1
暂存区内容 = 一个明确变更目的
2
commit message = 对这个变更目的的准确描述

例如：

1
git add src/auth/TokenValidator.kt
2
git commit -m "fix(auth): reject expired token"

这个提交就很清楚。

7. Git 基础配置#

Git 安装完成后，第一件事不是立刻提交代码，而是先完成基础配置。

Git 配置会影响：

• 提交作者信息
• 默认分支名
• 默认编辑器
• 换行符处理
• 代理
• 命令别名
• 凭据保存方式
• 输出显示效果

配置正确后，后续协作会少很多问题。

1. 查看版本

1
git --version

如果能正常输出版本号，说明 Git 已经安装并加入系统 PATH。

示例：

1
git version 2.45.0

如果命令不存在，需要检查：

• Git 是否安装
• 终端是否重启
• PATH 环境变量是否正确

2. 配置用户名和邮箱

1
git config --global user.name "Your Name"
2
git config --global user.email "you@example.com"

用户名和邮箱会写入每一次 commit。

查看提交时通常会看到：

1
Author: Your Name <you@example.com>

注意：

• 这里的邮箱不一定必须是 GitHub 邮箱，但建议保持一致。
• 公司项目建议使用公司邮箱。
• 个人开源项目可以使用个人邮箱。
• GitHub 用户如果想隐藏真实邮箱，可以使用 GitHub 提供的 noreply 邮箱。

查看当前配置：

1
git config --global user.name
2
git config --global user.email

如果某个仓库需要单独设置作者信息，可以去掉 --global：

1
git config user.name "Work Name"
2
git config user.email "work@example.com"

3. 配置默认分支名

1
git config --global init.defaultBranch main

这个配置影响 git init 新仓库时默认创建的分支名。

常见默认分支名：

• main
• master
• develop

现在很多新项目使用 main 作为默认分支名。

如果不配置，不同 Git 版本和模板环境可能使用不同默认名称。统一配置可以减少团队差异。

4. 查看配置

1
git config --list

查看全局配置：

1
git config --global --list

查看当前仓库配置：

1
git config --local --list

查看系统级配置：

1
git config --system --list

查看配置来源：

1
git config --list --show-origin

这在排查“为什么配置不生效”时很有用。

5. 配置编辑器

1
git config --global core.editor "code --wait"

编辑器用于这些场景：

• 写多行 commit message
• 处理 merge commit message
• 执行交互式 rebase
• 编辑 tag message

常见配置：

1
# VS Code
2
git config --global core.editor "code --wait"
3

4
# Vim
5
git config --global core.editor "vim"
6

7
# Notepad++
8
git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"

如果不配置，Git 可能默认打开 Vim。
如果你不熟悉 Vim，第一次看到编辑器界面可能会不知道如何退出。

6. 配置换行符

不同系统使用的换行符不同：

如果团队跨平台协作，换行符处理不当会导致大量无意义 diff。

Windows 常见配置：

1
git config --global core.autocrlf true

macOS / Linux 常见配置：

1
git config --global core.autocrlf input

也可以更推荐在项目中用 .gitattributes 统一：

1
* text=auto
2
*.sh text eol=lf
3
*.bat text eol=crlf

建议：

• 个人全局配置只做基础处理。
• 团队项目用 .gitattributes 明确规则。
• 不要让换行符变化污染业务提交。

7. 配置大小写敏感

Windows 和 macOS 默认文件系统通常对大小写不敏感，Linux 通常大小写敏感。

这会导致类似问题：

1
UserService.kt
2
userservice.kt

在 Linux CI 上可能是两个文件，在 Windows 上可能冲突。

查看配置：

1
git config core.ignorecase

一般 Git 会根据文件系统自动设置。

实践建议：

• 文件命名统一风格。
• 不要只改文件名大小写后直接提交。
• 如果必须修改大小写，使用 git mv。

示例：

1
git mv userservice.kt UserService.kt

8. 配置凭据保存

使用 HTTPS 远程仓库时，Git 需要认证。

常见方式：

• 用户名 + Token
• SSH key
• 凭据管理器

Windows 上 Git 通常会配合 Git Credential Manager。

查看凭据 helper：

1
git config --global credential.helper

常见配置：

1
git config --global credential.helper manager

macOS 常见：

1
git config --global credential.helper osxkeychain

Linux 可以使用 cache：

1
git config --global credential.helper cache

也可以设置缓存时间：

1
git config --global credential.helper "cache --timeout=3600"

安全建议：

• 不要把 token 写进远程 URL。
• 不要把 token 提交到仓库。
• 公司项目优先使用组织推荐的认证方式。

9. 配置 SSH

如果使用 SSH 访问远程仓库，需要生成 SSH key。

生成：

1
ssh-keygen -t ed25519 -C "you@example.com"

查看公钥：

1
cat ~/.ssh/id_ed25519.pub

把公钥添加到 GitHub、GitLab 或 Gitee 后，可以测试：

1
ssh -T git@github.com

SSH 远程地址一般长这样：

1
git@github.com:user/repo.git

HTTPS 地址一般长这样：

1
https://github.com/user/repo.git

SSH 适合长期开发，HTTPS 适合快速克隆或简单使用。

10. 配置代理

如果访问 GitHub 慢，可能会配置代理。

HTTP 代理：

1
git config --global http.proxy http://127.0.0.1:7890
2
git config --global https.proxy http://127.0.0.1:7890

取消代理：

1
git config --global --unset http.proxy
2
git config --global --unset https.proxy

注意：

• 代理地址要根据自己的环境调整。
• 公司网络环境下不要随意配置未知代理。
• 代理问题经常会影响 clone、fetch、push。

11. 配置常用别名

Git 命令较长，可以设置别名提高效率。

1
git config --global alias.st status
2
git config --global alias.co checkout
3
git config --global alias.sw switch
4
git config --global alias.br branch
5
git config --global alias.cm commit
6
git config --global alias.lg "log --oneline --graph --decorate --all"

使用：

1
git st
2
git lg

建议只给常用、安全、容易理解的命令设置别名。
不要给 reset --hard、push --force 这类危险命令设置太短的别名。

12. 配置默认 pull 行为

git pull 本质上是：

1
git fetch + merge/rebase

可以配置默认行为。

默认使用 merge：

1
git config --global pull.rebase false

默认使用 rebase：

1
git config --global pull.rebase true

只允许 fast-forward：

1
git config --global pull.ff only

团队应该统一策略，避免每个人 pull 后历史形态不一致。

13. 配置默认 push 行为

常见配置：

1
git config --global push.default simple

simple 表示只推送当前分支到它对应的 upstream 分支。
这是比较安全的默认行为。

14. 配置颜色输出

让 Git 输出更易读：

1
git config --global color.ui auto

通常新版本 Git 默认已经启用。

15. 配置提交模板

如果团队要求规范 commit message，可以配置提交模板。

创建模板文件，例如 ~/.gitmessage：

1
type(scope): subject
2

3
Why:
4

5
What:
6

7
Impact:
8

9
Refs:

配置：

1
git config --global commit.template ~/.gitmessage

之后执行：

1
git commit

Git 会自动打开这个模板。

16. 配置层级

Git 配置有三个常见层级：

优先级：

1
local > global > system

也就是说，当前仓库配置会覆盖全局配置。

示例：

1
git config --global user.email "personal@example.com"
2
git config user.email "work@example.com"

在当前仓库里，最终使用的是：

1
work@example.com

17. 推荐基础配置清单

个人开发环境可以先配置这些：

1
git config --global user.name "Your Name"
2
git config --global user.email "you@example.com"
3
git config --global init.defaultBranch main
4
git config --global core.editor "code --wait"
5
git config --global color.ui auto
6
git config --global push.default simple
7
git config --global alias.st status
8
git config --global alias.lg "log --oneline --graph --decorate --all"

Windows 可以额外考虑：

1
git config --global core.autocrlf true

macOS / Linux 可以考虑：

1
git config --global core.autocrlf input

项目级换行规则更推荐交给 .gitattributes。

8. 创建和克隆仓库#

Git 仓库的来源通常有两种：

1. 本地已经有项目，现在要开始用 Git 管理。
2. 远程已经有仓库，现在要克隆到本地开发。

对应命令分别是：

1
git init
2
git clone <repo-url>

这两个命令是进入 Git 项目的起点。

1. 初始化本地仓库

1
git init

git init 会在当前目录创建一个 .git 文件夹。
有了 .git 文件夹，这个目录就变成了 Git 仓库。

示例：

1
mkdir my-project
2
cd my-project
3
git init

初始化后可以查看状态：

1
git status

你会看到类似提示：

1
On branch main
2
No commits yet

这表示仓库已经创建，但还没有任何提交。

2. 初始化后的第一次提交

初始化仓库后，通常要添加项目文件并创建第一次提交。

1
echo "# My Project" > README.md
2
git add README.md
3
git commit -m "docs: add initial README"

第一次提交常见写法：

1
chore: initial commit
2
docs: add initial README
3
feat: initialize project structure

如果只是空项目初始化，可以用：

1
chore: initial commit

如果已经有明确项目结构，更推荐写清楚初始化内容。

3. 在已有项目中启用 Git

如果项目目录已经存在：

1
cd existing-project
2
git init
3
git status

然后添加必要文件：

1
git add .
2
git commit -m "chore: import existing project"

注意：

• 提交前先写 .gitignore
• 不要把构建产物、依赖目录、日志、密钥提交进去
• 初次导入项目时，可以先用 git status 检查文件列表

常见初始 .gitignore：

1
# build outputs
2
build/
3
dist/
4
target/
5

6
# dependencies
7
node_modules/
8

9
# logs
10
*.log
11

12
# env
13
.env
14

15
# IDE
16
../.idea/
17
.vscode/

4. 创建裸仓库

普通开发者很少需要裸仓库，但了解概念有帮助。

创建裸仓库：

1
git init --bare my-project.git

裸仓库没有工作区，通常用于服务器端远程仓库。

普通仓库：

1
项目文件 + .git

裸仓库：

1
只有 Git 仓库数据，没有可编辑工作区

现代团队通常直接使用 GitHub、GitLab、Gitee，不需要自己手动创建裸仓库。

5. 克隆远程仓库

1
git clone https://github.com/user/repo.git

git clone 会做几件事：

1. 下载远程仓库数据。
2. 创建本地工作目录。
3. 自动设置远程仓库名为 origin。
4. 检出默认分支。

克隆后目录结构：

1
repo/
2
  .git/
3
  README.md
4
  src/

进入项目：

1
cd repo
2
git status

6. 克隆到指定目录

默认情况下，Git 会用仓库名作为目录名。

1
git clone https://github.com/user/repo.git

会生成：

1
repo/

如果想指定目录名：

1
git clone https://github.com/user/repo.git my-local-name

会生成：

1
my-local-name/

7 使用 SSH 克隆

HTTPS 地址：

1
git clone https://github.com/user/repo.git

SSH 地址：

1
git clone git@github.com:user/repo.git

两者区别：

如果是自己的长期开发仓库，更推荐 SSH。

8. 浅克隆

如果仓库历史很大，只想拉最近历史，可以使用浅克隆：

1
git clone --depth 1 https://github.com/user/repo.git

适合：

• CI 临时拉代码
• 只需要最新版本
• 仓库历史很大

不适合：

• 需要完整历史分析
• 需要 bisect
• 需要查看很久以前的提交

9. 克隆指定分支

1
git clone -b develop https://github.com/user/repo.git

或者：

1
git clone --branch develop https://github.com/user/repo.git

适合只需要某个分支的情况。

10. 查看远程地址

1
git remote -v

输出示例：

1
origin  git@github.com:user/repo.git (fetch)
2
origin  git@github.com:user/repo.git (push)

其中：

• fetch 表示拉取地址
• push 表示推送地址

多数情况下，两者相同。

11. 添加远程仓库

1
git remote add origin git@github.com:user/repo.git

这个命令常用于：

• 本地 git init 后，要关联 GitHub/GitLab/Gitee 上的新仓库
• 本地已有项目，要推送到远程

完整流程：

1
git init
2
git add .
3
git commit -m "chore: initial commit"
4
git remote add origin git@github.com:user/repo.git
5
git push -u origin main

-u 表示设置 upstream。设置后，以后可以直接：

1
git push
2
git pull

12. 修改远程地址

如果远程地址错了，可以修改：

1
git remote set-url origin git@github.com:user/new-repo.git

查看确认：

1
git remote -v

13. 删除远程仓库引用

删除远程名：

1
git remote remove origin

注意：这只会删除本地对远程仓库的引用，不会删除 GitHub/GitLab 上的远程仓库。

14. 一个本地项目推送到新远程仓库的完整流程

假设你已经有一个本地项目，现在想推送到 GitHub。

步骤：

1. 在 GitHub 创建空仓库。
2. 本地初始化 Git。
3. 创建第一次提交。
4. 添加远程地址。
5. 推送主分支。

命令：

1
cd my-project
2
git init
3
git add .
4
git commit -m "chore: initial commit"
5
git branch -M main
6
git remote add origin git@github.com:user/my-project.git
7
git push -u origin main

git branch -M main 的作用是把当前分支重命名为 main。

15. 克隆后通常要做什么

克隆项目后，不是马上改代码，建议先做这些检查：

1
git status
2
git branch
3
git remote -v
4
git log --oneline -5

然后阅读：

• README.md
• CONTRIBUTING.md
• 构建脚本
• .gitignore
• 项目文档

如果是团队项目，通常还要：

• 安装依赖
• 配置环境变量
• 运行测试
• 创建自己的功能分支

示例：

1
git switch -c feature/login

9. 查看状态与差异#

在 Git 日常开发中，status 和 diff 是最常用、也最应该熟练掌握的命令。

它们分别回答两个问题：

1
git status: 当前仓库处于什么状态？
2
git diff: 具体改了什么？

一个好的提交习惯是：

1
git status
2
git diff
3
git add -p
4
git diff --cached
5
git commit

也就是说，提交前一定要先看状态和差异。

1. 查看状态

1
git status

git status 会告诉你：

• 当前在哪个分支
• 工作区是否有修改
• 暂存区是否有内容
• 是否有未跟踪文件
• 当前分支是否领先或落后远程分支
• 合并或 rebase 是否正在进行

典型输出：

1
On branch feature/login
2
Changes not staged for commit:
3
  modified:   src/LoginService.kt
4

5
Untracked files:
6
  debug.log

含义：

• 当前在 feature/login 分支
• LoginService.kt 被修改但未暂存
• debug.log 是未跟踪文件

2. 简洁状态

如果想看简洁输出：

1
git status -s

或：

1
git status --short

示例：

1
 M src/LoginService.kt
2
A  README.md
3
?? debug.log

常见标记：

短状态有两列：

1
XY file

• X 表示暂存区状态
• Y 表示工作区状态

例如：

1
 M file.txt

表示工作区修改了，但还没暂存。

1
M  file.txt

表示修改已经暂存。

3. 查看工作区差异

1
git diff

git diff 默认比较：

1
工作区 vs 暂存区

也就是查看还没有 git add 的修改。

适合在执行 git add 前检查自己改了什么。

示例输出结构：

1
diff --git a/src/LoginService.kt b/src/LoginService.kt
2
index 1111111..2222222 100644
3
--- a/src/LoginService.kt
4
+++ b/src/LoginService.kt
5
@@ -10,7 +10,7 @@
6
-    return false
7
+    return token.isNotBlank()

含义：

• - 开头表示旧内容
• + 开头表示新内容
• @@ 表示变更所在的上下文位置

4. 查看暂存区差异

1
git diff --cached

也可以写成：

1
git diff --staged

它比较的是：

1
暂存区 vs 最新提交 HEAD

也就是下一次 git commit 会提交的内容。

提交前非常建议执行：

1
git diff --cached

这样可以确认没有误提交。

5. 查看某个文件差异

1
git diff -- path/to/file

查看某个文件的暂存区差异：

1
git diff --cached -- path/to/file

查看某个目录的差异：

1
git diff -- src/main/

这个命令适合项目改动很多，但你只想看某个模块时使用。

6. 查看两个提交之间的差异

1
git diff <commit1> <commit2>

示例：

1
git diff HEAD~1 HEAD

含义：查看最近一次提交相对于上一次提交改了什么。

查看两个分支的差异：

1
git diff main feature/login

含义：比较 main 和 feature/login 两个分支的文件内容差异。

7. 查看当前分支和远程分支差异

查看本地当前分支与远程分支差异：

1
git diff origin/main

如果你在功能分支上，想看自己相对 main 改了什么：

1
git fetch origin
2
git diff origin/main...HEAD

三个点 ... 常用于查看当前分支相对共同祖先的变更，适合 review 前检查。

8. 只看文件名

如果不想看具体内容，只想知道哪些文件变了：

1
git diff --name-only

查看暂存区变更文件：

1
git diff --cached --name-only

查看文件状态和文件名：

1
git diff --name-status

示例：

1
M       src/LoginService.kt
2
A       src/LoginValidator.kt
3
D       old-login.md

9. 统计变更规模

查看每个文件增删行统计：

1
git diff --stat

查看暂存区统计：

1
git diff --cached --stat

示例：

1
 src/LoginService.kt | 12 +++++++-----
2
 README.md           |  3 ++-
3
 2 files changed, 9 insertions(+), 6 deletions(-)

适合提交前快速判断改动规模是否合理。

10. 忽略空白变化

有时 diff 里充满空格、缩进、换行变化，可以忽略空白差异。

忽略空白数量变化：

1
git diff -w

忽略行尾空白：

1
git diff --ignore-space-at-eol

注意：

• 忽略空白只适合辅助阅读。
• 不代表空白修改不存在。
• 提交前仍要确认格式化是否应该单独提交。

11. 查看单词级差异

普通 diff 以行为单位。
如果一行很长，可以用单词级 diff：

1
git diff --word-diff

适合：

• Markdown 文档
• 长字符串
• 一行较长的配置

12. 查看某次提交的差异

1
git show <commit>

例如：

1
git show HEAD

查看最近一次提交。

只看某次提交改了哪些文件：

1
git show --name-only <commit>

查看统计：

1
git show --stat <commit>

13. diff 输出怎么看

典型 diff：

1
diff --git a/file.txt b/file.txt
2
index 1111111..2222222 100644
3
--- a/file.txt
4
+++ b/file.txt
5
@@ -1,3 +1,4 @@
6
 line 1
7
-old line
8
+new line
9
+another line
10
 line 3

解释：

看 diff 时优先关注：

1. 是否有无关文件。
2. 是否有调试代码。
3. 是否有敏感信息。
4. 是否有大面积格式化。
5. 是否和 commit message 对得上。

14. 查看冲突状态

发生冲突时：

1
git status

会提示哪些文件未合并。

查看冲突文件：

1
git diff

冲突标记一般长这样：

1
<<<<<<< HEAD
2
当前分支内容
3
=======
4
被合并分支内容
5
>>>>>>> feature/login

解决冲突后：

1
git add conflict-file
2
git commit

如果是 rebase：

1
git add conflict-file
2
git rebase --continue

15. 提交前推荐检查流程

日常提交前建议：

1
git status
2
git diff
3
git add -p
4
git diff --cached
5
git status
6
git commit