Documentation: more git push examples
[git/git.git] / Documentation / git-push.txt
CommitLineData
215a7ad1
JH
1git-push(1)
2===========
7fc9d69f
JH
3
4NAME
5----
7bd7f280 6git-push - Update remote refs along with associated objects
7fc9d69f
JH
7
8
9SYNOPSIS
10--------
97925fde 11[verse]
bf07cc58
JS
12'git push' [--all | --mirror] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>]
13 [--repo=<repository>] [-f | --force] [-v | --verbose]
2c9693bd 14 [<repository> <refspec>...]
7fc9d69f
JH
15
16DESCRIPTION
17-----------
ab9b3138
JH
18
19Updates remote refs using local refs, while sending objects
20necessary to complete the given refs.
7fc9d69f 21
cc55aaec 22You can make interesting things happen to a repository
eb0362a4 23every time you push into it, by setting up 'hooks' there. See
5162e697 24documentation for linkgit:git-receive-pack[1].
eb0362a4 25
7fc9d69f
JH
26
27OPTIONS
28-------
3598a308 29<repository>::
85a97d4e 30 The "remote" repository that is destination of a push
98347fee
AM
31 operation. This parameter can be either a URL
32 (see the section <<URLS,GIT URLS>> below) or the name
33 of a remote (see the section <<REMOTES,REMOTES>> below).
3598a308 34
2c9693bd 35<refspec>...::
7a0d911f
JH
36 The format of a <refspec> parameter is an optional plus
37 `{plus}`, followed by the source ref <src>, followed
38 by a colon `:`, followed by the destination ref <dst>.
39 It is used to specify with what <src> object the <dst> ref
40 in the remote repository is to be updated.
3598a308 41+
491b1b11
SV
42The <src> side represents the source branch (or arbitrary
43"SHA1 expression", such as `master~4` (four parents before the
44tip of `master` branch); see linkgit:git-rev-parse[1]) that you
45want to push. The <dst> side represents the destination location.
3598a308
BF
46+
47The local ref that matches <src> is used
391d186b 48to fast forward the remote ref that matches <dst>. If
491b1b11 49the optional leading plus `+` is used, the remote ref is updated
3598a308
BF
50even if it does not result in a fast forward update.
51+
25fb6290 52`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
3598a308 53+
69274b6e
AM
54A lonely <src> parameter (without a colon and a destination) pushes
55the <src> to the same name in the destination repository.
25fb6290
JH
56+
57Pushing an empty <src> allows you to delete the <dst> ref from
58the remote repository.
a83619d6
PB
59+
60The special refspec `:` (or `+:` to allow non-fast forward updates)
89edd5a9
AM
61directs git to push "matching" branches: for every branch that exists on
62the local side, the remote side is updated if a branch of the same name
a83619d6
PB
63already exists on the remote side. This is the default operation mode
64if no explicit refspec is found (that is neither on the command line
65nor in any Push line of the corresponding remotes file---see below).
7fc9d69f 66
3240240f 67--all::
cc55aaec 68 Instead of naming each ref to push, specifies that all
5c633a4c 69 refs under `$GIT_DIR/refs/heads/` be pushed.
d6a73596 70
3240240f 71--mirror::
ff206748 72 Instead of naming each ref to push, specifies that all
73f03627
SP
73 refs under `$GIT_DIR/refs/` (which includes but is not
74 limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
ff206748
AW
75 be mirrored to the remote repository. Newly created local
76 refs will be pushed to the remote end, locally updated refs
77 will be force updated on the remote end, and deleted refs
84bb2dfd
PB
78 will be removed from the remote end. This is the default
79 if the configuration option `remote.<remote>.mirror` is
80 set.
ff206748 81
3240240f 82--dry-run::
11f2441f
BE
83 Do everything except actually send the updates.
84
3240240f 85--tags::
42301e34
JH
86 All refs under `$GIT_DIR/refs/tags` are pushed, in
87 addition to refspecs explicitly listed on the command
88 line.
89
3240240f 90--receive-pack=<git-receive-pack>::
4fc988ef 91--exec=<git-receive-pack>::
ba020ef5 92 Path to the 'git-receive-pack' program on the remote
5214f770
UKK
93 end. Sometimes useful when pushing to a remote
94 repository over ssh, and you do not have the program in
95 a directory on the default $PATH.
96
3240240f
SB
97-f::
98--force::
f0fff36e 99 Usually, the command refuses to update a remote ref that is
64a476e6 100 not an ancestor of the local ref used to overwrite it.
f0fff36e
BF
101 This flag disables the check. This can cause the
102 remote repository to lose commits; use it with care.
7fc9d69f 103
bf07cc58
JS
104--repo=<repository>::
105 This option is only relevant if no <repository> argument is
106 passed in the invocation. In this case, 'git-push' derives the
107 remote name from the current branch: If it tracks a remote
108 branch, then that remote repository is pushed to. Otherwise,
109 the name "origin" is used. For this latter case, this option
110 can be used to override the name "origin". In other words,
111 the difference between these two commands
112+
113--------------------------
114git push public #1
115git push --repo=public #2
116--------------------------
117+
118is that #1 always pushes to "public" whereas #2 pushes to "public"
119only if the current branch does not track a remote branch. This is
120useful if you write an alias or script around 'git-push'.
dc36f265 121
3240240f
SB
122--thin::
123--no-thin::
ba020ef5 124 These options are passed to 'git-send-pack'. Thin
dc36f265
JH
125 transfer spends extra cycles to minimize the number of
126 objects to be sent and meant to be used on slower connection.
127
3240240f
SB
128-v::
129--verbose::
dc36f265
JH
130 Run verbosely.
131
37ba0561 132include::urls-remotes.txt[]
eb0362a4 133
066a5268
JK
134OUTPUT
135------
136
137The output of "git push" depends on the transport method used; this
138section describes the output when pushing over the git protocol (either
139locally or via ssh).
140
141The status of the push is output in tabular form, with each line
142representing the status of a single ref. Each line is of the form:
143
144-------------------------------
145 <flag> <summary> <from> -> <to> (<reason>)
146-------------------------------
147
148flag::
149 A single character indicating the status of the ref. This is
150 blank for a successfully pushed ref, `!` for a ref that was
151 rejected or failed to push, and '=' for a ref that was up to
152 date and did not need pushing (note that the status of up to
153 date refs is shown only when `git push` is running verbosely).
154
155summary::
156 For a successfully pushed ref, the summary shows the old and new
157 values of the ref in a form suitable for using as an argument to
158 `git log` (this is `<old>..<new>` in most cases, and
159 `<old>...<new>` for forced non-fast forward updates). For a
160 failed update, more details are given for the failure.
161 The string `rejected` indicates that git did not try to send the
162 ref at all (typically because it is not a fast forward). The
163 string `remote rejected` indicates that the remote end refused
164 the update; this rejection is typically caused by a hook on the
165 remote side. The string `remote failure` indicates that the
166 remote end did not report the successful update of the ref
167 (perhaps because of a temporary error on the remote side, a
168 break in the network connection, or other transient error).
169
170from::
171 The name of the local ref being pushed, minus its
172 `refs/<type>/` prefix. In the case of deletion, the
173 name of the local ref is omitted.
174
175to::
176 The name of the remote ref being updated, minus its
177 `refs/<type>/` prefix.
178
179reason::
180 A human-readable explanation. In the case of successfully pushed
181 refs, no explanation is needed. For a failed ref, the reason for
182 failure is described.
bb9fca80
JH
183
184Examples
185--------
186
187git push origin master::
188 Find a ref that matches `master` in the source repository
189 (most likely, it would find `refs/heads/master`), and update
190 the same ref (e.g. `refs/heads/master`) in `origin` repository
491b1b11
SV
191 with it. If `master` did not exist remotely, it would be
192 created.
bb9fca80 193
17507832
AM
194git push origin HEAD::
195 A handy way to push the current branch to the same name on the
196 remote.
bb9fca80 197
2c9693bd
AMS
198git push origin master:satellite/master dev:satellite/dev::
199 Use the source ref that matches `master` (e.g. `refs/heads/master`)
200 to update the ref that matches `satellite/master` (most probably
201 `refs/remotes/satellite/master`) in the `origin` repository, then
202 do the same for `dev` and `satellite/dev`.
bb9fca80 203
17507832
AM
204git push origin HEAD:master::
205 Push the current branch to the remote ref matching `master` in the
206 `origin` repository. This form is convenient to push the current
207 branch without thinking about its local name.
208
4e560158
SP
209git push origin master:refs/heads/experimental::
210 Create the branch `experimental` in the `origin` repository
491b1b11
SV
211 by copying the current `master` branch. This form is only
212 needed to create a new branch or tag in the remote repository when
213 the local name and the remote name are different; otherwise,
214 the ref name on its own will work.
4e560158 215
17507832
AM
216git push origin :experimental::
217 Find a ref that matches `experimental` in the `origin` repository
218 (e.g. `refs/heads/experimental`), and delete it.
219
220
7fc9d69f
JH
221Author
222------
59eb68aa 223Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C
25fb6290 224by Linus Torvalds <torvalds@osdl.org>
7fc9d69f
JH
225
226Documentation
227--------------
228Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
229
230GIT
231---
9e1f0a85 232Part of the linkgit:git[1] suite