You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
421 lines
14 KiB
421 lines
14 KiB
git-push(1) |
|
=========== |
|
|
|
NAME |
|
---- |
|
git-push - Update remote refs along with associated objects |
|
|
|
|
|
SYNOPSIS |
|
-------- |
|
[verse] |
|
'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] |
|
[--repo=<repository>] [-f | --force] [-v | --verbose] [-u | --set-upstream] |
|
[<repository> [<refspec>...]] |
|
|
|
DESCRIPTION |
|
----------- |
|
|
|
Updates remote refs using local refs, while sending objects |
|
necessary to complete the given refs. |
|
|
|
You can make interesting things happen to a repository |
|
every time you push into it, by setting up 'hooks' there. See |
|
documentation for linkgit:git-receive-pack[1]. |
|
|
|
|
|
OPTIONS[[OPTIONS]] |
|
------------------ |
|
<repository>:: |
|
The "remote" repository that is destination of a push |
|
operation. This parameter can be either a URL |
|
(see the section <<URLS,GIT URLS>> below) or the name |
|
of a remote (see the section <<REMOTES,REMOTES>> below). |
|
|
|
<refspec>...:: |
|
The format of a <refspec> parameter is an optional plus |
|
`{plus}`, followed by the source ref <src>, followed |
|
by a colon `:`, followed by the destination ref <dst>. |
|
It is used to specify with what <src> object the <dst> ref |
|
in the remote repository is to be updated. |
|
+ |
|
The <src> is often the name of the branch you would want to push, but |
|
it can be any arbitrary "SHA-1 expression", such as `master~4` or |
|
`HEAD` (see linkgit:gitrevisions[7]). |
|
+ |
|
The <dst> tells which ref on the remote side is updated with this |
|
push. Arbitrary expressions cannot be used here, an actual ref must |
|
be named. If `:`<dst> is omitted, the same ref as <src> will be |
|
updated. |
|
+ |
|
The object referenced by <src> is used to update the <dst> reference |
|
on the remote side, but by default this is only allowed if the |
|
update can fast-forward <dst>. By having the optional leading `{plus}`, |
|
you can tell git to update the <dst> ref even when the update is not a |
|
fast-forward. This does *not* attempt to merge <src> into <dst>. See |
|
EXAMPLES below for details. |
|
+ |
|
`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. |
|
+ |
|
Pushing an empty <src> allows you to delete the <dst> ref from |
|
the remote repository. |
|
+ |
|
The special refspec `:` (or `{plus}:` to allow non-fast-forward updates) |
|
directs git to push "matching" branches: for every branch that exists on |
|
the local side, the remote side is updated if a branch of the same name |
|
already exists on the remote side. This is the default operation mode |
|
if no explicit refspec is found (that is neither on the command line |
|
nor in any Push line of the corresponding remotes file---see below). |
|
|
|
--all:: |
|
Instead of naming each ref to push, specifies that all |
|
refs under `refs/heads/` be pushed. |
|
|
|
--mirror:: |
|
Instead of naming each ref to push, specifies that all |
|
refs under `refs/` (which includes but is not |
|
limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`) |
|
be mirrored to the remote repository. Newly created local |
|
refs will be pushed to the remote end, locally updated refs |
|
will be force updated on the remote end, and deleted refs |
|
will be removed from the remote end. This is the default |
|
if the configuration option `remote.<remote>.mirror` is |
|
set. |
|
|
|
-n:: |
|
--dry-run:: |
|
Do everything except actually send the updates. |
|
|
|
--porcelain:: |
|
Produce machine-readable output. The output status line for each ref |
|
will be tab-separated and sent to stdout instead of stderr. The full |
|
symbolic names of the refs will be given. |
|
|
|
--delete:: |
|
All listed refs are deleted from the remote repository. This is |
|
the same as prefixing all refs with a colon. |
|
|
|
--tags:: |
|
All refs under `refs/tags` are pushed, in |
|
addition to refspecs explicitly listed on the command |
|
line. |
|
|
|
--receive-pack=<git-receive-pack>:: |
|
--exec=<git-receive-pack>:: |
|
Path to the 'git-receive-pack' program on the remote |
|
end. Sometimes useful when pushing to a remote |
|
repository over ssh, and you do not have the program in |
|
a directory on the default $PATH. |
|
|
|
-f:: |
|
--force:: |
|
Usually, the command refuses to update a remote ref that is |
|
not an ancestor of the local ref used to overwrite it. |
|
This flag disables the check. This can cause the |
|
remote repository to lose commits; use it with care. |
|
|
|
--repo=<repository>:: |
|
This option is only relevant if no <repository> argument is |
|
passed in the invocation. In this case, 'git push' derives the |
|
remote name from the current branch: If it tracks a remote |
|
branch, then that remote repository is pushed to. Otherwise, |
|
the name "origin" is used. For this latter case, this option |
|
can be used to override the name "origin". In other words, |
|
the difference between these two commands |
|
+ |
|
-------------------------- |
|
git push public #1 |
|
git push --repo=public #2 |
|
-------------------------- |
|
+ |
|
is that #1 always pushes to "public" whereas #2 pushes to "public" |
|
only if the current branch does not track a remote branch. This is |
|
useful if you write an alias or script around 'git push'. |
|
|
|
-u:: |
|
--set-upstream:: |
|
For every branch that is up to date or successfully pushed, add |
|
upstream (tracking) reference, used by argument-less |
|
linkgit:git-pull[1] and other commands. For more information, |
|
see 'branch.<name>.merge' in linkgit:git-config[1]. |
|
|
|
--thin:: |
|
--no-thin:: |
|
These options are passed to linkgit:git-send-pack[1]. A thin transfer |
|
significantly reduces the amount of sent data when the sender and |
|
receiver share many of the same objects in common. The default is |
|
\--thin. |
|
|
|
-q:: |
|
--quiet:: |
|
Suppress all output, including the listing of updated refs, |
|
unless an error occurs. Progress is not reported to the standard |
|
error stream. |
|
|
|
-v:: |
|
--verbose:: |
|
Run verbosely. |
|
|
|
--progress:: |
|
Progress status is reported on the standard error stream |
|
by default when it is attached to a terminal, unless -q |
|
is specified. This flag forces progress status even if the |
|
standard error stream is not directed to a terminal. |
|
|
|
include::urls-remotes.txt[] |
|
|
|
OUTPUT |
|
------ |
|
|
|
The output of "git push" depends on the transport method used; this |
|
section describes the output when pushing over the git protocol (either |
|
locally or via ssh). |
|
|
|
The status of the push is output in tabular form, with each line |
|
representing the status of a single ref. Each line is of the form: |
|
|
|
------------------------------- |
|
<flag> <summary> <from> -> <to> (<reason>) |
|
------------------------------- |
|
|
|
If --porcelain is used, then each line of the output is of the form: |
|
|
|
------------------------------- |
|
<flag> \t <from>:<to> \t <summary> (<reason>) |
|
------------------------------- |
|
|
|
The status of up-to-date refs is shown only if --porcelain or --verbose |
|
option is used. |
|
|
|
flag:: |
|
A single character indicating the status of the ref: |
|
(space);; for a successfully pushed fast-forward; |
|
`{plus}`;; for a successful forced update; |
|
`-`;; for a successfully deleted ref; |
|
`*`;; for a successfully pushed new ref; |
|
`!`;; for a ref that was rejected or failed to push; and |
|
`=`;; for a ref that was up to date and did not need pushing. |
|
|
|
summary:: |
|
For a successfully pushed ref, the summary shows the old and new |
|
values of the ref in a form suitable for using as an argument to |
|
`git log` (this is `<old>..<new>` in most cases, and |
|
`<old>\...<new>` for forced non-fast-forward updates). |
|
+ |
|
For a failed update, more details are given: |
|
+ |
|
-- |
|
rejected:: |
|
Git did not try to send the ref at all, typically because it |
|
is not a fast-forward and you did not force the update. |
|
|
|
remote rejected:: |
|
The remote end refused the update. Usually caused by a hook |
|
on the remote side, or because the remote repository has one |
|
of the following safety options in effect: |
|
`receive.denyCurrentBranch` (for pushes to the checked out |
|
branch), `receive.denyNonFastForwards` (for forced |
|
non-fast-forward updates), `receive.denyDeletes` or |
|
`receive.denyDeleteCurrent`. See linkgit:git-config[1]. |
|
|
|
remote failure:: |
|
The remote end did not report the successful update of the ref, |
|
perhaps because of a temporary error on the remote side, a |
|
break in the network connection, or other transient error. |
|
-- |
|
|
|
from:: |
|
The name of the local ref being pushed, minus its |
|
`refs/<type>/` prefix. In the case of deletion, the |
|
name of the local ref is omitted. |
|
|
|
to:: |
|
The name of the remote ref being updated, minus its |
|
`refs/<type>/` prefix. |
|
|
|
reason:: |
|
A human-readable explanation. In the case of successfully pushed |
|
refs, no explanation is needed. For a failed ref, the reason for |
|
failure is described. |
|
|
|
Note about fast-forwards |
|
------------------------ |
|
|
|
When an update changes a branch (or more in general, a ref) that used to |
|
point at commit A to point at another commit B, it is called a |
|
fast-forward update if and only if B is a descendant of A. |
|
|
|
In a fast-forward update from A to B, the set of commits that the original |
|
commit A built on top of is a subset of the commits the new commit B |
|
builds on top of. Hence, it does not lose any history. |
|
|
|
In contrast, a non-fast-forward update will lose history. For example, |
|
suppose you and somebody else started at the same commit X, and you built |
|
a history leading to commit B while the other person built a history |
|
leading to commit A. The history looks like this: |
|
|
|
---------------- |
|
|
|
B |
|
/ |
|
---X---A |
|
|
|
---------------- |
|
|
|
Further suppose that the other person already pushed changes leading to A |
|
back to the original repository you two obtained the original commit X. |
|
|
|
The push done by the other person updated the branch that used to point at |
|
commit X to point at commit A. It is a fast-forward. |
|
|
|
But if you try to push, you will attempt to update the branch (that |
|
now points at A) with commit B. This does _not_ fast-forward. If you did |
|
so, the changes introduced by commit A will be lost, because everybody |
|
will now start building on top of B. |
|
|
|
The command by default does not allow an update that is not a fast-forward |
|
to prevent such loss of history. |
|
|
|
If you do not want to lose your work (history from X to B) nor the work by |
|
the other person (history from X to A), you would need to first fetch the |
|
history from the repository, create a history that contains changes done |
|
by both parties, and push the result back. |
|
|
|
You can perform "git pull", resolve potential conflicts, and "git push" |
|
the result. A "git pull" will create a merge commit C between commits A |
|
and B. |
|
|
|
---------------- |
|
|
|
B---C |
|
/ / |
|
---X---A |
|
|
|
---------------- |
|
|
|
Updating A with the resulting merge commit will fast-forward and your |
|
push will be accepted. |
|
|
|
Alternatively, you can rebase your change between X and B on top of A, |
|
with "git pull --rebase", and push the result back. The rebase will |
|
create a new commit D that builds the change between X and B on top of |
|
A. |
|
|
|
---------------- |
|
|
|
B D |
|
/ / |
|
---X---A |
|
|
|
---------------- |
|
|
|
Again, updating A with this commit will fast-forward and your push will be |
|
accepted. |
|
|
|
There is another common situation where you may encounter non-fast-forward |
|
rejection when you try to push, and it is possible even when you are |
|
pushing into a repository nobody else pushes into. After you push commit |
|
A yourself (in the first picture in this section), replace it with "git |
|
commit --amend" to produce commit B, and you try to push it out, because |
|
forgot that you have pushed A out already. In such a case, and only if |
|
you are certain that nobody in the meantime fetched your earlier commit A |
|
(and started building on top of it), you can run "git push --force" to |
|
overwrite it. In other words, "git push --force" is a method reserved for |
|
a case where you do mean to lose history. |
|
|
|
|
|
Examples |
|
-------- |
|
|
|
git push:: |
|
Works like `git push <remote>`, where <remote> is the |
|
current branch's remote (or `origin`, if no remote is |
|
configured for the current branch). |
|
|
|
git push origin:: |
|
Without additional configuration, works like |
|
`git push origin :`. |
|
+ |
|
The default behavior of this command when no <refspec> is given can be |
|
configured by setting the `push` option of the remote. |
|
+ |
|
For example, to default to pushing only the current branch to `origin` |
|
use `git config remote.origin.push HEAD`. Any valid <refspec> (like |
|
the ones in the examples below) can be configured as the default for |
|
`git push origin`. |
|
|
|
git push origin ::: |
|
Push "matching" branches to `origin`. See |
|
<refspec> in the <<OPTIONS,OPTIONS>> section above for a |
|
description of "matching" branches. |
|
|
|
git push origin master:: |
|
Find a ref that matches `master` in the source repository |
|
(most likely, it would find `refs/heads/master`), and update |
|
the same ref (e.g. `refs/heads/master`) in `origin` repository |
|
with it. If `master` did not exist remotely, it would be |
|
created. |
|
|
|
git push origin HEAD:: |
|
A handy way to push the current branch to the same name on the |
|
remote. |
|
|
|
git push origin master:satellite/master dev:satellite/dev:: |
|
Use the source ref that matches `master` (e.g. `refs/heads/master`) |
|
to update the ref that matches `satellite/master` (most probably |
|
`refs/remotes/satellite/master`) in the `origin` repository, then |
|
do the same for `dev` and `satellite/dev`. |
|
|
|
git push origin HEAD:master:: |
|
Push the current branch to the remote ref matching `master` in the |
|
`origin` repository. This form is convenient to push the current |
|
branch without thinking about its local name. |
|
|
|
git push origin master:refs/heads/experimental:: |
|
Create the branch `experimental` in the `origin` repository |
|
by copying the current `master` branch. This form is only |
|
needed to create a new branch or tag in the remote repository when |
|
the local name and the remote name are different; otherwise, |
|
the ref name on its own will work. |
|
|
|
git push origin :experimental:: |
|
Find a ref that matches `experimental` in the `origin` repository |
|
(e.g. `refs/heads/experimental`), and delete it. |
|
|
|
git push origin {plus}dev:master:: |
|
Update the origin repository's master branch with the dev branch, |
|
allowing non-fast-forward updates. *This can leave unreferenced |
|
commits dangling in the origin repository.* Consider the |
|
following situation, where a fast-forward is not possible: |
|
+ |
|
---- |
|
o---o---o---A---B origin/master |
|
\ |
|
X---Y---Z dev |
|
---- |
|
+ |
|
The above command would change the origin repository to |
|
+ |
|
---- |
|
A---B (unnamed branch) |
|
/ |
|
o---o---o---X---Y---Z master |
|
---- |
|
+ |
|
Commits A and B would no longer belong to a branch with a symbolic name, |
|
and so would be unreachable. As such, these commits would be removed by |
|
a `git gc` command on the origin repository. |
|
|
|
|
|
Author |
|
------ |
|
Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C |
|
by Linus Torvalds <torvalds@osdl.org> |
|
|
|
Documentation |
|
-------------- |
|
Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. |
|
|
|
GIT |
|
--- |
|
Part of the linkgit:git[1] suite
|
|
|