doc: convert git push to synopsis style
- Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace - Use _<placeholder>_ instead of <placeholder> in the description - Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jean-Noël Avila committed
Nov 19, 2025 at 21:40 UTC
f7316a66d36f39ed9e5be7a3ce0ecd7b71430ff5
2 files changed
+201
-179
Documentation/config/push.adoc
+59
-54
@@ -1,15 +1,15 @@
1
-push.autoSetupRemote::
2
- If set to "true" assume `--set-upstream` on default push when no
1
+`push.autoSetupRemote`::
2
+ If set to `true` assume `--set-upstream` on default push when no
3
upstream tracking exists for the current branch; this option
4
- takes effect with push.default options 'simple', 'upstream',
5
- and 'current'. It is useful if by default you want new branches
4
+ takes effect with `push.default` options `simple`, `upstream`,
5
+ and `current`. It is useful if by default you want new branches
6
to be pushed to the default remote (like the behavior of
7
- 'push.default=current') and you also want the upstream tracking
7
+ `push.default=current`) and you also want the upstream tracking
8
to be set. Workflows most likely to benefit from this option are
9
- 'simple' central workflows where all branches are expected to
9
+ `simple` central workflows where all branches are expected to
10
have the same name on the remote.
11
12
-push.default::
12
+`push.default`::
13
Defines the action `git push` should take if no refspec is
14
given (whether from the command-line, config, or elsewhere).
15
Different values are well-suited for
@@ -18,24 +18,28 @@ push.default::
18
`upstream` is probably what you want. Possible values are:
19
+
20
--
21
-
22
-* `nothing` - do not push anything (error out) unless a refspec is
23
- given. This is primarily meant for people who want to
24
- avoid mistakes by always being explicit.
25
-
26
-* `current` - push the current branch to update a branch with the same
27
- name on the receiving end. Works in both central and non-central
28
- workflows.
29
-
30
-* `upstream` - push the current branch back to the branch whose
31
- changes are usually integrated into the current branch (which is
32
- called `@{upstream}`). This mode only makes sense if you are
33
- pushing to the same repository you would normally pull from
34
- (i.e. central workflow).
35
-
36
-* `tracking` - This is a deprecated synonym for `upstream`.
37
-
38
-* `simple` - push the current branch with the same name on the remote.
21
+`nothing`;;
22
+do not push anything (error out) unless a refspec is
23
+given. This is primarily meant for people who want to
24
+avoid mistakes by always being explicit.
25
+
26
+`current`;;
27
+push the current branch to update a branch with the same
28
+name on the receiving end. Works in both central and non-central
29
+workflows.
30
+
31
+`upstream`;;
32
+push the current branch back to the branch whose
33
+changes are usually integrated into the current branch (which is
34
+called `@{upstream}`). This mode only makes sense if you are
35
+pushing to the same repository you would normally pull from
36
+(i.e. central workflow).
37
+
38
+`tracking`;;
39
+this is a deprecated synonym for `upstream`.
40
+
41
+`simple`;;
42
+push the current branch with the same name on the remote.
43
+
44
If you are working on a centralized workflow (pushing to the same repository you
45
pull from, which is typically `origin`), then you need to configure an upstream
@@ -44,16 +48,17 @@ branch with the same name.
48
This mode is the default since Git 2.0, and is the safest option suited for
49
beginners.
50
47
-* `matching` - push all branches having the same name on both ends.
48
- This makes the repository you are pushing to remember the set of
49
- branches that will be pushed out (e.g. if you always push 'maint'
50
- and 'master' there and no other branches, the repository you push
51
- to will have these two branches, and your local 'maint' and
52
- 'master' will be pushed there).
51
+`matching`;;
52
+push all branches having the same name on both ends.
53
+This makes the repository you are pushing to remember the set of
54
+branches that will be pushed out (e.g. if you always push `maint`
55
+and `master` there and no other branches, the repository you push
56
+to will have these two branches, and your local `maint` and
57
+`master` will be pushed there).
58
+
59
To use this mode effectively, you have to make sure _all_ the
60
branches you would push out are ready to be pushed out before
56
-running 'git push', as the whole point of this mode is to allow you
61
+running `git push`, as the whole point of this mode is to allow you
62
to push all of the branches in one go. If you usually finish work
63
on only one branch and push out the result, while other branches are
64
unfinished, this mode is not for you. Also this mode is not
@@ -66,24 +71,24 @@ new default).
71
72
--
73
69
-push.followTags::
74
+`push.followTags`::
75
If set to true, enable `--follow-tags` option by default. You
76
may override this configuration at time of push by specifying
77
`--no-follow-tags`.
78
74
-push.gpgSign::
75
- May be set to a boolean value, or the string 'if-asked'. A true
79
+`push.gpgSign`::
80
+ May be set to a boolean value, or the string `if-asked`. A true
81
value causes all pushes to be GPG signed, as if `--signed` is
77
- passed to linkgit:git-push[1]. The string 'if-asked' causes
82
+ passed to linkgit:git-push[1]. The string `if-asked` causes
83
pushes to be signed if the server supports it, as if
79
- `--signed=if-asked` is passed to 'git push'. A false value may
84
+ `--signed=if-asked` is passed to `git push`. A false value may
85
override a value from a lower-priority config file. An explicit
86
command-line flag always overrides this config option.
87
83
-push.pushOption::
88
+`push.pushOption`::
89
When no `--push-option=<option>` argument is given from the
85
- command line, `git push` behaves as if each <value> of
86
- this variable is given as `--push-option=<value>`.
90
+ command line, `git push` behaves as if each _<option>_ of
91
+ this variable is given as `--push-option=<option>`.
92
+
93
This is a multi-valued variable, and an empty value can be used in a
94
higher priority configuration file (e.g. `.git/config` in a
@@ -109,26 +114,26 @@ This will result in only b (a and c are cleared).
114
115
----
116
112
-push.recurseSubmodules::
113
- May be "check", "on-demand", "only", or "no", with the same behavior
114
- as that of "push --recurse-submodules".
115
- If not set, 'no' is used by default, unless 'submodule.recurse' is
116
- set (in which case a 'true' value means 'on-demand').
117
+`push.recurseSubmodules`::
118
+ May be `check`, `on-demand`, `only`, or `no`, with the same behavior
119
+ as that of `push --recurse-submodules`.
120
+ If not set, `no` is used by default, unless `submodule.recurse` is
121
+ set (in which case a `true` value means `on-demand`).
122
118
-push.useForceIfIncludes::
119
- If set to "true", it is equivalent to specifying
123
+`push.useForceIfIncludes`::
124
+ If set to `true`, it is equivalent to specifying
125
`--force-if-includes` as an option to linkgit:git-push[1]
126
in the command line. Adding `--no-force-if-includes` at the
127
time of push overrides this configuration setting.
128
124
-push.negotiate::
125
- If set to "true", attempt to reduce the size of the packfile
129
+`push.negotiate`::
130
+ If set to `true`, attempt to reduce the size of the packfile
131
sent by rounds of negotiation in which the client and the
127
- server attempt to find commits in common. If "false", Git will
132
+ server attempt to find commits in common. If `false`, Git will
133
rely solely on the server's ref advertisement to find commits
134
in common.
135
131
-push.useBitmaps::
132
- If set to "false", disable use of bitmaps for "git push" even if
133
- `pack.useBitmaps` is "true", without preventing other git operations
134
- from using bitmaps. Default is true.
136
+`push.useBitmaps`::
137
+ If set to `false`, disable use of bitmaps for `git push` even if
138
+ `pack.useBitmaps` is `true`, without preventing other git operations
139
+ from using bitmaps. Default is `true`.
Documentation/git-push.adoc
+142
-125
@@ -8,13 +8,13 @@ git-push - Update remote refs along with associated objects
8
9
SYNOPSIS
10
--------
11
-[verse]
12
-'git push' [--all | --branches | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
13
- [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-q | --quiet] [-v | --verbose]
14
- [-u | --set-upstream] [-o <string> | --push-option=<string>]
15
- [--[no-]signed|--signed=(true|false|if-asked)]
16
- [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]]
17
- [--no-verify] [<repository> [<refspec>...]]
11
+[synopsis]
12
+git push [--all | --branches | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
13
+ [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-q | --quiet] [-v | --verbose]
14
+ [-u | --set-upstream] [-o <string> | --push-option=<string>]
15
+ [--[no-]signed | --signed=(true|false|if-asked)]
16
+ [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]]
17
+ [--no-verify] [<repository> [<refspec>...]]
18
19
DESCRIPTION
20
-----------
@@ -35,7 +35,7 @@ To decide which branches, tags, or other refs to push, Git uses
35
36
1. The `<refspec>` argument(s) (for example `main` in `git push origin main`)
37
or the `--all`, `--mirror`, or `--tags` options
38
-2. The `remote.*.push` configuration for the repository being pushed to
38
+2. The `remote.<name>.push` configuration for the repository being pushed to
39
3. The `push.default` configuration. The default is `push.default=simple`,
40
which will push to a branch with the same name as the current branch.
41
See the <<CONFIGURATION,CONFIGURATION>> section below for more on `push.default`.
@@ -49,25 +49,25 @@ You can make interesting things happen to a repository
49
every time you push into it, by setting up 'hooks' there. See
50
documentation for linkgit:git-receive-pack[1].
51
52
-
53
-OPTIONS[[OPTIONS]]
54
-------------------
55
-<repository>::
52
+[[OPTIONS]]
53
+OPTIONS
54
+-------
55
+_<repository>_::
56
The "remote" repository that is the destination of a push
57
operation. This parameter can be either a URL
58
(see the section <<URLS,GIT URLS>> below) or the name
59
of a remote (see the section <<REMOTES,REMOTES>> below).
60
61
-<refspec>...::
61
+`<refspec>...`::
62
Specify what destination ref to update with what source object.
63
+
64
-The format for a refspec is [+]<src>[:<dst>], for example `main`,
64
+The format for a refspec is `[+]<src>[:<dst>]`, for example `main`,
65
`main:other`, or `HEAD^:refs/heads/main`.
66
+
67
-The `<src>` is often the name of the local branch to push, but it can be
67
+The _<src>_ is often the name of the local branch to push, but it can be
68
any arbitrary "SHA-1 expression" (see linkgit:gitrevisions[7]).
69
+
70
-The `<dst>` determines what ref to update on the remote side. It must be the
70
+The _<dst>_ determines what ref to update on the remote side. It must be the
71
name of a branch, tag, or other ref, not an arbitrary expression.
72
+
73
The `+` is optional and does the same thing as `--force`.
@@ -78,23 +78,23 @@ and destination, or with a shorter form (for example `main` or
78
`main:other`). Here are the rules for how refspecs are expanded,
79
as well as various other special refspec forms:
80
+
81
- * `<src>` without a `:<dst>` means to update the same ref as the
82
- `<src>`, unless the `remote.<repository>.push` configuration specifies a
83
- different <dst>. For example, if `main` is a branch, then the refspec
81
+ * _<src>_ without a `:<dst>` means to update the same ref as the
82
+ _<src>_, unless the `remote.<repository>.push` configuration specifies a
83
+ different _<dst>_. For example, if `main` is a branch, then the refspec
84
`main` expands to `main:refs/heads/main`.
85
- * If `<dst>` unambiguously refers to a ref on the <repository> remote,
85
+ * If _<dst>_ unambiguously refers to a ref on the <repository> remote,
86
then expand it to that ref. For example, if `v1.0` is a tag on the
87
remote, then `HEAD:v1.0` expands to `HEAD:refs/tags/v1.0`.
88
- * If `<src>` resolves to a ref starting with `refs/heads/` or `refs/tags/`,
88
+ * If _<src>_ resolves to a ref starting with `refs/heads/` or `refs/tags/`,
89
then prepend that to <dst>. For example, if `main` is a branch, then
90
`main:other` expands to `main:refs/heads/other`
91
* The special refspec `:` (or `+:` to allow non-fast-forward updates)
92
directs Git to push "matching" branches: for every branch that exists on
93
the local side, the remote side is updated if a branch of the same name
94
already exists on the remote side.
95
- * <src> may contain a * to indicate a simple pattern match.
95
+ * _<src>_ may contain a `*` to indicate a simple pattern match.
96
This works like a glob that matches any ref matching the pattern.
97
- There must be only one * in both the `<src>` and `<dst>`.
97
+ There must be only one `*` in both the `<src>` and `<dst>`.
98
It will map refs to the destination by replacing the * with the
99
contents matched from the source. For example, `refs/heads/*:refs/heads/*`
100
will push all branches.
@@ -102,11 +102,11 @@ as well as various other special refspec forms:
102
This specifies refs to exclude. A ref will be considered to
103
match if it matches at least one positive refspec, and does not
104
match any negative refspec. Negative refspecs can be pattern refspecs.
105
- They must only contain a `<src>`.
105
+ They must only contain a _<src>_.
106
Fully spelled out hex object names are also not supported.
107
For example, `git push origin 'refs/heads/*' '^refs/heads/dev-*'`
108
will push all branches except for those starting with `dev-`
109
- * If `<src>` is empty, it deletes the `<dst>` ref from the remote
109
+ * If _<src>_ is empty, it deletes the _<dst>_ ref from the remote
110
repository. For example, `git push origin :dev` will
111
delete the `dev` branch.
112
* `tag <tag>` expands to `refs/tags/<tag>:refs/tags/<tag>`.
@@ -121,12 +121,12 @@ as well as various other special refspec forms:
121
122
Not all updates are allowed: see PUSH RULES below for the details.
123
124
---all::
125
---branches::
124
+`--all`::
125
+`--branches`::
126
Push all branches (i.e. refs under `refs/heads/`); cannot be
127
used with other <refspec>.
128
129
---prune::
129
+`--prune`::
130
Remove remote branches that don't have a local counterpart. For example
131
a remote branch `tmp` will be removed if a local branch with the same
132
name doesn't exist any more. This also respects refspecs, e.g.
@@ -134,7 +134,7 @@ Not all updates are allowed: see PUSH RULES below for the details.
134
make sure that remote `refs/tmp/foo` will be removed if `refs/heads/foo`
135
doesn't exist.
136
137
---mirror::
137
+`--mirror`::
138
Instead of naming each ref to push, specifies that all
139
refs under `refs/` (which includes but is not
140
limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
@@ -145,26 +145,26 @@ Not all updates are allowed: see PUSH RULES below for the details.
145
if the configuration option `remote.<remote>.mirror` is
146
set.
147
148
--n::
149
---dry-run::
148
+`-n`::
149
+`--dry-run`::
150
Do everything except actually send the updates.
151
152
---porcelain::
152
+`--porcelain`::
153
Produce machine-readable output. The output status line for each ref
154
will be tab-separated and sent to stdout instead of stderr. The full
155
symbolic names of the refs will be given.
156
157
--d::
158
---delete::
157
+`-d`::
158
+`--delete`::
159
All listed refs are deleted from the remote repository. This is
160
the same as prefixing all refs with a colon.
161
162
---tags::
162
+`--tags`::
163
All refs under `refs/tags` are pushed, in
164
addition to refspecs explicitly listed on the command
165
line.
166
167
---follow-tags::
167
+`--follow-tags`::
168
Push all the refs that would be pushed without this option,
169
and also push annotated tags in `refs/tags` that are missing
170
from the remote but are pointing at commit-ish that are
@@ -172,29 +172,34 @@ Not all updates are allowed: see PUSH RULES below for the details.
172
with configuration variable `push.followTags`. For more
173
information, see `push.followTags` in linkgit:git-config[1].
174
175
---signed::
176
---no-signed::
177
---signed=(true|false|if-asked)::
175
+`--signed`::
176
+`--no-signed`::
177
+`--signed=(true|false|if-asked)`::
178
GPG-sign the push request to update refs on the receiving
179
side, to allow it to be checked by the hooks and/or be
180
- logged. If `false` or `--no-signed`, no signing will be
181
- attempted. If `true` or `--signed`, the push will fail if the
182
- server does not support signed pushes. If set to `if-asked`,
183
- sign if and only if the server supports signed pushes. The push
184
- will also fail if the actual call to `gpg --sign` fails. See
185
- linkgit:git-receive-pack[1] for the details on the receiving end.
186
-
187
---atomic::
188
---no-atomic::
180
+ logged. Possible values are:
181
+`false`;;
182
+`--no-signed`;;
183
+no signing will be attempted.
184
+`true`;;
185
+`--signed`;;
186
+the push will fail if the server does not support signed pushes.
187
+`if-asked`;;
188
+sign if and only if the server supports signed pushes. The push
189
+will also fail if the actual call to `gpg --sign` fails. See
190
+linkgit:git-receive-pack[1] for the details on the receiving end.
191
+
192
+`--atomic`::
193
+`--no-atomic`::
194
Use an atomic transaction on the remote side if available.
195
Either all refs are updated, or on error, no refs are updated.
196
If the server does not support atomic pushes the push will fail.
197
193
--o <option>::
194
---push-option=<option>::
198
+`-o <option>`::
199
+`--push-option=<option>`::
200
Transmit the given string to the server, which passes them to
201
the pre-receive as well as the post-receive hook. The given string
197
- must not contain a NUL or LF character.
202
+ must not contain a _NUL_ or _LF_ character.
203
When multiple `--push-option=<option>` are given, they are
204
all sent to the other side in the order listed on the
205
command line.
@@ -202,22 +207,22 @@ Not all updates are allowed: see PUSH RULES below for the details.
207
line, the values of configuration variable `push.pushOption`
208
are used instead.
209
205
---receive-pack=<git-receive-pack>::
206
---exec=<git-receive-pack>::
210
+`--receive-pack=<git-receive-pack>`::
211
+`--exec=<git-receive-pack>`::
212
Path to the 'git-receive-pack' program on the remote
213
end. Sometimes useful when pushing to a remote
214
repository over ssh, and you do not have the program in
210
- a directory on the default $PATH.
215
+ a directory on the default `$PATH`.
216
212
---force-with-lease::
213
---no-force-with-lease::
214
---force-with-lease=<refname>::
215
---force-with-lease=<refname>:<expect>::
216
- Usually, "git push" refuses to update a remote ref that is
217
+`--force-with-lease`::
218
+`--no-force-with-lease`::
219
+`--force-with-lease=<refname>`::
220
+`--force-with-lease=<refname>:<expect>`::
221
+ Usually, `git push` refuses to update a remote ref that is
222
not an ancestor of the local ref used to overwrite it.
223
+
224
This option overrides this restriction if the current value of the
220
-remote ref is the expected value. "git push" fails otherwise.
225
+remote ref is the expected value. `git push` fails otherwise.
226
+
227
Imagine that you have to rebase what you have already published.
228
You will have to bypass the "must fast-forward" rule in order to
@@ -239,16 +244,16 @@ current value to be the same as the remote-tracking branch we have
244
for them.
245
+
246
`--force-with-lease=<refname>`, without specifying the expected value, will
242
-protect the named ref (alone), if it is going to be updated, by
247
+protect _<refname>_ (alone), if it is going to be updated, by
248
requiring its current value to be the same as the remote-tracking
249
branch we have for it.
250
+
246
-`--force-with-lease=<refname>:<expect>` will protect the named ref (alone),
251
+`--force-with-lease=<refname>:<expect>` will protect _<refname>_ (alone),
252
if it is going to be updated, by requiring its current value to be
248
-the same as the specified value `<expect>` (which is allowed to be
253
+the same as the specified value _<expect>_ (which is allowed to be
254
different from the remote-tracking branch we have for the refname,
255
or we do not even have to have such a remote-tracking branch when
251
-this form is used). If `<expect>` is the empty string, then the named ref
256
+this form is used). If _<expect>_ is the empty string, then the named ref
257
must not already exist.
258
+
259
Note that all forms other than `--force-with-lease=<refname>:<expect>`
@@ -256,7 +261,7 @@ that specifies the expected current value of the ref explicitly are
261
still experimental and their semantics may change as we gain experience
262
with this feature.
263
+
259
-"--no-force-with-lease" will cancel all the previous --force-with-lease on the
264
+`--no-force-with-lease` will cancel all the previous `--force-with-lease` on the
265
command line.
266
+
267
A general note on safety: supplying this option without an expected
@@ -276,23 +281,29 @@ If your editor or some other system is running `git fetch` in the
281
background for you a way to mitigate this is to simply set up another
282
remote:
283
+
279
- git remote add origin-push $(git config remote.origin.url)
280
- git fetch origin-push
284
+----
285
+git remote add origin-push $(git config remote.origin.url)
286
+git fetch origin-push
287
+----
288
+
289
Now when the background process runs `git fetch origin` the references
290
on `origin-push` won't be updated, and thus commands like:
291
+
285
- git push --force-with-lease origin-push
292
+----
293
+git push --force-with-lease origin-push
294
+----
295
+
296
Will fail unless you manually run `git fetch origin-push`. This method
297
is of course entirely defeated by something that runs `git fetch
298
--all`, in that case you'd need to either disable it or do something
299
more tedious like:
300
+
292
- git fetch # update 'master' from remote
293
- git tag base master # mark our base point
294
- git rebase -i master # rewrite some commits
295
- git push --force-with-lease=master:base master:master
301
+----
302
+git fetch # update 'master' from remote
303
+git tag base master # mark our base point
304
+git rebase -i master # rewrite some commits
305
+git push --force-with-lease=master:base master:master
306
+----
307
+
308
I.e. create a `base` tag for versions of the upstream code that you've
309
seen and are willing to overwrite, then rewrite history, and finally
@@ -308,26 +319,26 @@ verify if updates from the remote-tracking refs that may have been
319
implicitly updated in the background are integrated locally before
320
allowing a forced update.
321
311
--f::
312
---force::
322
+`-f`::
323
+`--force`::
324
Usually, `git push` will refuse to update a branch that is not an
325
ancestor of the commit being pushed.
326
+
327
This flag disables that check, the other safety checks in PUSH RULES
317
-below, and the checks in --force-with-lease. It can cause the remote
328
+below, and the checks in `--force-with-lease`. It can cause the remote
329
repository to lose commits; use it with care.
330
+
331
Note that `--force` applies to all the refs that are pushed, hence
332
using it with `push.default` set to `matching` or with multiple push
322
-destinations configured with `remote.*.push` may overwrite refs
333
+destinations configured with `remote.<name>.push` may overwrite refs
334
other than the current branch (including local refs that are
335
strictly behind their remote counterpart). To force a push to only
336
one branch, use a `+` in front of the refspec to push (e.g `git push
337
origin +master` to force a push to the `master` branch). See the
338
`<refspec>...` section above for details.
339
329
---force-if-includes::
330
---no-force-if-includes::
340
+`--force-if-includes`::
341
+`--no-force-if-includes`::
342
Force an update only if the tip of the remote-tracking ref
343
has been integrated locally.
344
+
@@ -343,72 +354,78 @@ a "no-op".
354
+
355
Specifying `--no-force-if-includes` disables this behavior.
356
346
---repo=<repository>::
347
- This option is equivalent to the <repository> argument. If both
357
+`--repo=<repository>`::
358
+ This option is equivalent to the _<repository>_ argument. If both
359
are specified, the command-line argument takes precedence.
360
350
--u::
351
---set-upstream::
361
+`-u`::
362
+`--set-upstream`::
363
For every branch that is up to date or successfully pushed, add
364
upstream (tracking) reference, used by argument-less
365
linkgit:git-pull[1] and other commands. For more information,
366
see `branch.<name>.merge` in linkgit:git-config[1].
367
357
---thin::
358
---no-thin::
368
+`--thin`::
369
+`--no-thin`::
370
These options are passed to linkgit:git-send-pack[1]. A thin transfer
371
significantly reduces the amount of sent data when the sender and
372
receiver share many of the same objects in common. The default is
373
`--thin`.
374
364
--q::
365
---quiet::
375
+`-q`::
376
+`--quiet`::
377
Suppress all output, including the listing of updated refs,
378
unless an error occurs. Progress is not reported to the standard
379
error stream.
380
370
--v::
371
---verbose::
381
+`-v`::
382
+`--verbose`::
383
Run verbosely.
384
374
---progress::
385
+`--progress`::
386
Progress status is reported on the standard error stream
376
- by default when it is attached to a terminal, unless -q
387
+ by default when it is attached to a terminal, unless `-q`
388
is specified. This flag forces progress status even if the
389
standard error stream is not directed to a terminal.
390
380
---no-recurse-submodules::
381
---recurse-submodules=check|on-demand|only|no::
391
+`--no-recurse-submodules`::
392
+`--recurse-submodules=(check|on-demand|only|no)`::
393
May be used to make sure all submodule commits used by the
394
revisions to be pushed are available on a remote-tracking branch.
384
- If 'check' is used Git will verify that all submodule commits that
395
+ Possible values are:
396
+`check`;;
397
+ Git will verify that all submodule commits that
398
changed in the revisions to be pushed are available on at least one
399
remote of the submodule. If any commits are missing the push will
387
- be aborted and exit with non-zero status. If 'on-demand' is used
400
+ be aborted and exit with non-zero status.
401
+`on-demand`;;
402
all submodules that changed in the revisions to be pushed will be
389
- pushed. If on-demand was not able to push all necessary revisions it will
390
- also be aborted and exit with non-zero status. If 'only' is used all
391
- submodules will be pushed while the superproject is left
392
- unpushed. A value of 'no' or using `--no-recurse-submodules` can be used
393
- to override the push.recurseSubmodules configuration variable when no
394
- submodule recursion is required.
395
-+
396
-When using 'on-demand' or 'only', if a submodule has a
397
-"push.recurseSubmodules={on-demand,only}" or "submodule.recurse" configuration,
398
-further recursion will occur. In this case, "only" is treated as "on-demand".
399
-
400
---verify::
401
---no-verify::
403
+ pushed. If `on-demand` was not able to push all necessary revisions it will
404
+ also be aborted and exit with non-zero status.
405
+`only`;;
406
+ all submodules will be pushed while the superproject is left
407
+ unpushed.
408
+`no`;;
409
+ override the `push.recurseSubmodules` configuration variable when no
410
+ submodule recursion is required. Similar to using `--no-recurse-submodules`.
411
+
412
++
413
+When using `on-demand` or `only`, if a submodule has a
414
+`push.recurseSubmodules=(on-demand|only)` or `submodule.recurse` configuration,
415
+further recursion will occur. In this case, `only` is treated as `on-demand`.
416
+
417
+`--verify`::
418
+`--no-verify`::
419
Toggle the pre-push hook (see linkgit:githooks[5]). The
403
- default is --verify, giving the hook a chance to prevent the
404
- push. With --no-verify, the hook is bypassed completely.
420
+ default is `--verify`, giving the hook a chance to prevent the
421
+ push. With `--no-verify`, the hook is bypassed completely.
422
406
--4::
407
---ipv4::
423
+`-4`::
424
+`--ipv4`::
425
Use IPv4 addresses only, ignoring IPv6 addresses.
426
410
--6::
411
---ipv6::
427
+`-6`::
428
+`--ipv6`::
429
Use IPv6 addresses only, ignoring IPv4 addresses.
430
431
include::urls-remotes.adoc[]
@@ -427,16 +444,16 @@ representing the status of a single ref. Each line is of the form:
444
<flag> <summary> <from> -> <to> (<reason>)
445
-------------------------------
446
430
-If --porcelain is used, then each line of the output is of the form:
447
+If `--porcelain` is used, then each line of the output is of the form:
448
449
-------------------------------
450
<flag> \t <from>:<to> \t <summary> (<reason>)
451
-------------------------------
452
436
-The status of up-to-date refs is shown only if --porcelain or --verbose
453
+The status of up-to-date refs is shown only if `--porcelain` or `--verbose`
454
option is used.
455
439
-flag::
456
+_<flag>_::
457
A single character indicating the status of the ref:
458
(space);; for a successfully pushed fast-forward;
459
`+`;; for a successful forced update;
@@ -445,7 +462,7 @@ flag::
462
`!`;; for a ref that was rejected or failed to push; and
463
`=`;; for a ref that was up to date and did not need pushing.
464
448
-summary::
465
+_<summary>_::
466
For a successfully pushed ref, the summary shows the old and new
467
values of the ref in a form suitable for using as an argument to
468
`git log` (this is `<old>..<new>` in most cases, and
@@ -586,7 +603,7 @@ Updating A with the resulting merge commit will fast-forward and your
603
push will be accepted.
604
605
Alternatively, you can rebase your change between X and B on top of A,
589
-with "git pull --rebase", and push the result back. The rebase will
606
+with `git pull --rebase`, and push the result back. The rebase will
607
create a new commit D that builds the change between X and B on top of
608
A.
609
@@ -604,12 +621,12 @@ accepted.
621
There is another common situation where you may encounter non-fast-forward
622
rejection when you try to push, and it is possible even when you are
623
pushing into a repository nobody else pushes into. After you push commit
607
-A yourself (in the first picture in this section), replace it with "git
608
-commit --amend" to produce commit B, and you try to push it out, because
624
+A yourself (in the first picture in this section), replace it with `git
625
+commit --amend` to produce commit B, and you try to push it out, because
626
forgot that you have pushed A out already. In such a case, and only if
627
you are certain that nobody in the meantime fetched your earlier commit A
611
-(and started building on top of it), you can run "git push --force" to
612
-overwrite it. In other words, "git push --force" is a method reserved for
628
+(and started building on top of it), you can run `git push --force` to
629
+overwrite it. In other words, `git push --force` is a method reserved for
630
a case where you do mean to lose history.
631
632
@@ -627,18 +644,18 @@ EXAMPLES
644
variable) if it has the same name as the current branch, and
645
errors out without pushing otherwise.
646
+
630
-The default behavior of this command when no <refspec> is given can be
647
+The default behavior of this command when no _<refspec>_ is given can be
648
configured by setting the `push` option of the remote, or the `push.default`
649
configuration variable.
650
+
651
For example, to default to pushing only the current branch to `origin`
635
-use `git config remote.origin.push HEAD`. Any valid <refspec> (like
652
+use `git config remote.origin.push HEAD`. Any valid _<refspec>_ (like
653
the ones in the examples below) can be configured as the default for
654
`git push origin`.
655
656
`git push origin :`::
657
Push "matching" branches to `origin`. See
641
- <refspec> in the <<OPTIONS,OPTIONS>> section above for a
658
+ _<refspec>_ in the <<OPTIONS,OPTIONS>> section above for a
659
description of "matching" branches.
660
661
`git push origin master`::