简体中文 ▾ 主题 ▾ 最新版本 ▾ git-remote 最后更新于 2.53.0

名称

git-remote - 管理已跟踪的仓库集

概要

git remote [-v | --verbose]
git remote add [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL>
git remote rename [--[no-]progress] <old> <new>
git remote remove <name>
git remote set-head <name> (-a | --auto | -d | --delete | <branch>)
git remote set-branches [--add] <name> <branch>…​
git remote get-url [--push] [--all] <name>
git remote set-url [--push] <name> <newurl> [<oldurl>]
git remote set-url --add [--push] <name> <newurl>
git remote set-url --delete [--push] <name> <URL>
git remote [-v | --verbose] show [-n] <name>…​
git remote prune [-n | --dry-run] <name>…​
git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)…​]

描述

管理你所跟踪的分支所属的仓库集（“远程仓库”）。

选项

-v
--verbose

显示更详细的信息，在名称后显示远程仓库的 URL。对于承诺者远程仓库（promisor remotes），还会显示配置了哪些过滤器（blob:none 等）。注意：此选项必须置于 remote 和子命令之间。

命令

不带参数时，显示现有远程仓库的列表。有几个子命令可用于对远程仓库执行操作。

add

为位于 <URL> 的仓库添加一个名为 <name> 的远程仓库。随后可以使用命令 git fetch <name> 来创建和更新远程跟踪分支 <name>/<branch>。

使用 -f 选项，在设置完远程仓库信息后立即运行 git fetch <name>。

使用 --tags 选项，git fetch <name> 会从远程仓库导入每个标签。

使用 --no-tags 选项，git fetch <name> 不会从远程仓库导入标签。

默认情况下，仅导入已拉取分支上的标签（参见 git-fetch[1]）。

使用 -t <branch> 选项，不再使用默认的通配符引用规格（refspec）来跟踪 refs/remotes/<name>/ 命名空间下的所有分支，而是创建一个仅跟踪 <branch> 的引用规格。你可以指定多个 -t <branch> 以在不获取所有分支的情况下跟踪多个分支。

使用 -m <master> 选项，会设置一个符号引用 refs/remotes/<name>/HEAD 指向远程仓库的 <master> 分支。另请参阅 set-head 命令。

当使用 --mirror=fetch 创建拉取镜像时，引用将不会存储在 refs/remotes/ 命名空间中，而是将远程仓库 refs/ 中的所有内容直接镜像到本地仓库的 refs/ 中。此选项仅在裸仓库中有意义，因为拉取操作会覆盖任何本地提交。

当使用 --mirror=push 创建推送镜像时，git push 的行为将始终表现为传递了 --mirror 参数。

rename

将名为 <old> 的远程仓库重命名为 <new>。该远程仓库的所有远程跟踪分支和配置设置都会更新。

如果 <old> 和 <new> 相同，且 <old> 是 $GIT_DIR/remotes 或 $GIT_DIR/branches 下的一个文件，则该远程仓库会被转换为配置文件格式。

remove
rm

移除名为 <name> 的远程仓库。该远程仓库的所有远程跟踪分支和配置设置都会被移除。

set-head

为指定的远程仓库设置或删除默认分支（即符号引用 refs/remotes/<name>/HEAD 的目标）。远程仓库不强制要求有默认分支，但设置后可以指定远程仓库名称来代替特定分支。例如，如果 origin 的默认分支设置为 master，那么在通常指定 origin/master 的地方都可以指定 origin。

使用 -d 或 --delete，符号引用 refs/remotes/<name>/HEAD 将被删除。

使用 -a 或 --auto，会查询远程仓库以确定其 HEAD，然后将符号引用 refs/remotes/<name>/HEAD 设置为相同的分支。例如，如果远程 HEAD 指向 next，git remote set-head origin -a 将把符号引用 refs/remotes/origin/HEAD 设置为 refs/remotes/origin/next。这只有在 refs/remotes/origin/next 已经存在时才有效；否则必须先获取（fetch）它。

使用 <branch> 显式设置符号引用 refs/remotes/<name>/HEAD。例如，git remote set-head origin master 将把符号引用 refs/remotes/origin/HEAD 设置为 refs/remotes/origin/master。这只有在 refs/remotes/origin/master 已经存在时才有效；否则必须先获取（fetch）它。

