远程仓库

字数: 0 字 时长: 0 分钟

远程仓库（Remote Repository）是托管在 GitHub、Gitee、GitLab 等平台上的 Git 仓库，用于备份代码、多人协作和跨设备同步。

本地仓库 ←→ 远程仓库 ←→ 其他开发者的本地仓库

1. 基本概念

1.1 origin 是什么

origin 是远程仓库常用的默认别名。设置后，后续命令不用反复书写完整仓库地址。

git remote add origin <repo-url>

origin 只是约定名称，也可以换成其他名字。

1.2 HTTPS 和 SSH

方式	特点	适用场景
HTTPS	配置简单，认证时通常需要 Token 或凭据管理	临时使用、新手、CI 环境
SSH	配置 SSH Key 后通常不用重复认证	日常开发、长期使用

2. 将已有本地项目推送到新建的 Gitee 仓库

2.1 创建空仓库

登录 Gitee 后新建仓库。因为本地项目已经存在提交记录，创建时不要初始化 README、.gitignore 或 LICENSE，避免本地和远程产生两套无关的提交历史。

创建完成后，复制仓库页面提供的 HTTPS 或 SSH 地址。

2.2 确认当前分支

在本地项目目录执行：

git branch --show-current

输出可能是 main 或 master，后续命令应使用实际分支名。下面以 main 为例。

2.3 添加并检查远程仓库

git remote add origin <repo-url>
git remote -v

如果已经存在 origin，先用 git remote -v 检查地址，不要重复添加。需要修改时使用：

git remote set-url origin <repo-url>

2.4 首次推送

git push -u origin main

-u（--set-upstream）会建立本地 main 与远程 main 的跟踪关系。首次推送成功后，通常可以直接使用 git push 和 git pull。

3. 日常同步

开始工作前先拉取远程更新：

git pull

本地提交完成后推送：

git push

只想查看远程更新、不立即合并时使用：

git fetch

fetch 只更新远程分支信息；pull 会拉取远程更新，并尝试整合到当前分支。

4. 克隆已有远程仓库

如果本地还没有项目，直接克隆即可：

git clone <repo-url>

克隆会下载文件、提交历史和远程仓库配置，不需要再次执行 git remote add origin。

5. 特殊情况：远程仓库已经有初始提交

如果 Gitee 仓库创建时初始化了 README、.gitignore 或 LICENSE，而本地项目也已经有独立提交，两边可能没有共同历史。此时不要把下面的命令当作正常流程；先确认确实需要合并两套历史，再执行：

git pull origin main --allow-unrelated-histories --no-rebase

如果产生冲突：

1. 打开冲突文件，保留需要的内容并删除冲突标记。
2. 执行 git add <file>。
3. 执行 git commit 完成合并。
4. 最后执行 git push -u origin main。

如果实际分支名是 master，请将以上命令中的 main 替换为 master。

6. 常见问题

提示远程仓库已存在

git remote -v
git remote set-url origin <repo-url>

推送被拒绝

先确认远程是否存在其他提交，再决定拉取合并或变基，不要直接强制推送。

HTTPS 认证失败

检查 Gitee 的 Token 或系统凭据管理配置。

SSH 连接失败

检查公钥是否已添加到 Gitee，并测试连接：

ssh -T git@gitee.com

7.

完整实验记录

下面记录一次完整的测试过程。这个实验中的远程仓库初始化了 .gitignore、LICENSE 和 Initial commit，因此本地与远程产生了两套独立历史。它用于演示特殊情况，不是新项目首次推送的推荐流程。

7.1 打开并登录 Gitee

进入 Gitee 网站。

注册或登录个人账号。

7.2 新建测试仓库

从页面右上角进入新建仓库。

填写测试仓库信息。正文前面已经保留了仓库创建页面和创建结果截图。

7.3 获取仓库地址

仓库同时提供 HTTPS 和 SSH 两种地址。

HTTPS 地址：

SSH 地址：

7.4 添加并检查 origin

将测试仓库地址添加为本地仓库的 origin。

检查远程仓库配置是否正确。

7.5 拉取远程初始提交

因为远程仓库已经有初始提交，本次实验使用 --allow-unrelated-histories 拉取并合并。

完成认证后继续拉取。

7.6 解决 .gitignore 冲突

本地与远程都存在 .gitignore，因此合并时产生冲突。处理冲突标记并保留最终需要的忽略规则。

7.7 推送并验证

解决冲突并提交后，执行首次推送。

正文前面已经保留了网页端推送成功的截图。

7.8 再次修改并推送

新建 my.txt，写入测试内容，再次提交并推送，用于确认后续同步流程已经正常。