Git 使用教程：从零开始把代码推送到 Gitee

一、Git 是什么？

Git 是一个版本控制工具，简单来说就是帮你记录代码的每一次修改历史。

好处：

• 代码改坏了可以回到之前的版本
• 可以看到每次改了什么内容
• 可以把代码同步到云端（GitHub / Gitee），换电脑也不怕丢失

---

二、核心概念

在学命令之前，先理解这几个概念：

概念	解释
仓库（Repository）	一个被 git 管理的项目文件夹
暂存区（Stage）	提交之前的"草稿区"，先把改动放在这里
提交（Commit）	把暂存区的内容正式保存为一个版本记录
远程仓库（Remote）	云端的仓库，比如 Gitee / GitHub 上的仓库
分支（Branch）	代码的不同版本线，默认叫 master

整个流程是：工作区 → 暂存区 → 本地仓库 → 远程仓库

---

三、安装与初次配置

安装 Git

前往 https://git-scm.com 下载安装，安装完成后打开 Git Bash。

配置用户信息（只需做一次）

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

• --global 表示全局配置，对这台电脑上所有 git 项目生效
• 这个信息会显示在每次提交记录里，让别人知道是谁提交的

---

四、初始化仓库

进入你的项目目录，运行：

git init

这条命令会在项目里创建一个隐藏的 .git 文件夹，git 从此开始追踪这个目录里的所有变化。

运行后会看到：

Initialized empty Git repository in .../你的项目/.git/

或者：

Reinitialized existing Git repository in .../你的项目/.git/

两种都正常，说明仓库已经准备好了。

---

五、创建 .gitignore 文件

.gitignore 是一个文本文件，告诉 git 哪些文件不需要上传。

为什么需要它？因为项目里有些文件是不应该提交的：

• build/ 文件夹：编译出来的二进制文件，体积大，每次编译都会变
• *.user 文件：IDE 的个人配置，别人用不上
• *.o / *.obj：编译中间产物

Qt/CMake 项目推荐的 .gitignore 内容：

# 编译产物
build/
*.o
*.obj

# Qt 自动生成的文件
moc_*
qrc_*
ui_*

# IDE 配置文件
*.user
CMakeLists.txt.user
.qtc_clangd/

# Windows 系统文件
Thumbs.db
desktop.ini

在 Git Bash 里创建这个文件：

cat > .gitignore << 'EOF'
build/
*.o
*.obj
moc_*
qrc_*
ui_*
*.user
CMakeLists.txt.user
EOF

---

六、第一次提交代码

提交分三步：查看状态 → 加入暂存区 → 提交

第一步：查看状态

git status

这条命令显示当前哪些文件被修改了、哪些是新文件、哪些已经在暂存区。

输出示例：

Untracked files:
  .gitignore
  CMakeLists.txt
  main.cpp
  Main.qml

Untracked files 表示这些文件还没有被 git 追踪过。

第二步：加入暂存区

git add .

• git add 是把文件放入暂存区的命令
• . 表示当前目录下的所有文件
• 也可以指定单个文件：git add main.cpp

第三步：提交

git commit -m "完成了QML的第一页界面"

• commit 是把暂存区内容正式保存为一个版本的命令
• -m 后面跟提交说明，用双引号包起来
• 提交说明要写清楚这次改了什么，方便以后查看历史

提交成功后会看到：

[master (root-commit) 05ee628] 完成了QML的第一页界面
 8 files changed, 266 insertions(+)

• master 是当前分支名
• 05ee628 是这次提交的唯一 ID（每次都不同）
• 8 files changed 表示有 8 个文件发生了变化

---

七、推送到 Gitee

第一步：在 Gitee 上创建仓库

1. 打开 https://gitee.com 登录账号
2. 点右上角 + → 新建仓库
3. 填写仓库名，不要勾选"使用 Readme 初始化仓库"
4. 点击创建，复制仓库地址（格式：https://gitee.com/用户名/仓库名.git）

第二步：关联远程仓库

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

