Git仓库基础用法

一、引言

开篇场景

“凌晨两点，你删掉了一行关键代码，保存退出——然后发现程序崩了。更糟的是，你忘了之前写了什么。如果你在用 Git，只需要一行命令就能回到一小时前的状态。”

几乎所有开发者都遇到过代码误改、丢失、版本混乱的问题，而 Git 就是解决这类问题的行业标准工具。它不只是简单的代码备份工具，更是一套完整的版本控制、代码回溯、团队协作体系，是程序员日常开发的必备技能。

读完本文你能：独立完成从项目创建到日常提交、远程协作、分支开发的全流程，遇到常见误操作、冲突、推送报错等问题知道如何快速应对，彻底摆脱“瞎敲命令”的状态

阅读建议：打开电脑终端，跟着每一步亲手操作，边看边练，实操是掌握 Git 最快的方式，看完即可熟练落地日常开发场景

全文示例项目

为了统一实操场景，降低学习门槛，本文所有操作将围绕一个名为blog-demo的个人博客项目展开，全程连贯实操，无零散案例：

• 创建index.html首页基础文件

• 添加style.css样式文件，完善页面样式

• 使用独立分支开发“文章列表”新功能

• 将本地完整项目推送到 GitHub 远程仓库

二、快速上手：安装与配置

本章目标：10分钟内完成Git安装和首次全局配置，搭建可正常使用的Git开发环境

2.1 安装 Git

Git 支持全平台系统，不同系统可通过对应官方方式快速安装，安装完成后无需复杂配置，终端识别即可使用：

• Windows：前往 Git 官网下载对应系统版本的安装包，默认下一步安装即可；也可通过系统自带 Winget 命令一键安装，无需手动下载

• macOS：安装 Homebrew 工具后，执行一键安装命令，全程自动完成配置

• Linux：通过系统自带包管理器（apt、yum 等）直接安装，适配绝大多数发行版

安装验证：打开终端，输入以下命令，输出版本号即代表安装成功：

git --version

2.2 初次配置（一次性）

Git 安装完成后，必须进行全局用户名和邮箱配置，这是 Git 的核心基础配置，所有代码提交记录都会绑定该作者信息，用于区分代码开发者，溯源修改记录。仅需配置一次，永久生效。

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

除核心配置外，可按需配置个性化参数，提升使用体验：

• 配置终端颜色高亮：让 Git 操作输出结果颜色区分，状态一目了然

• 配置默认编辑器：自定义 commit 编辑、冲突修改的默认文本编辑器

2.3 配置 SSH（推荐）

日常连接 GitHub 远程仓库有 HTTPS 和 SSH 两种方式，强烈推荐配置 SSH，核心优势为永久免密推送代码，无需每次输入账号密码，大幅提升开发效率，且传输稳定性更强。

SSH 配置核心步骤：执行密钥生成命令，生成专属公私钥，将公钥添加到 GitHub 个人后台的 SSH 配置中即可：

ssh-keygen -t ed25519 -C "你的邮箱"

执行命令后全程回车默认配置即可，无需额外修改参数。

📌 如果你临时使用 HTTPS 方式克隆仓库，无需配置 SSH，可直接跳过本节内容。

三、第一次提交：从初始化到完成提交

本章目标：完成你的第一次 Git 提交，彻底理解工作区、暂存区、版本库三大核心区域，掌握基础提交流程

3.1 创建项目并初始化

我们从零创建本次实操的博客项目，并将普通文件夹初始化为 Git 仓库，让 Git 开始接管项目版本。

mkdir blog-demo cd blog-demo git init

执行git init后，文件夹内会生成一个隐藏的.git文件夹，这是 Git 的核心“数据库”，专门存放项目所有版本记录、提交日志、分支配置等核心数据，禁止手动修改、删除该文件夹内容，否则会导致版本库损坏、代码记录丢失。

初始化验证：执行ls -la查看文件夹所有文件（包含隐藏文件），看到.git目录即初始化成功。

3.2 创建第一个文件并查看状态

在项目根目录新建index.html文件，写入基础的网页 HTML 结构，作为项目首页文件。

文件创建完成后，执行状态查看命令，观察 Git 对新文件的识别状态：

git status

此时终端会显示Untracked files，代表该文件是新增文件，Git 尚未开启追踪，不会记录其版本变化。

🎯概念引入①：工作区——就是你电脑上直观看到的项目文件夹，所有的代码编写、文件修改、删除操作，都在工作区完成，是代码的原始编辑区域。

3.3 追踪文件：添加到暂存区

想要让 Git 记录文件改动，需要先将工作区的变更添加到暂存区，完成文件追踪。

# 追踪单个指定文件 git add 文件名 # 查看当前仓库状态 git status

