Git 从入门到实战：一份兼容 GitHub / Gitee / GitCode 的新手指南

最新推荐文章于 2026-08-18 13:58:24 发布

原创最新推荐文章于 2026-08-18 13:58:24 发布 · 250 阅读

4 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

人工智能知识点

在这里插入图片描述

由于本人水平有限，难免出现错漏，敬请批评改正。
更多精彩内容，可点击进入我的个人主页查看。
一份面向实战的 Git 命令教程，覆盖初始化、分支管理、标签发布、多平台适配与避坑指南。

引言

Git 已成为当今开发者必备的版本控制工具。无论你是想备份个人代码、参与开源项目，还是在团队中协作，掌握 Git 核心命令都是基本功。

然而，许多新手在入门时往往会遇到这些问题：

面对五花八门的 Git 命令不知从何下手；
遇到 hook declined 或 LFS batch error 等报错时一脸茫然；
不熟悉 GitHub、Gitee、GitCode 等平台之间的差异，导致推送失败；
不知道如何管理分支和标签，让代码版本混乱不堪。

本文将从零开始，系统讲解 Git 的完整工作流，并覆盖 GitHub、Gitee、GitCode 三大主流代码托管平台的兼容使用与常见问题解决。无论你使用哪个平台，都能在这里找到答案。

Git 基础

什么是 Git？

Git 是一款分布式版本控制系统。与 SVN 等集中式版本控制不同，Git 在每个开发者的本地都保存了一份完整的代码仓库副本，因此可以离线工作、快速切换分支，并且几乎所有的操作都发生在本地，速度极快。

Git 的三大区域

理解 Git 的三个核心区域是掌握 Git 的关键：

区域	说明	对应命令
工作目录（Workspace）	你正在编辑代码的地方，即项目文件夹中的实际文件。	`git status` 查看红色文件
暂存区（Stage/Index）	一个“购物车”，你选择要提交的文件存放于此。它实际存储在 `.git/index` 文件中。	`git add` 将文件加入暂存区
本地仓库（Repository）	已提交的版本历史记录，存储在 `.git` 目录中。	`git commit` 将暂存区内容提交为永久版本

暂存区的物理位置与空间占用

很多初学者会好奇：暂存区到底存在哪里？占不占硬盘空间？

暂存区的“清单” 存储在 .git/index 文件中，这是一个二进制文件，记录了文件名、路径和哈希值，体积很小（通常几十 KB）。
文件的实际内容 在 git add 时会被压缩并存储在 .git/objects/ 目录下，以 Blob 对象的形式存在。因此，暂存区确实会占用硬盘空间，体积约为源文件压缩后的 50%~70%。

值得注意的是，git commit 只是将这些 Blob 对象“锁定”进版本历史，并不会再次复制文件内容，所以提交不会使仓库体积翻倍。

准备工作

在开始使用 Git 之前，需要完成以下准备工作：

1. 安装 Git

从 git-scm.com 下载并安装 Git。安装完成后，打开终端（CMD、PowerShell 或 Git Bash）验证安装：

git --version

2. 配置用户信息

Git 会将你的用户名和邮箱记录在每一次提交中。请将它们设置为你注册代码托管平台时使用的信息：

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

3. 注册并创建远程仓库

在 GitHub / Gitee / GitCode 上注册账号，然后新建一个仓库。重要：创建时不要勾选“使用 README 初始化”等选项，保持仓库为空，以便我们通过命令行推送。

4. 准备访问凭证

各平台均已禁用密码直接推送，请使用以下方式之一：

Gitee：在“设置 → 私人令牌”生成 Token（勾选 projects 权限）。
GitHub：在 Settings → Developer settings → Personal access tokens 生成 Token。
GitCode：在“个人设置 → 访问令牌”生成 Token（勾选项目读写权限）。

Git 基础工作流

初始化本地仓库

进入你的项目根目录，执行以下命令将其初始化为 Git 仓库：

git init

这会在当前目录下创建一个 .git 隐藏文件夹，所有版本数据都存储于此。

创建 .gitignore 排除文件

在项目根目录新建 .gitignore 文件，用来告诉 Git 哪些文件或目录不需要被版本控制。一个典型的 Python 项目 .gitignore 示例如下：

# 编译缓存
__pycache__/
*.pyc