• remote add 是添加远程仓库地址的命令
• origin 是给这个远程仓库起的别名，是约定俗成的名字，也可以改成其他名字
• 后面跟的是仓库的完整地址

第三步：推送代码

git push -u origin master

• push 是把本地代码推送到远程仓库的命令
• -u 表示把本地 master 分支和远程 origin/master 绑定
• 只需要第一次加 -u，之后直接用 git push 就够了
• 运行后会弹出登录窗口，输入 Gitee 账号和密码

推送成功后会看到：

To https://gitee.com/用户名/仓库名.git
 * [new branch]      master -> master
branch 'master' set up to track 'origin/master'.

---

八、日常开发流程

每次改完代码，重复这三步：

git add .
git commit -m "说明这次改了什么"
git push

就这三条命令，代码就同步到云端了。

---

九、常用命令速查表

命令	作用
git status	查看哪些文件改了还没提交
git add .	把所有改动加入暂存区
git add 文件名	把指定文件加入暂存区
git commit -m "说明"	提交暂存区内容，附上说明
git push	推送到远程仓库
git log --oneline	查看简洁的提交历史
git diff	查看具体改了哪些内容
git restore 文件名	撤销某个文件未提交的改动
git remote -v	查看当前关联的远程仓库地址

---

十、常见问题

Q：git add 和 git add . 有什么区别？
git add 后面必须跟文件名或路径，单独运行没有效果。. 代表当前目录，所以 git add . 是把当前目录下所有改动都加入暂存区。

Q：提交说明写什么好？
写清楚这次做了什么，比如"修复登录页面崩溃问题"、“新增视频播放功能”，避免写"改了一些东西"这种没有意义的说明。

Q：推送时出现 libpng warning 是什么？
这是 git 凭证管理器界面的图片格式警告，和你的代码完全无关，忽略即可。

Q：以后换电脑怎么把代码拉下来？

git clone https://gitee.com/用户名/仓库名.git

clone 命令会把远程仓库完整下载到本地，包括所有历史记录。

---

十一、坑：第三方库源码没上传上去

场景复现

你把一个第三方库的源码（比如 libmodbus）用 git clone 拉到项目里：

git clone https://github.com/stephane/libmodbus.git src/3rdparty/libmodbus

然后正常提交推送：

git add .
git commit -m "集成了libmodbus"
git push

推送完上 Gitee 一看，src/3rdparty/libmodbus 点不进去，源码根本不在上面。

原因

git clone 拉下来的目录自带一个 .git 文件夹：

src/3rdparty/libmodbus/
├── .git/          ← 这个害的！libmodbus 仓库自己的 git 历史
├── modbus.c
├── modbus.h
└── ...

你的项目本身就是一个 git 仓库。当 git 发现仓库里面还套着另一个 .git，它不会把文件正常提交，而是把这个目录当成子模块（submodule），只存一个指针（160000 模式）。所以云端看不到实际文件。

解决办法

# 1. 删掉第三方库里的 .git 文件夹
rm -rf src/3rdparty/libmodbus/.git

# 2. 从暂存区移除错误的 gitlink 记录（--cached 不删磁盘文件）
git rm --cached src/3rdparty/libmodbus

# 3. 重新添加为普通文件
git add src/3rdparty/libmodbus

# 4. 提交修复
git commit -m "修复：将 libmodbus 从 gitlink 改为普通文件"
git push

命令解释

命令	通俗理解
rm -rf xxx/.git	把炸弹拆掉（删除残留的 git 目录）
git rm --cached xxx	把货单上写错的划掉（从 git 记录删除，但保留磁盘文件）
git add xxx	重新登记为普通货物（重新追踪为正常文件）

如何提前发现

git add . 时如果看到这句警告，就要注意了：

warning: adding embedded git repository: src/3rdparty/libmodbus

这说明目录里有 .git，会被当成子模块。立马 Ctrl+C 取消，删掉 .git 再重新 git add。

记住

拉第三方源码进项目 → 如果不是子模块 → 先删 .git，再 git add。