李永旗

站内搜索

输入标题、简介或关键词开始搜索

技术经验

Git 团队协作远程操作完整指南

快速入门Git，进行团队协作。包括基础的Git操作，日常开发流程，如何通过SSH与远程仓库建立连接。

Git

Git 团队协作远程操作完整指南（从0到1 · SSH 版）

适配内网 GitLab 、公网github场景：

一、创建本地仓库（完成本地首次版本提交）

适用于本地已有项目代码，从零纳入 Git 管理的场景。

  1. 初始化本地 Git 仓库 进入项目根目录，执行初始化，生成 .git 版本管理目录：
cd 你的项目文件夹路径
git init
  1. 添加文件到暂存区
# 添加项目内所有文件
git add .

# 或只添加指定文件/文件夹
git add 文件名/文件夹名

建议提前配置 .gitignore 文件，排除编译产物、日志、临时文件等无需版本管理的内容。

  1. 提交代码到本地仓库
git commit -m "feat: 新增小龙虾剥虾头视觉识别模块"

提交信息建议格式：类型: 简短描述

  • feat：新增功能
  • fix：修复问题
  • docs：文档更新
  • refactor：代码重构
  • 如果你的电脑上首次使用 Git， 必须设置git用户名，否则提交代码会报错身份未知：
# 全局配置（所有仓库共用）
git config --global user.name "用户名"
git config --global user.email "你的邮箱"

只执行一次，后续所有项目不用重复设置。

二、与远程仓库建立联系

2.1 本地 SSH 密钥配置（仅首次本机配置）

Gitlab SSH密钥配置
GitHub SSH密钥配置教程

2.2 本地仓库关联远程仓库

把本地仓库和 GitLab /github 上的目标仓库绑定，只需执行一次。

  1. 执行关联命令
# 格式：git remote add <远程别名> <远程仓库SSH地址>
git remote add origin git@10.10.100.100:xiao_long_xia/crayfish-ii.git
  • origin：远程仓库的本地别名，业界约定俗成使用 origin，可自定义
  • 后面的 SSH 地址：对应 远程git 仓库的SSH 克隆地址，不是HTTPS地址
  • 关联时确保在本地Git仓库的目录下
  1. 验证关联结果
# remote -v :查看远程仓库地址
git remote -v

输出两行（分别对应拉取、推送地址），地址正确即关联成功：

origin  git@10.10.100.100:xiao_long_xia/crayfish-ii.git (fetch)
origin  git@10.10.100.100:xiao_long_xia/crayfish-ii.git (push)

补充：如果是直接从远程克隆仓库（git clone 地址），会自动完成 origin 关联，无需手动执行 git remote add。

三、日常开发常用流程

如果你是首次上传自己代码，代码与现有模块没有关联，略过1、2、3、节。 进行第四节中的代码推送

1. 开发前：同步远程主分支最新代码

每次开发前必须执行，避免基于旧代码开发导致后续大量合并冲突：

# 切换到主分支； switch 分支名：切换到指定分支
git switch feature/robot_bringup

# 拉取远程最新代码到本地；pull 用来拉取远程代码
git pull

2. 新建功能开发分支

基于最新的主分支，创建自己的开发分支：

# switch -c 新分支名 ：创建并切换到新分支
git switch -c feature/你的新分支

3. 编码后：提交本地变更

# 查看修改了哪些文件，确认变更范围
git status

# 添加修改的文件到暂存区
git add 文件名
# 或添加全部修改文件，要先写.gitignore文件
git add .

# 提交到本地仓库，写清变更说明
git commit -m "fix: 修复触觉传感器数据解析异常"

4. 推送分支到远程仓库

  • 首次推送该分支，建议加 -u 绑定上游追踪关系，后续操作可简写：
git push -u origin main
  • 绑定上游之后，该分支后续的推送/拉取可直接简写：
git push
git pull

5. 分支提交合并请求（MR / Merge Request）