# 虚拟环境
venv/
.venv/

# 大型模型文件（尤为重要，避免撑爆仓库）
*.pt
*.onnx
*.pth
*.h5
*.zip
*.tar.gz

# IDE 配置
.vscode/
.idea/

# 系统文件
.DS_Store
Thumbs.db

# 数据文件
/data/

添加文件到暂存区

git add .

这条命令会将当前目录下所有未被 .gitignore 忽略的文件添加到暂存区。

常用技巧：

git add 文件名：添加单个文件
git add *.py：添加所有 Python 文件
git add -p：交互式选择要添加的内容块

查看当前状态：

git status

绿色：已暂存，等待提交
红色：未跟踪，尚未加入暂存区

提交到本地仓库

git commit -m "简洁的描述本次改动"

提交信息（Commit Message）建议遵循以下格式：

feat: 添加用户登录功能
fix: 修复登录超时问题
docs: 更新 README 文档
refactor: 重构用户模块代码

关联远程仓库

git remote add origin https://gitee.com/你的用户名/仓库名.git

origin 是远程仓库的别名，可以改为其他名称。
也可以使用 SSH 地址（更稳定）：git@平台域名:用户名/仓库名.git

验证远程地址：

git remote -v

推送到远程仓库

首次推送需要指定分支并建立追踪关系：

git push -u origin master

-u 相当于 --set-upstream，将本地 master 与远程 origin/master 关联起来，之后直接执行 git push 即可。
如果默认分支是 main，则改为 git push -u origin main。

推送时会提示输入用户名和私人令牌（Token），请勿输入登录密码。

分支管理

为什么需要分支？

分支是 Git 最强大的功能之一。通过分支，你可以：

同时在多个方向上并行开发，互不干扰；
将 master/main 分支始终保持稳定，只存放经过测试的代码；
在开发新功能时随时保存进度，随时回退。

核心原则：永远不要直接在 master 分支上修改代码。将 master 视为“正式发布版”，只在开发分支上工作。

分支基本操作

查看分支：

git branch          # 本地分支（* 表示当前所在）
git branch -r       # 远程分支
git branch -a       # 所有分支

创建并切换到新分支：

git checkout -b dev

等价于 git branch dev + git checkout dev。

切换分支：

git checkout master

推送新分支到远程：

git push -u origin dev

合并分支（将 dev 合并到 master）：

git checkout master
git pull origin master
git merge dev
git push origin master

删除分支：

git branch -d dev              # 删除本地分支
git push origin --delete dev   # 删除远程分支

分支开发工作流示例

# 1. 创建并切换到功能分支
git checkout -b feature-login

# 2. 修改代码，提交
git add .
git commit -m "feat: 实现用户登录功能"

# 3. 推送到远程备份
git push origin feature-login

# 4. 开发完成，合并到 dev
git checkout dev
git pull origin dev
git merge feature-login
git push origin dev

# 5. 清理本地功能分支
git branch -d feature-login

标签与发布

标签的作用

标签（Tag）用于标记代码仓库中的特定版本，如 v1.0.0、v2.3.1 等。它相当于一个“书签”，让你可以在任何时候回到这个精确的代码状态。

标签操作

创建附注标签（推荐）：

git tag -a v1.0.0 -m "发布 v1.0.0 正式版"

查看所有标签：

git tag

推送标签到远程：

git push origin v1.0.0
# 推送所有标签：git push origin --tags

删除标签：

git tag -d v1.0.0                # 删除本地标签
git push origin --delete v1.0.0  # 删除远程标签

发行版（Release）

git 命令本身不直接创建 Release。Release 是代码托管平台提供的分发功能，用于上传安装包、展示更新日志。

GitHub：可使用官方 CLI 工具 gh release create v1.0.0，或通过网页创建。
Gitee：需在网页上基于已推送的 Tag 创建 Release。
GitCode：可在网页的项目页面创建 Release。

推荐流程：打 Tag → 推送 Tag → 到平台网页上将 Tag 转为 Release。

各平台差异与注意事项

核心区别速览

特性	GitHub	Gitee	GitCode
Git LFS（免费版）	每月 1GB 存储 + 1GB 带宽	❌ 仅付费企业版支持	✅ 免费开放
仓库总容量限制	建议 ≤ 5GB	约 500MB	个人用户约 10GB
单文件大小限制	无硬性限制	无硬性限制	默认 10MB，可调至 100MB
推送凭证方式	Token / SSH	Token / SSH	Token / SSH
默认分支名称	`main`	`master`	`master`

