git-push - 与相关对象一起更新远程分支引用

Updates one or more branches, tags, or other references in one or more remote repositories from your local repository, and sends all necessary data that isn’t already on the remote.

最简单的推送方式是 git push <remote> <branch>。例如，git push origin main 会将本地 main 分支推送到名为 origin 的远程上的 main 分支。

You can also push to multiple remotes at once by using a remote group. A remote group is a named list of remotes configured via remotes.<name> in your git config:

Then git push all-remotes will push to origin, gitlab, and backup in turn, as if you had run git push against each one individually. Each remote is pushed independently using its own push mapping configuration. There is a remotes.<group> entry in the configuration file. (See git-config[1]).

<repository> 参数默认取当前分支的上游仓库；如果没有配置上游，则默认为 origin。

Git 会按以下优先顺序决定要推送哪些分支、标签或其他引用：

如果你尚未为当前分支设置上游分支，git push 可能会失败，具体取决于 push.default 的设置。关于如何设置和使用上游分支，请参见下文 UPSTREAM BRANCHES 一节。

通过设置 “钩子”，你可以在每次推送到一个仓库时，让它发生有趣的事情。 见 git-receive-pack[1] 的文档。

并非所有更新都是允许的：详情请参见下文的 PUSH RULES。

通常，地址包含有关传输协议，远程服务器的地址以及仓库路径的信息。对于某些传输协议，一些信息可能会缺失。

Git 支持 ssh，git，http 和 https 协议（此外，可以使用 ftp 和 ftps 进行获取，但这效率低下且不建议使用；请勿使用）。

本地传输（即 git:// 地址）不进行身份验证，在不安全的网络上应谨慎使用。

以下是上述几个传输协议的格式：

ssh 协议也可以使用类似 scp 的语法：

仅当第一个冒号之前没有斜杠时才能识别此语法。这有助于区分包含冒号的本地路径。例如，可以将本地路径 foo:bar 指定为绝对路径，或者将 ./foo:bar 指定为绝对路径，以避免被误识别为 ssh url。

ssh 和 git 协议还支持 ~<用户名> 扩展：

对于本地仓库（Git 本身也支持），可以使用以下语法：

这两种语法几乎是等效的，除了在克隆时，前者隐含使用了 --local 选项。有关详细信息，请参阅 git-clone[1]。

git clone、git fetch 和 git pull（但不包括 git push）也会接受合适的捆绑包文件。参见 git-bundle[1]。

当 Git 不知道如何处理某种传输协议时，它会尝试使用 remote-<传输方式> 远程帮助程序（如果存在）。要显式请求远程帮助程序，可以使用以下语法：

其中，<地址> 可以是路径，服务器与路径，也可以是可被调用的特定远程帮助程序识别的类似于网页地址的任意字符串。有关详细信息，请参阅 gitremote-helpers[7]。

如果存在大量类似名称的远程仓库，并且您要为其使用不同的格式（这样，您使用的地址将被重写为有效的地址），则可以创建以下形式的配置：

例如，有如下：

诸如 "work:repo.git" 或 "host.xz:/path/to/repo.git" 的地址会在任何类似于 "git://git.host.xz/repo" 地址的上下文中重写。

如果要重写仅用于推送的地址，可以创建表单的配置部分：

例如，有如下：

类似于 "git://example.org/path/to/repo.git" 的地址会被重写为 "ssh://example.org/path/to/repo.git"，用于推送。但拉取代码时仍然使用原始的地址。

可以用下面的一个名称代替URL作为 <repository> 的参数：

所有这些也允许你从命令行中省略refspec，因为它们都包含一个git默认使用的refspec。

Git 中的分支可以选择关联一个上游远程分支。对于远程操作，Git 默认会使用该上游分支，例如：

上游信息存储在 .git/config 的 "remote" 和 "merge" 字段中。例如，如果 main 的上游是 origin/main：

你可以用 git push --set-upstream <remote> <branch> 显式设置上游分支，但 Git 往往也会自动为你设置上游，例如：

A remote group is a named list of remotes configured via remotes.<name> in your git config:

When a group name is given as the <repository> argument, the push is performed to each member remote in turn. The defining principle is:

is exactly equivalent to:

where r1, r2, …​, rN are the members of all-remotes. No special behaviour is added or removed — the group is purely a shorthand for running the same push command against each member remote individually.

When pushing to a group of more than one remote, Git spawns a separate git push subprocess for each member remote in sequence. Each subprocess receives the same flags and refspecs as the original invocation. This means that per-remote push mappings configured via remote.<name>.push and mirror mode (remote.<name>.mirror) are evaluated independently for each remote, and a mirror remote in the group cannot affect the push behaviour of other non-mirror remotes in the same group.