推送成功后，终端会输出 GitLab 的 MR 创建直达链接，点击即可跳转创建；也可在网页端手动操作：

  1. 进入 GitLab 仓库页面 → 左侧 Merge Requests → New merge request
  2. 源分支选择你的 feature/xxx 功能分支，目标分支选择主分支 feature/robot_bringup
  3. 填写标题、改动说明、测试情况，指派代码评审人
  4. 提交 MR，等待评审

6. 代码评审与迭代

  • 评审人提出修改意见：你在本地对应分支修改代码后，重复「提交 → 推送」步骤，更新会自动同步到同一个 MR
  • 评审通过后：由仓库负责人执行合并，代码正式合入主分支

四、常用操作

1、分支命名规范

  • 主分支：feature/robot_bringup（受保护分支，禁止直接推送，必须走 MR 流程）
  • 功能分支：feature/模块名_功能名，例如 feature/peel_crafish
  • 修复分支：fix/问题描述，例如 fix/camera_frame_delay

2、处理代码冲突

当 git pull 或合并提示冲突时：

  1. 打开冲突文件，找到 <<<<<<< ======= >>>>>>> 标记的冲突区域
  2. 手动修改保留正确代码，删除所有冲突标记
  3. 执行 git add 和 git commit 完成合并：
git add 冲突文件
git commit -m "merge: 解决代码合并冲突"
git push

3、常用值令汇总

1、仓库状态与提交记录

命令作用
git status查看当前仓库状态
git log查看完整提交历史
git log --oneline简洁查看提交历史
git show查看最近一次提交的详细信息
git diff查看工作区与暂存区之间的差异
git diff --staged查看暂存区与最近一次提交之间的差异

2、远程仓库管理

这一部分主要用于 GitHub 和 GitLab 的远程同步。

命令作用
git remote -v查看远程仓库
git remote add origin 地址添加远程仓库
git remote set-url origin 地址修改远程仓库地址
git remote remove origin删除远程仓库关联
git fetch获取远程更新，但不自动合并
git pull拉取远程更新并整合到当前分支
git push推送本地提交到远程仓库
git push origin 分支名推送指定分支
git push -u origin 分支名首次推送并建立上游追踪关系
git clone 地址克隆远程仓库到本地
示例：
# 获取远程仓库最新的分支和提交信息，但不会直接修改当前工作区
git fetch origin
# 获取并整合
git pull origin main

3、文件管理

这一部分非常重要，开发过程中经常会遇到误修改、误添加、误提交的情况。

命令作用
git add 文件名将文件添加到暂存区
git add .添加当前目录下的变更
git rm 文件名删除文件并记录删除操作
git mv 原文件 新文件移动或重命名文件
git rm --cached 文件名停止跟踪文件，但保留本地文件
git restore 文件名丢弃工作区指定文件的未暂存修改
git restore .丢弃当前目录下所有未暂存修改
git restore --staged 文件名将文件从暂存区移回工作区但保留本地修改
git commit --amend修改最近一次提交
git reset --soft HEAD~1撤销最近一次提交，保留暂存区和工作区内容
git reset HEAD~1撤销最近一次提交，只保留工作区修改内容
git reset --hard HEAD~1撤销最近一次提交，丢弃对应工作区和暂存区修改
git revert 提交ID通过新增一次反向提交来撤销指定提交
示例
# 如果你修改了 `main.cpp`，但是想恢复到上次提交的状态：
git restore main.cpp

# 如果你执行了 git add . 要取消暂存区的提交
git restore --staged .

# 如何你已经提交了一次代码，但是发现提交内容有问题。
git reset --soft HEAD~1

#如果代码已经推送到 GitHub，撤销提交，通常优先考虑 
git revert HEAD

# 如果想取消 Git 跟踪，但保留本地文件
git rm --cached main.cpp

3、分支管理