Gitee 特别提醒

不要使用 Git LFS：Gitee 免费版不支持 LFS。如已启用 LFS，推送时会报错 LFS batch error。解决方案：
- 删除 .git/hooks/pre-push 文件；
- 或执行 git lfs install --skip-smudge 跳过 LFS 下载。
邮箱隐私保护：Gitee 默认禁止命令行推送暴露个人邮箱。如遇到 hook declined 错误，请在 Gitee 设置 → 邮箱管理中取消勾选“禁止命令行推送暴露个人邮箱”。
仓库大小限制：免费版约 500MB，请务必通过 .gitignore 排除大文件，并定期使用 git count-objects -vH 检查仓库体积。

GitCode 特别提醒

单文件大小限制：新建仓库默认单文件上限为 10MB。如需推送大文件（≤ 100MB），需在仓库设置中调整限制，然后执行 git fetch 并重新推送。
Git LFS 免费开放：GitCode 免费支持 LFS，适合管理大文件。
网络优势：GitCode 服务器在国内，访问和推送速度显著优于境外平台。

GitHub 特别提醒

网络连接：国内访问 GitHub 可能较慢，建议使用 SSH 协议或配置代理。
Git LFS 限额：每月 1GB 存储和 1GB 带宽的限额对个人项目通常够用，但需留意大型项目超出限额。

常见问题与解决方案

推送相关错误

错误信息	原因	解决方案
`fatal: not a git repository`	未执行 `git init`	先执行初始化命令。
`src refspec master does not match any`	本地没有提交记录	先执行 `git commit`。
`hook declined`（Gitee）	暴露了真实邮箱	在 Gitee 设置中关闭邮箱保护。
`LFS batch error`（Gitee）	免费版不支持 LFS	删除 `.git/hooks/pre-push` 或跳过 LFS。
`size of the file has exceeded the limited size (10 MiB)`（GitCode）	单文件超限	在仓库设置中调整限制至 100MB。
`curl 55 Send failure`	网络超时或数据量过大	`git config http.postBuffer 524288000` 或换用 SSH。
`failed to push some refs`	远程有本地没有的新提交	先执行 `git pull origin master --rebase`。

克隆相关错误

错误信息	原因	解决方案
`Smudge error: LFS only supported repository in paid or trial enterprise`（Gitee）	仓库包含 LFS 文件，但免费版不支持	克隆后进入目录，执行 `git lfs install --skip-smudge` 和 `git restore --source=HEAD :/`。
`clone succeeded, but checkout failed`	LFS 文件检出失败	同上处理。

仓库空间相关问题

Q：Gitee 显示 200MB，本地克隆却有 500MB，正常吗？

A：完全正常。原因如下：

远程存储的是压缩包（.git/objects/pack/），体积较小。
本地不仅有压缩包，还有解压后的工作目录文件（源代码本身）。
本地总大小 ≈ .git 目录（压缩历史）+ 工作目录（解压后的源代码）。

查看本地仓库压缩大小：

git count-objects -vH

重点关注 size-pack 字段，该值应与平台显示的仓库大小接近。

压缩本地仓库：

git gc --aggressive --prune=now

常用命令速查表

操作	命令
查看状态	`git status`
添加所有文件到暂存区	`git add .`
提交到本地仓库	`git commit -m "说明"`
关联远程仓库	`git remote add origin <仓库地址>`
首次推送	`git push -u origin master`
推送更新	`git push`
拉取远程更新	`git pull`
查看分支	`git branch`
创建并切换分支	`git checkout -b <分支名>`
切换分支	`git checkout <分支名>`
合并分支	`git merge <分支名>`
创建标签	`git tag -a v1.0.0 -m "说明"`
推送标签	`git push origin v1.0.0`
查看提交历史	`git log --oneline --graph --all`
丢弃工作区修改	`git restore <文件>`
撤销暂存	`git restore --staged <文件>`
临时隐藏未提交修改	`git stash` → `git stash pop`
查看仓库压缩大小	`git count-objects -vH`
压缩仓库	`git gc --aggressive`