set-branches

更改指定远程仓库跟踪的分支列表。这可以用于在远程仓库初始设置后，跟踪可用远程分支的一个子集。

指定的各个分支将像在 git remote add 命令行中使用 -t 选项一样被解析。

使用 --add，将在当前跟踪的分支列表中添加新分支，而不是替换列表。

get-url

获取远程仓库的 URL。insteadOf 和 pushInsteadOf 的配置在此处会被展开。默认情况下，只列出第一个 URL。

使用 --push，将查询推送（push）URL 而非拉取（fetch）URL。

使用 --all，将列出该远程仓库的所有 URL。

set-url

更改远程仓库的 URL。将远程仓库 <name> 中第一个匹配正则表达式 <oldurl> 的 URL（如果未给出 <oldurl> 则为第一个 URL）设置为 <newurl>。如果 <oldurl> 不匹配任何 URL，则会报错且不作更改。

使用 --push，将操作推送 URL 而非拉取 URL。

使用 --add，将添加新 URL 而非更改现有 URL。

使用 --delete，将为远程仓库 <name> 删除所有匹配正则表达式 <URL> 的 URL，而不是更改现有 URL。尝试删除所有非推送 URL 是错误的。

请注意，推送 URL 和拉取 URL 即使可以设置得不同，也必须指向同一个地方。你推送到推送 URL 的内容应该是你立即从拉取 URL 获取时所能看到的内容。如果你尝试从一个地方（例如你的上游）拉取并推送到另一个地方（例如你的发布仓库），请使用两个独立的远程仓库。

show

提供有关远程仓库 <name> 的一些信息。

使用 -n 选项，不会先通过 git ls-remote <name> 查询远程 head；而是使用缓存的信息。

prune

删除与 <name> 关联的陈旧引用。默认情况下，会删除 <name> 下陈旧的远程跟踪分支，但根据全局配置和远程仓库的配置，我们甚至可能会修剪尚未推送到那里的本地标签。相当于 git fetch --prune <name>，区别在于不会获取任何新引用。

有关根据不同配置将修剪哪些内容，请参阅 git-fetch[1] 的 PRUNING 章节。

使用 --dry-run 选项，报告哪些分支将被修剪，但并不实际修剪它们。

update

获取仓库中由 remotes.<group> 定义的远程仓库或远程组的更新。如果在命令行上既未指定组也未指定远程仓库，则将使用配置参数 remotes.default；如果未定义 remotes.default，则将更新所有未将配置参数 remote.<name>.skipDefaultUpdate 设置为 true 的远程仓库。（参见 git-config[1]）。

使用 --prune 选项，对所有更新的远程仓库运行修剪。

讨论

远程仓库配置是通过使用 remote.origin.url 和 remote.origin.fetch 配置变量实现的。（参见 git-config[1]）。

退出状态

成功后，退出状态码为 0。

当 add、rename 和 remove 等子命令找不到相关远程仓库时，退出状态码为 2。当远程仓库已存在时，退出状态码为 3。

发生任何其他错误时，退出状态码可能是任何其他非零值。

示例

  • 添加一个新远程仓库、拉取并从中检出一个分支

    $ git remote
origin
$ git branch -r
  origin/HEAD -> origin/master
  origin/master
$ git remote add staging git://git.kernel.org/.../gregkh/staging.git
$ git remote
origin
staging
$ git fetch staging
...
From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging
 * [new branch]      master     -> staging/master
 * [new branch]      staging-linus -> staging/staging-linus
 * [new branch]      staging-next -> staging/staging-next
$ git branch -r
  origin/HEAD -> origin/master
  origin/master
  staging/master
  staging/staging-linus
  staging/staging-next
$ git switch -c staging staging/master
...

  • 模仿 git clone 但仅跟踪选定的分支

    $ mkdir project.git
$ cd project.git
$ git init
$ git remote add -f -t master -m master origin git://example.com/git.git/
$ git merge origin

另请参阅

git-fetch[1] git-branch[1] git-config[1]

GIT

Git[1] 套件的一部分