Git remote 怎么用？远程仓库管理完整教程

Git remote 怎么用？远程仓库管理完整教程

从基础配置到多远程协作，一篇掌握 Git 远程仓库管理。

文章摘要
Git remote 用于管理本地仓库所关联的远程仓库。本文从远程仓库的基本概念开始，系统讲解查看、添加、修改、重命名、删除远程仓库，以及多远程协作、上游同步、远程分支清理和常见报错处理。
本文内容包括：远程仓库概念、origin 与 upstream、查看与添加远程、修改 URL、重命名、删除、多远程协作、远程分支清理和常见报错。
一、什么是远程仓库
远程仓库是存放在其他位置的 Git 仓库，常见位置包括 GitHub、Gitee、GitLab、公司内部服务器，以及局域网中的另一台主机。远程仓库可以用于备份代码、多人协作、代码审查和持续集成。
Git 是分布式版本控制系统，本地仓库本身就保存了完整的提交历史。所谓“远程”，只是本地仓库记录的一组远程地址和跟踪规则。即使暂时断网，本地提交、查看历史和创建分支等操作仍然可以进行。
![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=git_remote_blog_assets%2Fremote_architecture.png&pos_id=img-OJgj7M6P-1786462828032

提示： 重点：origin 只是 git clone 默认创建的远程名称，并不是 Git 强制规定的固定名称。远程仓库名称可以自定义。
二、git remote 命令能做什么
git remote 的主要作用是管理当前本地仓库记录的远程仓库，包括查看远程名称与地址、添加远程、修改 URL、重命名、删除和清理失效的远程跟踪分支。

git remote

不带参数时，命令只显示远程名称。想同时查看拉取地址和推送地址，可以加入 -v。

git remote -v

origin https://github.com/username/demo.git (fetch)
origin https://github.com/username/demo.git (push)

同一个远程通常会显示两行：fetch 表示获取代码时使用的地址，push 表示推送代码时使用的地址。多数项目中两者相同。
三、查看远程仓库的详细信息
只查看远程地址时，git remote -v 已经足够。排查跟踪分支、默认分支或推送状态时，可以查看某个远程的详细信息。

git remote show origin

该命令通常会显示远程 URL、远程默认分支、已经跟踪的远程分支、本地分支与远程分支的对应关系，以及推送时的状态。
只获取某个远程的 URL，可以使用 get-url。

git remote get-url origin

如果一个远程配置了多个 URL，可以查看全部地址。

git remote get-url –all origin

只查看推送地址，可以加入 –push。

git remote get-url –push origin

四、给本地项目添加远程仓库
一个使用 git init 创建的本地仓库，默认没有远程仓库。需要使用 git remote add 将远程名称和仓库地址建立关联。

git remote add origin https://github.com/username/demo.git

添加完成后立即检查配置，避免地址拼写错误。

git remote -v

如果使用 SSH 地址，命令格式如下。

git remote add origin git@github.com:username/demo.git

提示： HTTPS 和 SSH 只是连接方式不同。HTTPS 常使用访问令牌认证；SSH 需要提前配置密钥。仓库内容和 Git 提交历史不因协议不同而改变。
五、首次推送并设置上游分支
仅添加远程仓库并不会自动上传代码。第一次推送当前 main 分支时，可以同时设置上游分支。

git push -u origin main

-u 是 –set-upstream 的简写。设置成功后，本地 main 会跟踪 origin/main，之后通常可以直接使用 git push 和 git pull。

git push

git pull

查看本地分支的上游跟踪关系，可以使用以下命令。

git branch -vv

如果分支已经存在，也可以单独设置上游分支。

git branch –set-upstream-to=origin/main main

六、从远程仓库获取最新信息
git fetch 会从远程仓库下载新的提交、分支和标签信息，并更新远程跟踪分支，但不会直接修改当前工作分支。

git fetch origin

只获取远程 main 分支，可以明确写出分支名称。

git fetch origin main

获取所有已配置远程仓库的信息，可以使用 –all。

git fetch –all

获取完成后，可以查看远程分支。

git branch -r

查看远程 main 中存在、但当前分支尚未包含的提交。

git log HEAD..origin/main –oneline

确认无误后，可以将远程更新合并到当前分支。

git merge origin/main

七、修改远程仓库地址
仓库迁移、项目改名，或者需要在 HTTPS 和 SSH 之间切换时，可以使用 git remote set-url 修改地址。

git remote set-url origin https://github.com/username/new-demo.git

从 HTTPS 切换到 SSH。

git remote set-url origin git@github.com:username/new-demo.git

从 SSH 切换回 HTTPS。

git remote set-url origin https://github.com/username/new-demo.git

修改后再次检查地址。

git remote -v

注意： 修改 URL 只会改变本地仓库中的远程配置，不会自动创建、移动或删除服务器上的仓库。必须先确认目标仓库真实存在并且当前账号有访问权限。
八、重命名远程仓库
远程名称只是本地别名。如果 origin 的含义不够清晰，可以将其重命名为 github、company 或其他名称。

git remote rename origin github

重命名后，原来引用 origin 的命令需要改用新名称。

git fetch github

git push github main

Git 会同时调整相关的远程跟踪引用和配置。完成后使用 git remote -v 检查结果。

git remote -v

九、删除远程仓库关联
项目不再需要某个远程，或者远程配置添加错误时，可以删除该远程。remove 和 rm 的作用相同。

git remote remove origin

git remote rm origin

删除远程只会解除本地仓库与远程地址的关联，并删除对应的远程跟踪配置，不会删除 GitHub、Gitee 或服务器上的真实仓库。

注意： 执行前先使用 git remote -v 确认远程名称。删除后如果仍需要该远程，只能重新使用 git remote add 添加。
十、同时管理多个远程仓库
同一个本地仓库可以配置多个远程。例如将 GitHub 作为主仓库，将 Gitee 作为备份仓库。

git remote add github git@github.com:username/demo.git
git remote add gitee git@gitee.com:username/demo.git

查看所有远程。

git remote -v

将 main 分支分别推送到两个远程。

git push github main
git push gitee main

获取所有远程的最新信息。

git fetch –all

提示： 多个远程可以服务于不同用途。建议使用清晰名称，例如 origin、upstream、company、github、gitee，避免使用 remote1、remote2 这类难以理解的名称。
十一、Fork 项目中的 origin 和 upstream
参与开源项目时，通常先在平台上 Fork 原始仓库，再克隆自己的 Fork。此时 origin 指向自己的仓库，还可以添加 upstream 指向原始项目。
![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=git_remote_blog_assets%2Fmulti_remote.png&pos_id=img-5Wwpp6A8-1786462828032

git remote add upstream https://github.com/original-owner/project.git

获取原始项目的最新提交。

git fetch upstream

切换到本地 main，并将 upstream/main 的更新合并进来。

git switch main
git merge upstream/main

再将同步后的 main 推送到自己的 origin。

git push origin main

这种配置可以明确区分“自己的远程仓库”和“原始上游仓库”。
十二、清理已经失效的远程分支引用
远程分支被删除后，本地的 origin/旧分支 可能仍然存在。可以先试运行，查看哪些远程跟踪分支会被清理。

git remote prune origin –dry-run

确认后正式清理。

git remote prune origin

也可以在获取远程更新时同时清理。

git fetch origin –prune

希望当前用户的所有仓库默认在 fetch 时清理失效引用，可以设置全局配置。

git config –global fetch.prune true

注意： –prune 主要清理远程跟踪引用，不等同于删除本地开发分支。不要把 git remote prune 与直接清理 Git 对象的 git prune 混淆。
十三、查看和更新远程默认分支
origin/HEAD 通常指向远程仓库的默认分支。查看远程详细信息时可以看到默认分支名称。

git remote show origin

远程默认分支发生变化后，可以让 Git 自动查询并更新本地的 origin/HEAD。

git remote set-head origin -a

随后可以查看远程 HEAD 指向。

git symbolic-ref refs/remotes/origin/HEAD

该操作不会重命名本地分支，也不会修改服务器上的默认分支，只是更新本地记录的远程默认分支引用。
十四、完整操作流程示例
![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=git_remote_blog_assets%2Fremote_lifecycle.png&pos_id=img-FcOHYMIg-1786462828032

下面以“把现有本地项目关联到 GitHub，并额外添加 Gitee 备份”为例。

git init
git add .
git commit -m "初始化项目"

git remote add origin git@github.com:username/demo.git
git remote add gitee git@gitee.com:username/demo.git

git remote -v

git push -u origin main
git push -u gitee main

以后正常开发时，可以分别向两个远程推送。

git push origin main
git push gitee main

如果 GitHub 仓库迁移到了新地址，只需要更新 origin。

git remote set-url origin git@github.com:username/new-demo.git
git remote -v

十五、常见报错与解决方法

git remote -v

如果只是地址错误，直接修改 URL。

git remote set-url origin <新的仓库地址>

如果原远程完全不需要，可以删除后重新添加。

git remote remove origin
git remote add origin <仓库地址>

git remote

确认后添加正确的远程。

git remote add origin <仓库地址>

git remote get-url origin

ssh -T git@github.com

git status
git remote -v

git status
git branch –show-current
git log –oneline -1

没有提交时先完成首次提交。

git add .
git commit -m "初始化项目"

git fetch origin
git pull –rebase origin main
git push origin main

十六、使用建议与最佳实践
第一，远程名称要表达用途。个人主仓库使用 origin，上游仓库使用 upstream，企业仓库可使用 company，镜像仓库可使用 gitee 或 mirror。
第二，修改或删除远程前先执行 git remote -v，操作后再次验证，避免改错仓库。
第三，不要将远程仓库地址中的访问令牌直接写进公开文档、截图或脚本。凭据泄露后应立即撤销并重新生成。
第四，多个平台之间做镜像时，优先配置两个独立远程。这样 fetch 和 push 的来源清晰，排查问题也更容易。
第五，定期使用 git fetch –prune 清理远程已经删除的分支引用，让远程分支列表保持准确。
第六，执行强制推送前先确认目标远程和目标分支。团队项目中优先使用受保护分支和 Pull Request 流程。
十七、常用命令速查
查看远程名称。

git remote

查看远程名称和 URL。

git remote -v

查看远程详细信息。

git remote show origin

添加远程。

git remote add origin <仓库地址>

修改远程地址。

git remote set-url origin <新仓库地址>

重命名远程。

git remote rename origin github

删除远程。

git remote remove origin

获取某个远程的最新信息。

git fetch origin

获取全部远程。

git fetch –all

清理失效的远程分支引用。

git fetch origin –prune

首次推送并设置上游。

git push -u origin main

总结
git remote 并不负责直接提交代码，它管理的是“本地仓库如何找到远程仓库”。掌握查看、添加、修改、重命名和删除远程之后，就能够处理大部分远程仓库配置问题。
日常开发最常使用的命令是 git remote -v、git remote add、git remote set-url、git fetch 和 git push -u。多人协作或开源项目中，再掌握 origin 与 upstream 的双远程方式以及 –prune 清理，就能建立清晰、稳定的远程协作流程。
参考资料
Git 官方文档：git-remote – https://git-scm.com/docs/git-remote
Git 官方文档：git-push – https://git-scm.com/docs/git-push
Git 官方文档：git-fetch – https://git-scm.com/docs/git-fetch
Pro Git：Working with Remotes – https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes
GitHub Docs：Managing remote repositories – https://docs.github.com/en/get-started/git-basics/managing-remote-repositories!](https://i-blog.csdnimg.cn/direct/c8eee89fb2c34c94a5cf9b0f2bb746c1.png)