命令作用
git branch查看本地分支
git branch 分支名创建分支，但不切换
git switch 分支名切换分支
git switch -c 分支名创建并切换到新分支
git branch -d 分支名删除已经合并的本地分支
git branch -D 分支名强制删除本地分支
git branch -m 新名称重命名当前分支
git merge 分支名将指定分支合并到当前分支
git merge --abort取消正在进行的合并
git rebase 分支名将当前分支的提交重新应用到指定分支之上
git cherry-pick 提交ID将指定提交应用到当前分支

示例：

# 查看当前分支
git branch

# 删除本地功能分支
git branch -d feature/add-mpc

4、暂存工作区：git stash

这是一个很实用的功能。假设你正在开发一个功能，代码还没有写完，但是突然需要切换到另一个分支修复 Bug。此时可以暂时保存当前修改。

命令作用
git stash暂存当前已跟踪文件的修改
git stash push -u暂存修改，包括未跟踪文件
git stash list查看暂存记录
git stash pop恢复最近一次暂存并删除对应记录
git stash apply恢复最近一次暂存，但保留记录
git stash drop删除最近一次暂存记录
git stash clear清空所有暂存记录

示例：

# 暂存当前修改
git stash push -u
# 切换分支
git switch main

# 修复其他问题并完成提交

# 切回原来的开发分支
git switch feature/add-mpc

# 恢复之前的修改
git stash pop

SSH 密钥配置流程

Gitlab SSH 密钥配置流程

  • 先获取 gitlab 账号
  • 登录账号 gitlab URL：

1、本地生成 SSH 公钥（Linux/macOS/WSL）

打开终端执行，替换为你 GitLab 绑定的邮箱：

# 生成ed25519加密密钥（推荐，安全性更高）
ssh-keygen -t ed25519 -C "你的gitlab邮箱"
  • 提示输入文件路径：直接回车默认保存 ~/.ssh/id_ed25519
  • 密钥密码（可选）：输入密码后每次使用 SSH 需解锁；不想输直接回车留空
  • 生成完成后，读取公钥内容：
cat ~/.ssh/id_ed25519.pub

复制全部输出，格式以 ssh-ed25519 开头。 Windows 纯 cmd/PowerShell 同理，若无 ssh 工具先安装 OpenSSH 客户端。

2、GitLab 页面「添加 SSH 密钥」表单填写字段说明

  1. 说明（密钥内容框） 粘贴刚刚复制的完整公钥，开头必须是 ssh-ed25519 /ssh-rsa/ecdsa 等合规前缀，不能粘贴私钥（不带.pub 的文件）。
  2. 标题 自定义标识，用于区分多台设备，示例： 本地台式机Ubuntu / MacBook开发本 / 服务器构建机 仅展示用途，不影响连接。
  3. 使用类型（二选一）
  • 仅认证 仅用于 git 拉取、推送、克隆仓库，日常开发选这个足够。
  • 认证与签名 除代码推拉，还支持 Git 提交签名，满足代码审计、合规校验场景；企业内部规范、开源提交签名需求勾选此项。
  1. 有效期（可选，推荐设置）
  • 不填：密钥永久有效，存在密钥泄露风险；
  • 设置日期：到期后该密钥自动失效，无法再通过 SSH 访问仓库；
  • 企业规范建议设置 90 天 / 180 天轮换，到期重新生成密钥上传。

3、测试联通性

终端执行

ssh -T git@10.10.100.100

出现欢迎提示即配置成功，之后即可使用 SSH 地址克隆仓库:

git clone git@10.10.100.100:分组/项目.git

GitHub SSH密钥配置教程

一、创建 GitHub 远程仓库

1.1 打开创建仓库页面

登录 GitHub：进入 Create a new repository页面。

1.2 填写仓库信息