执行后文件会变为绿色，状态显示为 Staged，代表已成功进入暂存区。

日常开发最常用快捷命令：git add .，可一次性添加当前目录下所有新增、修改的文件变更，无需逐个添加，高效便捷。

🎯概念引入②：暂存区——可以理解为“购物车”，专门存放你确认需要提交的代码改动。你可以批量将多个修改加入暂存区，统一提交，灵活筛选需要保存的版本内容。

3.4 完成提交：保存到版本库

暂存区的改动仅为临时存放，需要执行提交命令，将改动永久保存到版本库，生成专属版本记录。

git commit -m "备注信息"

提交完成后，可通过简洁命令查看所有提交记录：

git log --oneline

🎯概念引入③：版本库——Git 永久存储所有提交记录的核心区域，相当于游戏的“存档点”，每一次 commit 都是一个独立存档，后续可随时回溯、切换、修改对应版本。

规范提交信息：统一采用<type>: <简短描述>格式，清晰标注本次提交的改动类型和内容，方便团队协作和版本回溯。

常用 type 类型：

• feat：新增功能

• fix：修复代码 bug

• docs：文档修改、注释更新

• style：样式调整、格式优化（无代码逻辑改动）

• refactor：代码重构（优化逻辑，无功能新增/修复）

3.5 配置 .gitignore

项目开发中会产生大量无需提交的文件：依赖包、环境配置文件、系统临时文件、打包产物等。如果不做忽略配置，这些文件会被 Git 追踪，造成仓库臃肿、敏感信息泄露，因此项目初始化后第一件事就是配置 .gitignore。

在项目根目录新建.gitignore文件，写入忽略规则，Git 会自动忽略匹配规则的文件，不再追踪和提交。本文适配 Python 开发场景，下方为Python 项目通用完整忽略规则，覆盖虚拟环境、缓存、编译产物、编辑器配置等所有常见冗余文件，可直接复用。

# Python 字节缓存文件 __pycache__/ *.py[cod] *$py.class # 虚拟环境目录 venv/ env/ .venv/ .env/ virtualenv/ # 打包、编译产物 build/ dist/ *.egg-info/ .Python # 日志、临时文件 *.log *.tmp *.swp # 环境变量、配置缓存 .env .env.local .idea/ .vscode/ # 系统文件 .DS_Store

配置完成后执行git status，被忽略的文件不会出现在待提交列表中，配置生效。

• .gitignore必须放在项目根目录（和.git文件夹同级）才生效
• 只对未被 Git 追踪过的文件生效；如果文件已经add/commit过，改.gitignore不会自动忽略，需要先删除仓库追踪

3.5.1 进阶：让 .gitignore 对已追踪文件彻底生效（完整命令）

核心原理：仅删除 Git 仓库的追踪记录，不会删除本地文件，本地缓存、虚拟环境等文件会保留，同时不再被Git提交、追踪。

步骤1：移除仓库中所有已追踪、但被 gitignore 匹配的文件（核心命令）

# 清空Git缓存，重新匹配最新.gitignore规则（最通用、推荐） git rm -r --cached .

参数解释：-r递归处理文件夹（适配venv、__pycache__等目录），--cached只删除仓库追踪记录，保留本地文件，绝对不会误删代码。

步骤2：重新暂存、提交生效

# 重新添加所有未被忽略的合法文件 git add . # 提交配置更新，彻底固化忽略规则 git commit -m "chore: 生效gitignore，忽略Python冗余文件"

精准移除单个文件/文件夹（按需使用）：如果不想全局刷新，仅移除指定已追踪文件，执行以下命令：

# 移除单个已追踪文件 git rm --cached 文件名 # 移除已追踪的文件夹（如venv虚拟环境） git rm -r --cached venv/

操作完成后，再次执行git status，所有 .gitignore 配置的冗余文件、缓存、虚拟环境目录均不会出现在待提交列表中，规则完全永久生效。

3.6 小练习：完成三次提交

通过三次实操提交，熟练掌握 add + commit 完整流程，夯实基础操作：

1. 新建style.css样式文件，写入基础样式，提交代码：git commit -m "style: 添加基础样式"

2. 修改index.html文件，引入style.css样式，提交代码：git commit -m "feat: 引入样式文件"

3. 执行git log --oneline查看提交记录，此时项目应有 3 条完整提交记录

✅本章检查点：执行git log --oneline，输出结果应包含三条有序提交记录，示例如下：

a1b2c3d feat: 引入样式文件 e4f5g6h style: 添加基础样式 i7j8k9l feat: 添加首页 HTML 结构

四、远程协作：把代码推送到 Gitee

本章目标：将本地仓库与 Gitee 远程仓库关联，熟练掌握代码推送、拉取核心操作，解决推送失败等常见问题

