Git 与 GitLab 基础使用教程

其余使用默认选项即可。

注意：建议最后一步勾选 Launch Git Bash，打开 Git 命令行（后续所有命令在 Git Bash 里敲）。

2.1.3 验证

输入以下命令，验证 Git 安装是否成功：

git --version

2.2 配置个人信息（关联公司 GitLab 账号）

Git 会记录每一次提交的作者，必须和公司 GitLab 的账号一致，否则提交记录会显示未知用户。

2.2.1 打开 Git Bash / 终端，输入以下两条命令（替换成你的信息）：

git config --global user.name "你的 GitLab 用户名"
git config --global user.email "你在公司的邮箱"

2.2.2 验证

验证配置是否成功：

git config --list

2.2.3 配置 SSH 密钥（免密访问公司 GitLab）

如果不配这个，每次拉/推代码都要输账号密码，还容易报错。公司内网 GitLab 几乎都要求用 SSH 密钥：

1. 生成 SSH 密钥（Git Bash / 终端输入，一路回车，不要改任何默认值）：

ssh-keygen -t ed25519 -C "你在公司的邮箱"

• 执行后会提示 Enter file in which to save the key，直接回车（默认保存到 ~/.ssh 文件夹）；
• 提示 Enter passphrase（密码），直接回车（免密，后续操作不用输密码）；
• 提示 Enter same passphrase again，再回车。

2. 找到并复制公钥

• Windows：在 Git Bash 输入 cat ~/.ssh/id_ed25519.pub，会显示一串以 ssh-ed25519 开头、你的邮箱结尾的字符串，全选复制（按 Ctrl+C，注意不要漏字符）；

3. 把公钥添加到公司 GitLab：

• a. 登录公司 GitLab 网页（比如 http://gitlab.公司域名.com）；
• b. 点击页面右上角的个人头像 → 选择 Settings（设置）；
• c. 左侧菜单栏找到 SSH Keys（SSH 密钥）；
• d. 粘贴刚才复制的公钥到 Key 输入框，Title 可以填我的办公电脑（随便填，方便识别）；
• e. 点击 Add key（添加密钥），验证：Git Bash / 终端输入 ssh -T git@公司域名（替换成你公司的 GitLab 域名），如果显示 Welcome to GitLab, @你的用户名!，说明 SSH 配置成功！

3. 手把手实操

假设公司 GitLab 有一个测试项目（如果没有，让 leader 给你开一个测试仓库，或自己新建一个），我们完整走一遍开发→提交→提 MR→合并的流程，每一步都写死命令和操作：

前置准备：找到公司 GitLab 仓库的 SSH 地址

登录公司 GitLab → 进入目标项目 → 点击页面上方的 Clone（克隆）按钮 → 选择 SSH 标签 → 复制显示的地址（比如 git@gitlab.公司域名.com:测试项目组/测试项目.git）。

3.1 克隆仓库到本地

目的：把 GitLab 上的远程仓库，复制一份到你本地电脑，后续所有开发都在本地克隆的文件夹里做。

1. 打开 Git Bash / 终端，先切换到你想存放代码的目录（比如桌面）：

cd /c/Users/你的用户名/Desktop

2. 执行克隆命令（粘贴刚才复制的 SSH 地址）：

git clone git@gitlab.公司域名.com:测试项目组/测试项目.git

3. 预期结果：终端显示 Cloning into '测试项目'...，最后无报错，说明克隆成功；此时你的桌面会多出一个测试项目文件夹（这就是你的本地工作区）。

3.2 分支操作（核心！绝对不要直接改主分支）

公司规范：main/master（主分支）是生产环境代码，dev（开发分支）是团队共用分支，你必须从 dev 分支新建自己的功能分支开发。

1. 先进入克隆好的项目文件夹：

cd 测试项目 # 进入项目根目录，后续所有命令都要在这个目录下执行！

2. 查看当前所有分支（本地 + 远程）：

git branch -a # -a 表示 all，查看所有分支

输出示例：* main（* 表示当前在 main 分支）、remotes/origin/dev（远程的 dev 分支）。

3. 切换到远程 dev 分支，并拉取最新代码（避免你的本地分支落后）：

# 切换到 dev 分支（如果本地没有，会自动创建并关联远程 dev）
git checkout dev
# 拉取远程 dev 分支的最新代码（同步同事的修改）
git pull origin dev

4. 新建你的个人功能分支（命名按公司规范，比如 feature/日期 - 功能名）：

# -b 表示'新建并切换到该分支'，示例：feature/20251209-新增登录功能
git checkout -b feature/20251209-新增登录功能

5. 验证：执行 git branch，会看到 * feature/20251209-新增登录功能，说明已成功切换到自己的功能分支。

3.3 本地开发 + 提交代码（核心命令）

现在你可以在测试项目文件夹里修改代码（比如新建一个 login.py 文件，写几行测试代码），然后把修改提交到本地仓库：

1. 先查看本地代码状态（每次提交前必做，确认修改内容）：

git status

预期输出：Untracked files: (use "git add ..." to include in what will be committed) login.py，说明 Git 检测到你新建了 login.py 文件。

2. 将修改加入暂存区（相当于把商品加入购物车）：

# 方式 1：添加指定文件（推荐，避免误加无关文件）
git add login.py
# 方式 2：添加所有修改（适合一次性改了多个文件）
# git add .

3. 再次执行 git status，会看到 Changes to be committed: login.py，说明文件已进入暂存区。

4. 将暂存区的修改提交到本地仓库（相当于结账，生成一条提交记录）：

