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