4.1 在 Gitee 创建远程仓库

首先在 Gitee 平台创建与本地项目同名的远程仓库，用于存储、同步本地代码，实现云端备份与团队协作。

创建核心步骤：

1. 登录 Gitee 账号，点击右上角新建仓库按钮创建仓库

2. 仓库名称填写blog-demo，与本地项目保持一致

3. 重点：不要勾选 README、LICENSE 等初始化选项，避免远程仓库存在初始文件，与本地代码产生冲突

4. 创建完成后，复制仓库 SSH 地址（优先选择 SSH 协议，免密推送）

4.2 关联远程仓库

回到本地项目终端，执行命令将本地 Git 仓库与 Gitee 远程仓库绑定关联：

# 关联远程仓库，替换为自己的Gitee仓库SSH地址 git remote add origin git@gitee.com:你的用户名/blog-demo.git # 查看远程关联状态，验证是否绑定成功 git remote -v

执行后终端展示对应的推送、拉取地址，即代表远程关联成功。其中origin是远程仓库的默认别名，为行业通用规范，无需修改。

4.3 第一次推送

关联完成后，将本地所有提交的代码推送到远程仓库：

git push -u origin main

-u参数核心作用：建立本地main分支与远程main分支的永久追踪关系。首次推送必须加 -u，后续日常推送直接执行git push即可，无需重复指定分支。

⚠️部分旧版本 Git 默认主分支为master，若本地默认分支为 master，可统一使用git push -u origin master，保持本地与远程分支名一致即可。

4.4 拉取远程更新

团队协作场景中，同事会向远程仓库推送新代码，需要同步远程最新改动到本地，此时用到拉取命令，核心区分两个高频指令：

4.5 常见问题：推送被拒绝（远程有新提交）

日常协作中高频报错场景：本地推送代码失败，终端提示：! [rejected] main -> main (non-fast-forward)

报错原因：远程仓库存在本地没有的新提交记录，Git 为了避免覆盖他人代码，直接拒绝推送。常见于多人协作、多设备登录同一仓库开发场景。

解决三步走（通用万能方案）：

1. 执行git pull拉取远程最新代码，同步远程更新到本地

2. 若出现代码冲突，手动解决冲突（具体方法参考 5.6 节）

3. 再次执行git push，即可成功推送本地改动

✅本章检查点：打开 Gitee远程仓库页面，可正常看到本地推送的index.html、style.css文件，代码同步成功。

五、分支：并行开发的利器

本章目标：理解分支的核心价值，熟练掌握分支创建、切换、开发、合并、删除全流程，独立解决代码合并冲突问题

5.1 为什么需要分支？（先用场景说话）

很多新手习惯直接在主分支开发，极易引发代码混乱、功能耦合、Bug 无法溯源等问题，而分支就是解决这些问题的核心工具：

场景一：正在开发新功能写到一半，代码处于半成品状态，突然需要紧急修复线上 Bug，无需提交半成品代码到主分支，可新建 Bug 分支独立修复

场景二：团队多人协作开发，A 开发文章功能、B 开发评论功能，通过独立分支隔离开发，互不干扰，避免代码互相覆盖

一句话核心：分支让你可以在同一套代码基础上，隔离地进行不同方向的开发，主分支始终保持稳定、可用状态。

5.2 查看与创建分支

默认项目仅有main主分支，通过以下命令查看分支、创建自定义功能分支：

# 查看当前所有本地分支，* 标记为当前所在分支 git branch # 创建名为 feature/articles 的功能分支（用于开发文章列表功能） git branch feature/articles

分支命名规范：统一采用feature/功能名、fix/Bug名格式，语义清晰，便于团队识别。

5.3 切换分支

分支创建后，需要切换到对应分支才能开展开发工作，Git 提供新旧两套切换命令，推荐使用简洁新语法：

# 旧版切换语法（兼容所有Git版本） git checkout feature/articles # 新版切换语法（Git 2.23+ 推荐使用） git switch feature/articles # 一步到位：创建并切换到新分支（最常用） git switch -c feature/articles

💡 核心实操特点：切换分支后，项目工作区文件会自动同步为对应分支的版本，不同分支的代码完全隔离，互不影响。

5.4 在分支上开发

我们在新建的功能分支中完成文章列表功能开发，直观感受分支隔离特性：

1. 确保当前处于feature/articles分支，新建articles.html文章列表页面，写入基础代码内容

2. 执行git add .暂存所有改动，执行git commit -m "feat: 添加文章列表页"提交版本

3. 执行git switch main切回主分支，查看项目文件，会发现articles.html文件消失