# -m 后面是提交信息，必须按公司规范写！格式：类型：功能描述
# 常见类型：feat（新增功能）、fix（修复 bug）、docs（修改文档）、style（格式调整）
git commit -m "feat: 新增用户登录接口，实现手机号验证"

预期输出：显示 1 file changed, 3 insertions(+)，说明提交成功。

3.4 推送本地分支到 GitLab 远程仓库

目的：把你本地的功能分支和提交记录，上传到 GitLab，让同事能看到，也为了后续提 MR。

1. 执行推送命令（第一次推送新分支，需要指定远程仓库和分支名）：

# origin 是远程仓库的默认名称，后面跟你的功能分支名
git push origin feature/20251209-新增登录功能

预期输出：显示 Total 0 (delta 0), reused 0 (delta 0)，最后提示 To gitlab.公司域名.com:测试项目组/测试项目.git * [new branch] feature/20251209-新增登录功能 -> feature/20251209-新增登录功能，说明推送成功。

2. 验证：登录公司 GitLab → 进入测试项目 → 点击左侧 Repository→Branches，能看到你刚推送的分支，说明成功。

3.5 提 Merge Request（MR，GitLab 协作核心）

MR 是请求把你的功能分支合并到 dev 分支，需要 leader / 同事审核通过后才能合并，这是公司协作的关键步骤（对应 GitHub 的 PR）：

1. 登录公司 GitLab → 进入测试项目 → 页面顶部找到 Merge Requests→ 点击 New merge request（新建 MR）；
2. 选择分支：
   • Source branch（源分支）：选你刚推送的 feature/20251209-新增登录功能；
   • Target branch（目标分支）：选 dev（绝对不要选 main/master！）；
   • 点击 Compare branches and continue（对比分支并继续）；
3. 填写 MR 信息（按公司规范，越详细越好）：
   • Title（标题）：和提交信息一致，比如 feat: 新增用户登录接口，实现手机号验证；
   • Description（描述）：写清楚你做了什么、测试了什么、需要注意什么（比如 1. 新增 login.py 实现手机号正则校验；2. 测试了正确 / 错误手机号场景；3. 依赖 requests 库）；
   • （可选）Assignee（审核人）：选择你的 leader 或指定的审核同事；
   • 点击 Create merge request（创建 MR），此时 MR 就提交成功了，等待审核

3.6 MR 审核通过后 → 合并 + 清理分支

1. 审核通过后，GitLab 页面会显示 Merge 按钮，点击它（一般由审核人点，或你确认后点），选择 Merge commit（合并提交），完成分支合并；
2. 合并后，清理本地和远程的功能分支（避免分支过多混乱）：

# 第一步：切回 dev 分支，拉取合并后的最新代码
git checkout dev
git pull origin dev
# 第二步：删除本地的功能分支（-d 表示删除已合并的分支）
git branch -d feature/20251209-新增登录功能
# 第三步：删除远程的功能分支（可选，公司一般要求合并后删除）
git push origin --delete feature/20251209-新增登录功能

4. 新手高频问题与解决（避坑指南）

问题 1：git pull/push 报错 Permission denied (publickey)

原因：SSH 密钥配置错误，解决步骤：

1. 检查 SSH 密钥是否正确添加到 GitLab：重新走配置 SSH 密钥的步骤，确认公钥复制完整（不要多空格 / 少字符）；
2. 验证 SSH 连接：ssh -T git@公司域名，如果显示 Welcome 说明没问题，否则重新生成密钥。

问题 2：提 MR 后提示代码冲突

原因：你开发时，同事已经修改了 dev 分支的同一文件，解决步骤：

1. 切回你的功能分支，拉取 dev 分支的最新代码并合并：

git checkout feature/20251209-新增登录功能
git pull origin dev # 拉取 dev 最新代码，此时会提示 Automatic merge failed; fix conflicts and then commit the result.

2. 打开冲突文件：文件里会有 <<<<<<< HEAD（dev 分支的代码）、=======（你的代码）、>>>>>>> feature/xxx 标记，手动删除标记并保留正确代码；

3. 解决后重新提交并推送：

git add 冲突文件名
git commit -m "fix: 解决 dev 分支代码冲突"
git push origin feature/20251209-新增登录功能

4. 此时 GitLab 的 MR 会自动更新，冲突标记消失。

问题 3：提交错分支（比如误改了 dev 分支）

解决步骤：

1. 先暂存你的修改（避免丢失）：

git stash # 把当前修改暂存起来，工作区恢复到干净状态

2. 切到正确的功能分支，恢复暂存的修改：

git checkout feature/20251209-新增登录功能
git stash pop # 恢复暂存的修改到当前分支

3. 如果已经误提交到 dev 分支，需要回滚：

# 先查看提交记录，找到错误提交前的 ID（比如 abc123）
git log --oneline
# 回滚到错误提交前的版本（--hard 表示彻底回滚，慎用！）
git reset --hard abc123
# 推送到远程 dev 分支（需要权限，一般找 leader 确认）
git push origin dev --force

问题 4：想撤销已暂存的文件（比如 git add 加错了文件）

# 撤销指定文件的暂存
git reset HEAD 错误文件名
# 撤销所有暂存的文件
git reset HEAD .

5. 必背核心命令（新手版，记这些就够了）

6. 新手学习建议（效率最高）

1. 实操优先：不要只看教程，找公司的测试仓库（或自己新建一个空仓库），每天花 1 小时，重复克隆→建分支→改代码→提交→推分支→提 MR→合并→删分支全流程，至少做 3 遍，肌肉记忆就形成了；
2. 对齐公司规范：主动问 leader 要 3 样东西：① 公司的分支命名规范；② 提交信息规范；③ MR 模板，严格按规范来，避免返工；