填写字段填写说明
Owner你的 GitHub 账号
Repository name仓库名称，建议与本地项目名称保持一致
Description项目描述，可选
Choose visibility仓库可见性Public或 Private
Add READMEOff
Add .gitignoreNo .gitignore
Add licenseNo license
  • Choose visibility：如果项目暂时不希望公开，建议选择Private。如果准备公开发布开源项目，可以选择Public
  • 本教程的场景是本地仓库已经初始化，并且已经有本地提交，因此最后三个选项保持默认关闭。如果 GitHub 再创建一个 README 初始提交，就会形成两条独立的提交历史，首次推送可能出现冲突
  • 如果本地仓库尚未初始化、没有提交，并且你希望由 GitHub帮你创建初始文件，则可以根据实际需要选择这些选项；但这不属于本教程当前场景。

1.3创建仓库

确认信息后，点击页面底部的 Create repository。

创建成功后，GitHub 会进入仓库页面，并显示 Quick Setup信息。后续需要使用其中的 SSH 地址。

二、本地 SSH 密钥配置

SSH 密钥用于验证当前电脑是否有权限访问 GitHub 仓库。配置完成后，使用 SSH 地址进行克隆、拉取和推送时，通常不需要每次输入 GitHub 账号密码。

2.1 检查本地是否已有 SSH 密钥

终端执行：

ls -la ~/.ssh/

如果有密钥，常见的密钥文件名如下：

id_ed25519
id_ed25519.pub
  • 两个文件的区别： id_ed25519 私钥，保存在本地，用于身份认证 ，不可以上传到github id_ed25519.pub 公钥，用于提供给 GitHub
  • 文件名只是常见默认命名，并不是每台电脑都必须使用这个名称。~/.ssh/目录中也可能存在其他名称的密钥文件。

2.2 情况 A：已经有可复用的 SSH 密钥

如果之前为 GitLab 或其他服务生成过 SSH密钥，可以直接复用，不需要重新生成。GitHub 和 GitLab 都支持 SSH密钥钥认证；同一公钥可以添加到不同平台的账号设置中。

查看公钥：

cat ~/.ssh/id_ed25519.pub
  • 复制完整输出内容。输出通常以 ssh-ed25519 开头。只能复制 .pub 公钥文件的内容。
  • 如果想为 GitHub单独创建一对密钥，应使用新的文件名，避免覆盖已有密钥。

2.3 情况 B：本地没有 SSH 密钥，需要新建

终端执行：

# # 生成ed25519加密密钥（推荐，安全性更高）
ssh-keygen -t ed25519 -C "你的GitHub邮箱"

按照终端提示操作。当出现：

Enter file in which to save the key

直接按回车，默认保存到：

/home/你的用户名/.ssh/id_ed25519

接下来设置密钥密码（可选），不想设置可以直接回车两次。 生成完成后，查看公钥：

cat ~/.ssh/id_ed25519.pub

重要：如果终端提示目标文件已经存在，不要直接确认覆盖。 覆盖可能导致原有服务使用的密钥失效。可以取消本次操作，再使用单独的文件名，例如：

/home/你的用户名/.ssh/id_ed25519_github

如果使用了单独文件名，则相应查看：

cat ~/.ssh/id_ed25519_github.pub

2.4 将公钥添加到 GitHub

打开 GitHub SSH 密钥设置页面, 操作步骤：

  1. 点击 New SSH key。
  2. Title：填写设备名称，例如Ubuntu 22.04 Desktop，方便区分不同设备。
  3. Key type：选择 Authentication Key。
  4. Key：粘贴刚才复制的完整公钥内容。
  5. 点击 Add SSH key。

注意：这里添加的是公钥，不是私钥。 Authentication Key 用于 SSH身份认证；不要因为本教程是 Git 推送配置，就误选用于提交签名的Signing Key。

2.5 测试 SSH 连接

在 Ubuntu 终端执行：

ssh -T git@github.com

第一次连接时，可能会出现主机指纹确认提示：

Are you sure you want to continue connecting (yes/no/[fingerprint])?

确认主机指纹与 GitHub 官方公布的 SSH 主机指纹一致后，输入：

yes

认证成功时，会看到类似提示：

Hi 用户名! You've successfully authenticated, but GitHub does not provide shell access.

这表示 SSH 身份认证成功。提示中的 does not provide shell access是正常信息，不代表认证失败