该现象充分证明：分支开发完全隔离，功能分支的改动不会影响主分支代码，完美保障主分支稳定性。

5.5 合并分支

当功能分支开发完成、测试无误后，需要将分支代码合并到主分支，完成功能上线：

# 先切回需要合并到的目标分支（主分支）

git switch main # 将功能分支代码合并到当前main分支 git merge feature/articles

合并完成后，主分支中会出现articles.html文件，功能代码成功同步到主分支。

合并完成、功能稳定后，可删除无用的功能分支，精简分支列表：

git branch -d feature/articles

5.6 合并冲突（新手最怕的场景，一步步来）

合并冲突是新手学习 Git 的最大卡点，但冲突不是程序报错，只是 Git 无法自动判断代码取舍，需要开发者手动决策，掌握规律即可轻松解决。

冲突触发核心条件：两个不同分支，修改了同一个文件的同一行/同一区域代码，Git 无法自动合并，触发冲突提示。

手把手模拟并解决真实冲突：

第一步：制造冲突场景

# 新建并切换到头部样式修改分支 git switch -c feature/header # 修改index.html标题为测试版，提交代码 # 此处手动修改文件后执行提交 git add . && git commit -m "feat: 修改标题为测试版" # 切回主分支 git switch main # 在主分支修改同一位置标题为正式版，提交代码 # 此处手动修改文件后执行提交 git add . && git commit -m "feat: 修改标题为正式版"

第二步：执行合并，触发冲突

git merge feature/header

终端报错：Automatic merge failed; fix conflicts and then commit the result.，代表冲突产生，合并暂停。

第三步：手动解决冲突

打开冲突文件index.html，会看到 Git 自动插入的冲突标记：

<<<<<<< HEAD 我的博客 - 正式版 ======= 我的博客 - 新标题 >>>>>>> feature/header

• HEAD区域：当前所在主分支（main）的代码内容

• feature/header区域：待合并分支的代码内容

手动决策保留内容：可保留任意一方、或整合双方内容，必须删除所有冲突标记符号，文件恢复正常代码格式。

第四步：完成合并收尾

# 暂存解决冲突后的文件 git add . # 提交合并结果，完成合并 git commit -m "merge: 解决标题冲突"

一句话总结：冲突不是错误，是 Git 在请你做决定——最终保留什么代码，由开发者根据业务需求说了算。

✅本章检查点：当前处于main分支，执行git branch确认已合并的功能分支已删除，项目中articles.html文件正常存在。

六、常见问题与后悔药（按操作阶段分类）

本章目标：覆盖90%新手高频误操作，做到修改可撤回、报错可解决，告别Git操作焦虑

6.1 场景一：修改了但还没 add（工作区撤销）

适用场景：代码修改错误、调试代码作废，尚未执行任何暂存操作，需要丢弃所有本地修改，恢复到上次提交的完整状态。

# 撤销单个文件的工作区修改 git restore 文件名

⚠️高危提醒：该操作会永久丢弃工作区未保存的修改，不可恢复，执行前建议先通过git diff查看具体修改内容，确认无需保留再操作。

6.2 场景二：已经 add 但还没 commit（暂存区撤销）

适用场景：误将不需要提交的文件添加到暂存区，需要取消暂存，但保留本地文件修改，方便二次编辑后重新提交。

# 将文件从暂存区移出，保留工作区修改 git restore --staged 文件名

通俗理解：等同于“撤销 git add 操作”，仅修改暂存区状态，不改动代码内容，安全无风险。

6.3 场景三：已经 commit 但还没 push（撤销提交）

本地已完成提交，但尚未推送到远程仓库，发现提交内容有误、需要修改，可通过git reset撤销提交，三种模式适配所有场景，一张表彻底弄懂：

💡 参数说明：HEAD~1代表“上一次提交”，HEAD~3代表“往前撤销三次提交”，可按需修改数字。

6.4 场景四：已经 push 到远程了怎么办？

代码已推送到远程仓库，本地重置命令不再适用，需区分分支类型选择解决方案，核心原则：公共分支禁止强制覆盖历史。

6.5 其他高频问题速查表

七、日常开发完整流程图与核心习惯

7.1 一个功能开发的完整流程

以下是适配90%互联网团队的标准开发流程，从日常同步代码到功能开发、合并推送，全程规范无坑：

7.2 四条核心习惯（记住就能不踩坑）

Git 操作的核心不在于记住所有命令，而在于养成规范习惯，规避99%的新手问题：

7.3 下一步学什么？

掌握本文全部内容，即可满足日常开发95%的 Git 需求。如需进阶提升，适配复杂团队协作、版本管理场景，可学习以下核心方向：

附录：常用命令速查表

汇总日常开发高频 Git 命令，无需死记硬背，随时查阅即可：