doc: convert git fetch 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
903b04a3e721f4afb337bd48890b69e16c04c5d6
6 files changed
+190
-189
Documentation/config/fetch.adoc
+30
-30
@@ -1,32 +1,32 @@
1
-fetch.recurseSubmodules::
1
+`fetch.recurseSubmodules`::
2
This option controls whether `git fetch` (and the underlying fetch
3
in `git pull`) will recursively fetch into populated submodules.
4
- This option can be set either to a boolean value or to 'on-demand'.
4
+ This option can be set either to a boolean value or to `on-demand`.
5
Setting it to a boolean changes the behavior of fetch and pull to
6
recurse unconditionally into submodules when set to true or to not
7
- recurse at all when set to false. When set to 'on-demand', fetch and
7
+ recurse at all when set to false. When set to `on-demand`, fetch and
8
pull will only recurse into a populated submodule when its
9
superproject retrieves a commit that updates the submodule's
10
reference.
11
- Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.
11
+ Defaults to `on-demand`, or to the value of `submodule.recurse` if set.
12
13
-fetch.fsckObjects::
13
+`fetch.fsckObjects`::
14
If it is set to true, git-fetch-pack will check all fetched
15
objects. See `transfer.fsckObjects` for what's
16
- checked. Defaults to false. If not set, the value of
16
+ checked. Defaults to `false`. If not set, the value of
17
`transfer.fsckObjects` is used instead.
18
19
-fetch.fsck.<msg-id>::
19
+`fetch.fsck.<msg-id>`::
20
Acts like `fsck.<msg-id>`, but is used by
21
linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See
22
the `fsck.<msg-id>` documentation for details.
23
24
-fetch.fsck.skipList::
24
+`fetch.fsck.skipList`::
25
Acts like `fsck.skipList`, but is used by
26
linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See
27
the `fsck.skipList` documentation for details.
28
29
-fetch.unpackLimit::
29
+`fetch.unpackLimit`::
30
If the number of objects fetched over the Git native
31
transfer is below this
32
limit, then the objects will be unpacked into loose object
@@ -37,12 +37,12 @@ fetch.unpackLimit::
37
especially on slow filesystems. If not set, the value of
38
`transfer.unpackLimit` is used instead.
39
40
-fetch.prune::
40
+`fetch.prune`::
41
If true, fetch will automatically behave as if the `--prune`
42
option was given on the command line. See also `remote.<name>.prune`
43
and the PRUNING section of linkgit:git-fetch[1].
44
45
-fetch.pruneTags::
45
+`fetch.pruneTags`::
46
If true, fetch will automatically behave as if the
47
`refs/tags/*:refs/tags/*` refspec was provided when pruning,
48
if not set already. This allows for setting both this option
@@ -50,41 +50,41 @@ fetch.pruneTags::
50
refs. See also `remote.<name>.pruneTags` and the PRUNING
51
section of linkgit:git-fetch[1].
52
53
-fetch.all::
53
+`fetch.all`::
54
If true, fetch will attempt to update all available remotes.
55
This behavior can be overridden by passing `--no-all` or by
56
explicitly specifying one or more remote(s) to fetch from.
57
- Defaults to false.
57
+ Defaults to `false`.
58
59
-fetch.output::
59
+`fetch.output`::
60
Control how ref update status is printed. Valid values are
61
`full` and `compact`. Default value is `full`. See the
62
OUTPUT section in linkgit:git-fetch[1] for details.
63
64
-fetch.negotiationAlgorithm::
64
+`fetch.negotiationAlgorithm`::
65
Control how information about the commits in the local repository
66
is sent when negotiating the contents of the packfile to be sent by
67
- the server. Set to "consecutive" to use an algorithm that walks
68
- over consecutive commits checking each one. Set to "skipping" to
67
+ the server. Set to `consecutive` to use an algorithm that walks
68
+ over consecutive commits checking each one. Set to `skipping` to
69
use an algorithm that skips commits in an effort to converge
70
faster, but may result in a larger-than-necessary packfile; or set
71
- to "noop" to not send any information at all, which will almost
71
+ to `noop` to not send any information at all, which will almost
72
certainly result in a larger-than-necessary packfile, but will skip
73
- the negotiation step. Set to "default" to override settings made
73
+ the negotiation step. Set to `default` to override settings made
74
previously and use the default behaviour. The default is normally
75
- "consecutive", but if `feature.experimental` is true, then the
76
- default is "skipping". Unknown values will cause 'git fetch' to
75
+ `consecutive`, but if `feature.experimental` is `true`, then the
76
+ default is `skipping`. Unknown values will cause `git fetch` to
77
error out.
78
+
79
See also the `--negotiate-only` and `--negotiation-tip` options to
80
linkgit:git-fetch[1].
81
82
-fetch.showForcedUpdates::
83
- Set to false to enable `--no-show-forced-updates` in
82
+`fetch.showForcedUpdates`::
83
+ Set to `false` to enable `--no-show-forced-updates` in
84
linkgit:git-fetch[1] and linkgit:git-pull[1] commands.
85
- Defaults to true.
85
+ Defaults to `true`.
86
87
-fetch.parallel::
87
+`fetch.parallel`::
88
Specifies the maximal number of fetch operations to be run in parallel
89
at a time (submodules, or remotes when the `--multiple` option of
90
linkgit:git-fetch[1] is in effect).
@@ -94,16 +94,16 @@ A value of 0 will give some reasonable default. If unset, it defaults to 1.
94
For submodules, this setting can be overridden using the `submodule.fetchJobs`
95
config setting.
96
97
-fetch.writeCommitGraph::
97
+`fetch.writeCommitGraph`::
98
Set to true to write a commit-graph after every `git fetch` command
99
that downloads a pack-file from a remote. Using the `--split` option,
100
most executions will create a very small commit-graph file on top of
101
the existing commit-graph file(s). Occasionally, these files will
102
merge and the write may take longer. Having an updated commit-graph
103
file helps performance of many Git commands, including `git merge-base`,
104
- `git push -f`, and `git log --graph`. Defaults to false.
104
+ `git push -f`, and `git log --graph`. Defaults to `false`.
105
106
-fetch.bundleURI::
106
+`fetch.bundleURI`::
107
This value stores a URI for downloading Git object data from a bundle
108
URI before performing an incremental fetch from the origin Git server.
109
This is similar to how the `--bundle-uri` option behaves in
@@ -115,9 +115,9 @@ If you modify this value and your repository has a `fetch.bundleCreationToken`
115
value, then remove that `fetch.bundleCreationToken` value before fetching from
116
the new bundle URI.
117
118
-fetch.bundleCreationToken::
118
+`fetch.bundleCreationToken`::
119
When using `fetch.bundleURI` to fetch incrementally from a bundle
120
- list that uses the "creationToken" heuristic, this config value
120
+ list that uses the "`creationToken`" heuristic, this config value
121
stores the maximum `creationToken` value of the downloaded bundles.
122
This value is used to prevent downloading bundles in the future
123
if the advertised `creationToken` is not strictly larger than this
Documentation/fetch-options.adoc
+101
-100
@@ -1,41 +1,41 @@
1
---all::
2
---no-all::
1
+`--all`::
2
+`--no-all`::
3
Fetch all remotes, except for the ones that has the
4
`remote.<name>.skipFetchAll` configuration variable set.
5
This overrides the configuration variable `fetch.all`.
6
7
--a::
8
---append::
7
+`-a`::
8
+`--append`::
9
Append ref names and object names of fetched refs to the
10
existing contents of `.git/FETCH_HEAD`. Without this
11
option old data in `.git/FETCH_HEAD` will be overwritten.
12
13
---atomic::
13
+`--atomic`::
14
Use an atomic transaction to update local refs. Either all refs are
15
updated, or on error, no refs are updated.
16
17
---depth=<depth>::
17
+`--depth=<depth>`::
18
Limit fetching to the specified number of commits from the tip of
19
each remote branch history. If fetching to a 'shallow' repository
20
created by `git clone` with `--depth=<depth>` option (see
21
linkgit:git-clone[1]), deepen or shorten the history to the specified
22
number of commits. Tags for the deepened commits are not fetched.
23
24
---deepen=<depth>::
25
- Similar to --depth, except it specifies the number of commits
24
+`--deepen=<depth>`::
25
+ Similar to `--depth`, except it specifies the number of commits
26
from the current shallow boundary instead of from the tip of
27
each remote branch history.
28
29
---shallow-since=<date>::
29
+`--shallow-since=<date>`::
30
Deepen or shorten the history of a shallow repository to
31
- include all reachable commits after <date>.
31
+ include all reachable commits after _<date>_.
32
33
---shallow-exclude=<ref>::
33
+`--shallow-exclude=<ref>`::
34
Deepen or shorten the history of a shallow repository to
35
exclude commits reachable from a specified remote branch or tag.
36
This option can be specified multiple times.
37
38
---unshallow::
38
+`--unshallow`::
39
If the source repository is complete, convert a shallow
40
repository to a complete one, removing all the limitations
41
imposed by shallow repositories.
@@ -43,13 +43,13 @@
43
If the source repository is shallow, fetch as much as possible so that
44
the current repository has the same history as the source repository.
45
46
---update-shallow::
46
+`--update-shallow`::
47
By default when fetching from a shallow repository,
48
`git fetch` refuses refs that require updating
49
- .git/shallow. This option updates .git/shallow and accepts such
49
+ `.git/shallow`. This option updates `.git/shallow` and accepts such
50
refs.
51
52
---negotiation-tip=<commit|glob>::
52
+`--negotiation-tip=(<commit>|<glob>)`::
53
By default, Git will report, to the server, commits reachable
54
from all local refs to find common commits in an attempt to
55
reduce the size of the to-be-received packfile. If specified,
@@ -69,28 +69,28 @@ See also the `fetch.negotiationAlgorithm` and `push.negotiate`
69
configuration variables documented in linkgit:git-config[1], and the
70
`--negotiate-only` option below.
71
72
---negotiate-only::
72
+`--negotiate-only`::
73
Do not fetch anything from the server, and instead print the
74
ancestors of the provided `--negotiation-tip=*` arguments,
75
which we have in common with the server.
76
+
77
-This is incompatible with `--recurse-submodules=[yes|on-demand]`.
77
+This is incompatible with `--recurse-submodules=(yes|on-demand)`.
78
Internally this is used to implement the `push.negotiate` option, see
79
linkgit:git-config[1].
80
81
---dry-run::
81
+`--dry-run`::
82
Show what would be done, without making any changes.
83
84
---porcelain::
84
+`--porcelain`::
85
Print the output to standard output in an easy-to-parse format for
86
scripts. See section OUTPUT in linkgit:git-fetch[1] for details.
87
+
88
-This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes
88
+This is incompatible with `--recurse-submodules=(yes|on-demand)` and takes
89
precedence over the `fetch.output` config option.
90
91
ifndef::git-pull[]
92
---write-fetch-head::
93
---no-write-fetch-head::
92
+`--write-fetch-head`::
93
+`--no-write-fetch-head`::
94
Write the list of remote refs fetched in the `FETCH_HEAD`
95
file directly under `$GIT_DIR`. This is the default.
96
Passing `--no-write-fetch-head` from the command line tells
@@ -98,64 +98,65 @@ ifndef::git-pull[]
98
file is never written.
99
endif::git-pull[]
100
101
--f::
102
---force::
103
- When 'git fetch' is used with `<src>:<dst>` refspec, it may
104
- refuse to update the local branch as discussed
101
+`-f`::
102
+`--force`::
103
ifdef::git-pull[]
106
- in the `<refspec>` part of the linkgit:git-fetch[1]
107
- documentation.
104
+When `git fetch` is used with `<src>:<dst>` refspec, it may
105
+refuse to update the local branch as discussed
106
+in the _<refspec>_ part of the linkgit:git-fetch[1]
107
+documentation.
108
endif::git-pull[]
109
ifndef::git-pull[]
110
- in the `<refspec>` part below.
110
+When `git fetch` is used with `<src>:<dst>` refspec, it may
111
+refuse to update the local branch as discussed in the _<refspec>_ part below.
112
endif::git-pull[]
112
- This option overrides that check.
113
+This option overrides that check.
114
114
--k::
115
---keep::
115
+`-k`::
116
+`--keep`::
117
Keep downloaded pack.
118
119
ifndef::git-pull[]
119
---multiple::
120
- Allow several <repository> and <group> arguments to be
121
- specified. No <refspec>s may be specified.
122
-
123
---auto-maintenance::
124
---no-auto-maintenance::
125
---auto-gc::
126
---no-auto-gc::
120
+`--multiple`::
121
+ Allow several _<repository>_ and _<group>_ arguments to be
122
+ specified. No __<refspec>__s may be specified.
123
+
124
+`--auto-maintenance`::
125
+`--no-auto-maintenance`::
126
+`--auto-gc`::
127
+`--no-auto-gc`::
128
Run `git maintenance run --auto` at the end to perform automatic
129
repository maintenance if needed. (`--[no-]auto-gc` is a synonym.)
130
This is enabled by default.
131
131
---write-commit-graph::
132
---no-write-commit-graph::
132
+`--write-commit-graph`::
133
+`--no-write-commit-graph`::
134
Write a commit-graph after fetching. This overrides the config
135
setting `fetch.writeCommitGraph`.
136
endif::git-pull[]
137
137
---prefetch::
138
+`--prefetch`::
139
Modify the configured refspec to place all refs into the
140
`refs/prefetch/` namespace. See the `prefetch` task in
141
linkgit:git-maintenance[1].
142
142
--p::
143
---prune::
143
+`-p`::
144
+`--prune`::
145
Before fetching, remove any remote-tracking references that no
146
longer exist on the remote. Tags are not subject to pruning
147
if they are fetched only because of the default tag
147
- auto-following or due to a --tags option. However, if tags
148
+ auto-following or due to a `--tags` option. However, if tags
149
are fetched due to an explicit refspec (either on the command
150
line or in the remote configuration, for example if the remote
150
- was cloned with the --mirror option), then they are also
151
+ was cloned with the `--mirror` option), then they are also
152
subject to pruning. Supplying `--prune-tags` is a shorthand for
153
providing the tag refspec.
154
ifndef::git-pull[]
155
+
156
See the PRUNING section below for more details.
157
157
--P::
158
---prune-tags::
158
+`-P`::
159
+`--prune-tags`::
160
Before fetching, remove any local tags that no longer exist on
161
the remote if `--prune` is enabled. This option should be used
162
more carefully, unlike `--prune` it will remove any local
@@ -168,17 +169,17 @@ See the PRUNING section below for more details.
169
endif::git-pull[]
170
171
ifndef::git-pull[]
171
--n::
172
+`-n`::
173
endif::git-pull[]
173
---no-tags::
174
+`--no-tags`::
175
By default, tags that point at objects that are downloaded
176
from the remote repository are fetched and stored locally.
177
This option disables this automatic tag following. The default
177
- behavior for a remote may be specified with the remote.<name>.tagOpt
178
+ behavior for a remote may be specified with the `remote.<name>.tagOpt`
179
setting. See linkgit:git-config[1].
180
181
ifndef::git-pull[]
181
---refetch::
182
+`--refetch`::
183
Instead of negotiating with the server to avoid transferring commits and
184
associated objects that are already present locally, this option fetches
185
all objects as a fresh clone would. Use this to reapply a partial clone
@@ -187,19 +188,19 @@ ifndef::git-pull[]
188
object database pack consolidation to remove any duplicate objects.
189
endif::git-pull[]
190
190
---refmap=<refspec>::
191
+`--refmap=<refspec>`::
192
When fetching refs listed on the command line, use the
193
specified refspec (can be given more than once) to map the
194
refs to remote-tracking branches, instead of the values of
194
- `remote.*.fetch` configuration variables for the remote
195
+ `remote.<name>.fetch` configuration variables for the remote
196
repository. Providing an empty `<refspec>` to the
197
`--refmap` option causes Git to ignore the configured
198
refspecs and rely entirely on the refspecs supplied as
199
command-line arguments. See section on "Configured Remote-tracking
200
Branches" for details.
201
201
--t::
202
---tags::
202
+`-t`::
203
+`--tags`::
204
Fetch all tags from the remote (i.e., fetch remote tags
205
`refs/tags/*` into local tags with the same name), in addition
206
to whatever else would otherwise be fetched. Using this
@@ -208,8 +209,8 @@ endif::git-pull[]
209
destination of an explicit refspec; see `--prune`).
210
211
ifndef::git-pull[]
211
---recurse-submodules[=(yes|on-demand|no)]::
212
- This option controls if and under what conditions new commits of
212
+`--recurse-submodules[=(yes|on-demand|no)]`::
213
+ Control if and under what conditions new commits of
214
submodules should be fetched too. When recursing through submodules,
215
`git fetch` always attempts to fetch "changed" submodules, that is, a
216
submodule that has commits that are referenced by a newly fetched
@@ -219,19 +220,19 @@ ifndef::git-pull[]
220
adds a new submodule, that submodule cannot be fetched until it is
221
cloned e.g. by `git submodule update`.
222
+
222
-When set to 'on-demand', only changed submodules are fetched. When set
223
-to 'yes', all populated submodules are fetched and submodules that are
224
-both unpopulated and changed are fetched. When set to 'no', submodules
223
+When set to `on-demand`, only changed submodules are fetched. When set
224
+to `yes`, all populated submodules are fetched and submodules that are
225
+both unpopulated and changed are fetched. When set to `no`, submodules
226
are never fetched.
227
+
228
When unspecified, this uses the value of `fetch.recurseSubmodules` if it
228
-is set (see linkgit:git-config[1]), defaulting to 'on-demand' if unset.
229
-When this option is used without any value, it defaults to 'yes'.
229
+is set (see linkgit:git-config[1]), defaulting to `on-demand` if unset.
230
+When this option is used without any value, it defaults to `yes`.
231
endif::git-pull[]
232
232
--j::
233
---jobs=<n>::
234
- Number of parallel children to be used for all forms of fetching.
233
+`-j <n>`::
234
+`--jobs=<n>`::
235
+ Parallelize all forms of fetching up to _<n>_ jobs at a time.
236
+
237
If the `--multiple` option was specified, the different remotes will be fetched
238
in parallel. If multiple submodules are fetched, they will be fetched in
@@ -242,12 +243,12 @@ Typically, parallel recursive and multi-remote fetches will be faster. By
243
default fetches are performed sequentially, not in parallel.
244
245
ifndef::git-pull[]
245
---no-recurse-submodules::
246
+`--no-recurse-submodules`::
247
Disable recursive fetching of submodules (this has the same effect as
248
using the `--recurse-submodules=no` option).
249
endif::git-pull[]
250
250
---set-upstream::
251
+`--set-upstream`::
252
If the remote is fetched successfully, add upstream
253
(tracking) reference, used by argument-less
254
linkgit:git-pull[1] and other commands. For more information,
@@ -255,55 +256,55 @@ endif::git-pull[]
256
linkgit:git-config[1].
257
258
ifndef::git-pull[]
258
---submodule-prefix=<path>::
259
- Prepend <path> to paths printed in informative messages
259
+`--submodule-prefix=<path>`::
260
+ Prepend _<path>_ to paths printed in informative messages
261
such as "Fetching submodule foo". This option is used
262
internally when recursing over submodules.
263
263
---recurse-submodules-default=[yes|on-demand]::
264
+`--recurse-submodules-default=(yes|on-demand)`::
265
This option is used internally to temporarily provide a
265
- non-negative default value for the --recurse-submodules
266
+ non-negative default value for the `--recurse-submodules`
267
option. All other methods of configuring fetch's submodule
268
recursion (such as settings in linkgit:gitmodules[5] and
269
linkgit:git-config[1]) override this option, as does
269
- specifying --[no-]recurse-submodules directly.
270
+ specifying `--[no-]recurse-submodules` directly.
271
271
--u::
272
---update-head-ok::
273
- By default 'git fetch' refuses to update the head which
272
+`-u`::
273
+`--update-head-ok`::
274
+ By default `git fetch` refuses to update the head which
275
corresponds to the current branch. This flag disables the
275
- check. This is purely for the internal use for 'git pull'
276
- to communicate with 'git fetch', and unless you are
276
+ check. This is purely for the internal use for `git pull`
277
+ to communicate with `git fetch`, and unless you are
278
implementing your own Porcelain you are not supposed to
279
use it.
280
endif::git-pull[]
281
281
---upload-pack <upload-pack>::
282
+`--upload-pack <upload-pack>`::
283
When given, and the repository to fetch from is handled
283
- by 'git fetch-pack', `--exec=<upload-pack>` is passed to
284
+ by `git fetch-pack`, `--exec=<upload-pack>` is passed to
285
the command to specify non-default path for the command
286
run on the other end.
287
288
ifndef::git-pull[]
288
--q::
289
---quiet::
290
- Pass --quiet to git-fetch-pack and silence any other internally
289
+`-q`::
290
+`--quiet`::
291
+ Pass `--quiet` to `git-fetch-pack` and silence any other internally
292
used git commands. Progress is not reported to the standard error
293
stream.
294
294
--v::
295
---verbose::
295
+`-v`::
296
+`--verbose`::
297
Be verbose.
298
endif::git-pull[]
299
299
---progress::
300
+`--progress`::
301
Progress status is reported on the standard error stream
301
- by default when it is attached to a terminal, unless -q
302
+ by default when it is attached to a terminal, unless `-q`
303
is specified. This flag forces progress status even if the
304
standard error stream is not directed to a terminal.
305
305
--o <option>::
306
---server-option=<option>::
306
+`-o <option>`::
307
+`--server-option=<option>`::
308
Transmit the given string to the server when communicating using
309
protocol version 2. The given string must not contain a NUL or LF
310
character. The server's handling of server options, including
@@ -314,23 +315,23 @@ endif::git-pull[]
315
the values of configuration variable `remote.<name>.serverOption`
316
are used instead.
317
317
---show-forced-updates::
318
+`--show-forced-updates`::
319
By default, git checks if a branch is force-updated during
319
- fetch. This can be disabled through fetch.showForcedUpdates, but
320
- the --show-forced-updates option guarantees this check occurs.
320
+ fetch. This can be disabled through `fetch.showForcedUpdates`, but
321
+ the `--show-forced-updates` option guarantees this check occurs.
322
See linkgit:git-config[1].
323
323
---no-show-forced-updates::
324
+`--no-show-forced-updates`::
325
By default, git checks if a branch is force-updated during
325
- fetch. Pass --no-show-forced-updates or set fetch.showForcedUpdates
326
+ fetch. Pass `--no-show-forced-updates` or set `fetch.showForcedUpdates`
327
to false to skip this check for performance reasons. If used during
327
- 'git-pull' the --ff-only option will still check for forced updates
328
+ `git-pull` the `--ff-only` option will still check for forced updates
329
before attempting a fast-forward update. See linkgit:git-config[1].
330
330
--4::
331
---ipv4::
331
+`-4`::
332
+`--ipv4`::
333
Use IPv4 addresses only, ignoring IPv6 addresses.
334
334
--6::
335
---ipv6::
335
+`-6`::
336
+`--ipv6`::
337
Use IPv6 addresses only, ignoring IPv4 addresses.
Documentation/git-fetch.adoc
+24
-24
@@ -8,11 +8,11 @@ git-fetch - Download objects and refs from another repository
8
9
SYNOPSIS
10
--------
11
-[verse]
12
-'git fetch' [<options>] [<repository> [<refspec>...]]
13
-'git fetch' [<options>] <group>
14
-'git fetch' --multiple [<options>] [(<repository> | <group>)...]
15
-'git fetch' --all [<options>]
11
+[synopsis]
12
+git fetch [<options>] [<repository> [<refspec>...]]
13
+git fetch [<options>] <group>
14
+git fetch --multiple [<options>] [(<repository>|<group>)...]
15
+git fetch --all [<options>]
16
17
18
DESCRIPTION
@@ -20,19 +20,19 @@ DESCRIPTION
20
Fetch branches and/or tags (collectively, "refs") from one or more
21
other repositories, along with the objects necessary to complete their
22
histories. Remote-tracking branches are updated (see the description
23
-of <refspec> below for ways to control this behavior).
23
+of _<refspec>_ below for ways to control this behavior).
24
25
By default, any tag that points into the histories being fetched is
26
also fetched; the effect is to fetch tags that
27
point at branches that you are interested in. This default behavior
28
-can be changed by using the --tags or --no-tags options or by
29
-configuring remote.<name>.tagOpt. By using a refspec that fetches tags
28
+can be changed by using the `--tags` or `--no-tags` options or by
29
+configuring `remote.<name>.tagOpt`. By using a refspec that fetches tags
30
explicitly, you can fetch tags that do not point into branches you
31
are interested in as well.
32
33
-'git fetch' can fetch from either a single named repository or URL,
34
-or from several repositories at once if <group> is given and
35
-there is a remotes.<group> entry in the configuration file.
33
+`git fetch` can fetch from either a single named repository or URL,
34
+or from several repositories at once if _<group>_ is given and
35
+there is a `remotes.<group>` entry in the configuration file.
36
(See linkgit:git-config[1]).
37
38
When no remote is specified, by default the `origin` remote will be used,
@@ -48,15 +48,15 @@ include::fetch-options.adoc[]
48
49
include::pull-fetch-param.adoc[]
50
51
---stdin::
51
+`--stdin`::
52
Read refspecs, one per line, from stdin in addition to those provided
53
- as arguments. The "tag <name>" format is not supported.
53
+ as arguments. The "tag _<name>_" format is not supported.
54
55
include::urls-remotes.adoc[]
56
57
-
58
-CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
59
--------------------------------------------
57
+[[CRTB]]
58
+CONFIGURED REMOTE-TRACKING BRANCHES
59
+-----------------------------------
60
61
You often interact with the same remote repository by
62
regularly and repeatedly fetching from it. In order to keep track
@@ -84,13 +84,13 @@ This configuration is used in two ways:
84
85
* When `git fetch` is run with explicit branches and/or tags
86
to fetch on the command line, e.g. `git fetch origin master`, the
87
- <refspec>s given on the command line determine what are to be
87
+ _<refspec>s_ given on the command line determine what are to be
88
fetched (e.g. `master` in the example,
89
which is a short-hand for `master:`, which in turn means
90
- "fetch the 'master' branch but I do not explicitly say what
90
+ "fetch the `master` branch but I do not explicitly say what
91
remote-tracking branch to update with it from the command line"),
92
and the example command will
93
- fetch _only_ the 'master' branch. The `remote.<repository>.fetch`
93
+ fetch _only_ the `master` branch. The `remote.<repository>.fetch`
94
values determine which
95
remote-tracking branch, if any, is updated. When used in this
96
way, the `remote.<repository>.fetch` values do not have any
@@ -144,9 +144,9 @@ tracking branches that are deleted, but any local tag that doesn't
144
exist on the remote.
145
146
This might not be what you expect, i.e. you want to prune remote
147
-`<name>`, but also explicitly fetch tags from it, so when you fetch
147
+_<name>_, but also explicitly fetch tags from it, so when you fetch
148
from it you delete all your local tags, most of which may not have
149
-come from the `<name>` remote in the first place.
149
+come from the _<name>_ remote in the first place.
150
151
So be careful when using this with a refspec like
152
`refs/tags/*:refs/tags/*`, or any other refspec which might map
@@ -213,11 +213,11 @@ of the form:
213
<flag> <old-object-id> <new-object-id> <local-reference>
214
-------------------------------
215
216
-The status of up-to-date refs is shown only if the --verbose option is
216
+The status of up-to-date refs is shown only if the `--verbose` option is
217
used.
218
219
In compact output mode, specified with configuration variable
220
-fetch.output, if either entire `<from>` or `<to>` is found in the
220
+fetch.output, if either entire _<from>_ or _<to>_ is found in the
221
other string, it will be substituted with `*` in the other string. For
222
example, `master -> origin/master` becomes `master -> origin/*`.
223
@@ -303,7 +303,7 @@ include::config/fetch.adoc[]
303
304
BUGS
305
----
306
-Using --recurse-submodules can only fetch new commits in submodules that are
306
+Using `--recurse-submodules` can only fetch new commits in submodules that are
307
present locally e.g. in `$GIT_DIR/modules/`. If the upstream adds a new
308
submodule, that submodule cannot be fetched until it is cloned e.g. by `git
309
submodule update`. This is expected to be fixed in a future Git version.
Documentation/pull-fetch-param.adoc
+26
-26
@@ -1,20 +1,20 @@
1
-<repository>::
1
+_<repository>_::
2
The "remote" repository that is the source of a fetch
3
or pull operation. This parameter can be either a URL
4
(see the section <<URLS,GIT URLS>> below) or the name
5
of a remote (see the section <<REMOTES,REMOTES>> below).
6
7
ifndef::git-pull[]
8
-<group>::
8
+_<group>_::
9
A name referring to a list of repositories as the value
10
- of remotes.<group> in the configuration file.
10
+ of `remotes.<group>` in the configuration file.
11
(See linkgit:git-config[1]).
12
endif::git-pull[]
13
14
[[fetch-refspec]]
15
-<refspec>::
15
+_<refspec>_::
16
Specifies which refs to fetch and which local refs to update.
17
- When no <refspec>s appear on the command line, the refs to fetch
17
+ When no __<refspec>__s appear on the command line, the refs to fetch
18
are read from `remote.<repository>.fetch` variables instead
19
ifndef::git-pull[]
20
(see <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> below).
@@ -24,18 +24,18 @@ ifdef::git-pull[]
24
in linkgit:git-fetch[1]).
25
endif::git-pull[]
26
+
27
-The format of a <refspec> parameter is an optional plus
28
-`+`, followed by the source <src>, followed
29
-by a colon `:`, followed by the destination <dst>.
30
-The colon can be omitted when <dst> is empty. <src> is
27
+The format of a _<refspec>_ parameter is an optional plus
28
+`+`, followed by the source _<src>_, followed
29
+by a colon `:`, followed by the destination _<dst>_.
30
+The colon can be omitted when _<dst>_ is empty. _<src>_ is
31
typically a ref, or a glob pattern with a single `*` that is used
32
to match a set of refs, but it can also be a fully spelled hex object
33
name.
34
+
35
-A <refspec> may contain a `*` in its <src> to indicate a simple pattern
35
+A _<refspec>_ may contain a `*` in its _<src>_ to indicate a simple pattern
36
match. Such a refspec functions like a glob that matches any ref with the
37
-pattern. A pattern <refspec> must have one and only one `*` in both the <src> and
38
-<dst>. It will map refs to the destination by replacing the `*` with the
37
+pattern. A pattern _<refspec>_ must have one and only one `*` in both the _<src>_ and
38
+_<dst>_. It will map refs to the destination by replacing the `*` with the
39
contents matched from the source.
40
+
41
If a refspec is prefixed by `^`, it will be interpreted as a negative
@@ -45,14 +45,14 @@ considered to match if it matches at least one positive refspec, and does
45
not match any negative refspec. Negative refspecs can be useful to restrict
46
the scope of a pattern refspec so that it will not include specific refs.
47
Negative refspecs can themselves be pattern refspecs. However, they may only
48
-contain a <src> and do not specify a <dst>. Fully spelled out hex object
48
+contain a _<src>_ and do not specify a _<dst>_. Fully spelled out hex object
49
names are also not supported.
50
+
51
`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`;
52
it requests fetching everything up to the given tag.
53
+
54
-The remote ref that matches <src>
55
-is fetched, and if <dst> is not an empty string, an attempt
54
+The remote ref that matches _<src>_
55
+is fetched, and if _<dst>_ is not an empty string, an attempt
56
is made to update the local ref that matches it.
57
+
58
Whether that update is allowed without `--force` depends on the ref
@@ -60,7 +60,7 @@ namespace it's being fetched to, the type of object being fetched, and
60
whether the update is considered to be a fast-forward. Generally, the
61
same rules apply for fetching as when pushing, see the `<refspec>...`
62
section of linkgit:git-push[1] for what those are. Exceptions to those
63
-rules particular to 'git fetch' are noted below.
63
+rules particular to `git fetch` are noted below.
64
+
65
Until Git version 2.20, and unlike when pushing with
66
linkgit:git-push[1], any updates to `refs/tags/*` would be accepted
@@ -91,7 +91,7 @@ object.
91
When the remote branch you want to fetch is known to
92
be rewound and rebased regularly, it is expected that
93
its new tip will not be a descendant of its previous tip
94
-(as stored in your remote-tracking branch the last time
94
+(as stored in your remote-tracking branch the last time_
95
you fetched). You would want
96
to use the `+` sign to indicate non-fast-forward updates
97
will be needed for such branches. There is no way to
@@ -101,19 +101,19 @@ must know this is the expected usage pattern for a branch.
101
ifdef::git-pull[]
102
+
103
[NOTE]
104
-There is a difference between listing multiple <refspec>
105
-directly on 'git pull' command line and having multiple
104
+There is a difference between listing multiple _<refspec>_
105
+directly on `git pull` command line and having multiple
106
`remote.<repository>.fetch` entries in your configuration
107
-for a <repository> and running a
108
-'git pull' command without any explicit <refspec> parameters.
109
-<refspec>s listed explicitly on the command line are always
107
+for a _<repository>_ and running a
108
+`git pull` command without any explicit _<refspec>_ parameters.
109
+__<refspec>__s listed explicitly on the command line are always
110
merged into the current branch after fetching. In other words,
111
-if you list more than one remote ref, 'git pull' will create
111
+if you list more than one remote ref, `git pull` will create
112
an Octopus merge. On the other hand, if you do not list any
113
-explicit <refspec> parameter on the command line, 'git pull'
114
-will fetch all the <refspec>s it finds in the
113
+explicit _<refspec>_ parameter on the command line, `git pull`
114
+will fetch all the __<refspec>__s it finds in the
115
`remote.<repository>.fetch` configuration and merge
116
-only the first <refspec> found into the current branch.
116
+only the first _<refspec>_ found into the current branch.
117
This is because making an
118
Octopus from remote refs is rarely done, while keeping track
119
of multiple remote heads in one-go by fetching more than one
Documentation/urls-remotes.adoc
+8
-8
@@ -4,7 +4,7 @@ REMOTES[[REMOTES]]
4
------------------
5
6
The name of one of the following can be used instead
7
-of a URL as `<repository>` argument:
7
+of a URL as _<repository>_ argument:
8
9
* a remote in the Git configuration file: `$GIT_DIR/config`,
10
* a file in the `$GIT_DIR/remotes` directory, or
@@ -32,8 +32,8 @@ config file would appear like this:
32
fetch = <refspec>
33
------------
34
35
-The `<pushurl>` is used for pushes only. It is optional and defaults
36
-to `<URL>`. Pushing to a remote affects all defined pushurls or all
35
+The _<pushurl>_ is used for pushes only. It is optional and defaults
36
+to _<URL>_. Pushing to a remote affects all defined pushurls or all
37
defined urls if no pushurls are defined. Fetch, however, will only
38
fetch from the first defined url if multiple urls are defined.
39
@@ -54,8 +54,8 @@ following format:
54
55
------------
56
57
-`Push:` lines are used by 'git push' and
58
-`Pull:` lines are used by 'git pull' and 'git fetch'.
57
+`Push:` lines are used by `git push` and
58
+`Pull:` lines are used by `git pull` and `git fetch`.
59
Multiple `Push:` and `Pull:` lines may
60
be specified for additional branch mappings.
61
@@ -72,12 +72,12 @@ This file should have the following format:
72
<URL>#<head>
73
------------
74
75
-`<URL>` is required; `#<head>` is optional.
75
+_<URL>_ is required; `#<head>` is optional.
76
77
Depending on the operation, git will use one of the following
78
refspecs, if you don't provide one on the command line.
79
-`<branch>` is the name of this file in `$GIT_DIR/branches` and
80
-`<head>` defaults to `master`.
79
+_<branch> is the name of this file in `$GIT_DIR/branches` and
80
+_<head>_ defaults to `master`.
81
82
git fetch uses:
83
builtin/fetch.c
+1
-1
@@ -47,7 +47,7 @@
47
static const char * const builtin_fetch_usage[] = {
48
N_("git fetch [<options>] [<repository> [<refspec>...]]"),
49
N_("git fetch [<options>] <group>"),
50
- N_("git fetch --multiple [<options>] [(<repository> | <group>)...]"),
50
+ N_("git fetch --multiple [<options>] [(<repository>|<group>)...]"),
51
N_("git fetch --all [<options>]"),
52
NULL
53
};