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