The --atomic option is not supported for group pushes, because atomicity can only be guaranteed within a single transport connection to a single remote. Git will refuse the invocation with an error if --atomic is combined with a group name.

If any member remote fails whether due to a push rejection (e.g. a non-fast-forward update, a server-side hook refusing a ref) or a connection error (e.g. the repository does not exist, authentication fails, or the network is unreachable), Git reports the error and continues pushing to the remaining remotes in the group. The overall exit code is non-zero if any member push fails.

This means the user is responsible for ensuring that the sequence of individual pushes makes sense. If git push r1 would fail for a given set of options and arguments, then git push all-remotes will fail in the same way when it reaches r1. The group push does not do anything special to make a failing individual push succeed.

"git push" 的输出取决于所使用的传输方式；本节将介绍通过 Git 协议（本地或通过 ssh）推送时的输出。

推送的状态以表格的形式输出，每一行代表一个引用的状态。每一行的形式是：

如果使用了 --porcelain ，那么输出的每一行都是这样的：

只有在使用 --porcelain 或 --verbose 选项时，才会显示最新引用的状态。

作为一项安全功能，git push 命令只允许某些类型的更新，以防你不小心丢失远程数据。

由于分支和标签的用途不同，推送到分支的安全规则与推送到标签的规则不同。以下规则中，“更新”指除删除和创建之外的任何修改。删除和创建始终允许，除非被配置或钩子禁止。

你可以通过传入 --force，或者在 refspec 前加上可选的前导 + 来覆盖这些规则。唯一的例外是：无论怎样强制，分支都不会接受非提交对象；而且如果远程仓库被配置为拒绝某次推送，强制也无法让它接受。

钩子和配置也可以覆盖或补充这些规则，例如 git-config[1] 中的 receive.denyNonFastForwards 和 receive.denyDeletes，以及 githooks[5] 中的 pre-receive 和 update。

当一个更新将原来指向提交 A 的分支（或更普遍的，一个引用）改为指向另一个提交 B 时，当且仅当 B 是 A 的后代时，它被称为快速合并。

在从 A 到 B 的快速合并中，原始提交 A 所建立的提交集是新提交 B 所建立的提交集的一个子集。 因此，它不会丢失任何历史。

相反，非快速合并更新会丢失历史。 例如，假设你和别人从同一个提交 X 开始，你建立了一个通往提交 B 的历史，而另一个人建立了一个通往提交 A 的历史。 这段历史看起来像这样：

进一步假设对方已经将 A 导致的修改推送回原仓库，你们俩从原仓库中获得原始提交 X。

另一个人所做的推送，将原来指向提交 X 的分支更新为指向提交 A 的分支。

但如果你试图推送，你会试图用提交 B 来更新分支（现在指向 A）。这不是快速合并。 如果你这样做了，提交 A 引入的修改就会丢失，因为大家现在都会在 B 的基础上开始构建。

该命令默认不允许非快速合并的更新，以防止这种历史的损失。

如果你不想丢失你的工作（从 X 到 B 的历史）或对方的工作（从 X 到 A 的历史），你需要先从仓库中获取历史，创建一个包含双方修改的历史，并将结果推送回去。

您可以执行 "git pull"，解决潜在的冲突，然后将结果 "git push"。 一个 "git pull "会在提交 A 和 B 之间创建一个合并提交 C。

用所产生的合并提交更新 A，将快速合并，你的推送将被接受。

另外，你也可以用 git pull --rebase 将 X 和 B 之间的改动重新归档到 A 之上，然后将结果推送回来。 重置将创建一个新的提交 D，将 X 和 B 之间的修改建立在 A 的基础上。

同样的，用这个提交更新 A 会快速合并，你的推送会被接受。

还有一种常见的情况是，当你试图推送时，可能会遇到非快速合并拒绝，即使你推送到一个没有人推送的仓库中也有可能。在你自己推送了提交 A（在本节的第一幅图中），用 git commit --amend 替换后产生了提交 B，你试图推送它，因为忘记了你已经推送了 A。在这种情况下，只有当您确定在此期间没有人取走您先前的提交 A（并在其基础上开始构建），您才能运行 git push --force 来覆盖它。换句话说，git push --force 是一种保留给你确实想失去历史的情况的方法。

获取和推送协议并不是为了防止一方从另一个仓库窃取不打算共享的数据。如果你有需要保护的私人数据不被恶意的同行窃取，你最好的选择是把它存储在另一个资源库中。这同时适用于客户端和服务器。特别是，服务器上的命名空间对于读取访问控制是无效的；你应该只将命名空间的读取访问权授予那些你信任的可以读取整个仓库的客户。

已知的攻击媒介如下：

本节中这一行以下的内容都是从 git-config[1] 文档中摘录的。其内容与那里的内容相同：

属于 git[1] 文档