doc: convert git pull 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
c80a5ebce0e6afe3f9d3f5047f3de524386c40bb
4 files changed
+38
-39
Documentation/fetch-options.adoc
+5
-5
@@ -71,7 +71,7 @@ configuration variables documented in linkgit:git-config[1], and the
71
72
`--negotiate-only`::
73
Do not fetch anything from the server, and instead print the
74
- ancestors of the provided `--negotiation-tip=*` arguments,
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)`.
@@ -126,7 +126,7 @@ ifndef::git-pull[]
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.)
129
+ repository maintenance if needed.
130
This is enabled by default.
131
132
`--write-commit-graph`::
@@ -193,7 +193,7 @@ endif::git-pull[]
193
specified refspec (can be given more than once) to map the
194
refs to remote-tracking branches, instead of the values of
195
`remote.<name>.fetch` configuration variables for the remote
196
- repository. Providing an empty `<refspec>` to the
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
@@ -204,7 +204,7 @@ endif::git-pull[]
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
207
- option alone does not subject tags to pruning, even if --prune
207
+ option alone does not subject tags to pruning, even if `--prune`
208
is used (though tags may be pruned anyway if they are also the
209
destination of an explicit refspec; see `--prune`).
210
@@ -306,7 +306,7 @@ endif::git-pull[]
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
309
+ protocol version 2. The given string must not contain a _NUL_ or _LF_
310
character. The server's handling of server options, including
311
unknown ones, is server-specific.
312
When multiple `--server-option=<option>` are given, they are all
Documentation/git-pull.adoc
+30
-31
@@ -8,8 +8,8 @@ git-pull - Fetch from and integrate with another repository or a local branch
8
9
SYNOPSIS
10
--------
11
-[verse]
12
-'git pull' [<options>] [<repository> [<refspec>...]]
11
+[synopsis]
12
+git pull [<options>] [<repository> [<refspec>...]]
13
14
15
DESCRIPTION
@@ -43,7 +43,7 @@ want to handle, you can safely abort it with `git merge --abort` or `git
43
OPTIONS
44
-------
45
46
-<repository>::
46
+_<repository>_::
47
The "remote" repository to pull from. This can be either
48
a URL (see the section <<URLS,GIT URLS>> below) or the name
49
of a remote (see the section <<REMOTES,REMOTES>> below).
@@ -52,29 +52,29 @@ Defaults to the configured upstream for the current branch, or `origin`.
52
See <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> below for more on how to
53
configure upstreams.
54
55
-<refspec>::
55
+_<refspec>_::
56
Which branch or other reference(s) to fetch and integrate into the
57
current branch, for example `main` in `git pull origin main`.
58
Defaults to the configured upstream for the current branch.
59
+
60
This can be a branch, tag, or other collection of reference(s).
61
-See <<fetch-refspec,<refspec>>> below under "Options related to fetching"
61
+See <<fetch-refspec,_<refspec>_>> below under "Options related to fetching"
62
for the full syntax, and <<DEFAULT-BEHAVIOUR,DEFAULT BEHAVIOUR>> below
63
for how `git pull` uses this argument to determine which remote branch
64
to integrate.
65
66
--q::
67
---quiet::
66
+`-q`::
67
+`--quiet`::
68
This is passed to both underlying git-fetch to squelch reporting of
69
during transfer, and underlying git-merge to squelch output during
70
merging.
71
72
--v::
73
---verbose::
74
- Pass --verbose to git-fetch and git-merge.
72
+`-v`::
73
+`--verbose`::
74
+ Pass `--verbose` to git-fetch and git-merge.
75
76
---recurse-submodules[=(yes|on-demand|no)]::
77
---no-recurse-submodules::
76
+`--recurse-submodules[=(yes|on-demand|no)]`::
77
+`--no-recurse-submodules`::
78
This option controls if new commits of populated submodules should
79
be fetched, and if the working trees of active submodules should be
80
updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and
@@ -91,21 +91,20 @@ Options related to merging
91
92
include::merge-options.adoc[]
93
94
--r::
95
---rebase[=(false|true|merges|interactive)]::
96
- When true, rebase the current branch on top of the upstream
94
+`-r`::
95
+`--rebase[=(true|merges|false|interactive)]`::
96
+`true`;; rebase the current branch on top of the upstream
97
branch after fetching. If there is a remote-tracking branch
98
corresponding to the upstream branch and the upstream branch
99
was rebased since last fetched, the rebase uses that information
100
- to avoid rebasing non-local changes.
101
-+
102
-When set to `merges`, rebase using `git rebase --rebase-merges` so that
100
+ to avoid rebasing non-local changes. This is the default.
101
+
102
+`merges`;; rebase using `git rebase --rebase-merges` so that
103
the local merge commits are included in the rebase (see
104
linkgit:git-rebase[1] for details).
105
-+
106
-When false, merge the upstream branch into the current branch.
107
-+
108
-When `interactive`, enable the interactive mode of rebase.
105
+`false`;; merge the upstream branch into the current branch.
106
+`interactive`;; enable the interactive mode of rebase.
107
+
108
+
109
See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in
110
linkgit:git-config[1] if you want to make `git pull` always use
@@ -117,8 +116,8 @@ It rewrites history, which does not bode well when you
116
published that history already. Do *not* use this option
117
unless you have read linkgit:git-rebase[1] carefully.
118
120
---no-rebase::
121
- This is shorthand for --rebase=false.
119
+`--no-rebase`::
120
+ This is shorthand for `--rebase=false`.
121
122
Options related to fetching
123
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -178,7 +177,7 @@ uses the refspec from the configuration or
177
rules apply:
178
179
. If `branch.<name>.merge` configuration for the current
181
- branch `<name>` exists, that is the name of the branch at the
180
+ branch _<name>_ exists, that is the name of the branch at the
181
remote site that is merged.
182
183
. If the refspec is a globbing one, nothing is merged.
@@ -198,9 +197,9 @@ $ git pull
197
$ git pull origin
198
------------------------------------------------
199
+
201
-Normally the branch merged in is the HEAD of the remote repository,
202
-but the choice is determined by the branch.<name>.remote and
203
-branch.<name>.merge options; see linkgit:git-config[1] for details.
200
+Normally the branch merged in is the `HEAD` of the remote repository,
201
+but the choice is determined by the `branch.<name>.remote` and
202
+`branch.<name>.merge` options; see linkgit:git-config[1] for details.
203
204
* Merge into the current branch the remote branch `next`:
205
+
@@ -208,7 +207,7 @@ branch.<name>.merge options; see linkgit:git-config[1] for details.
207
$ git pull origin next
208
------------------------------------------------
209
+
211
-This leaves a copy of `next` temporarily in FETCH_HEAD, and
210
+This leaves a copy of `next` temporarily in `FETCH_HEAD`, and
211
updates the remote-tracking branch `origin/next`.
212
The same can be done by invoking fetch and merge:
213
+
@@ -219,14 +218,14 @@ $ git merge origin/next
218
219
220
If you tried a pull which resulted in complex conflicts and
222
-would want to start over, you can recover with 'git reset'.
221
+would want to start over, you can recover with `git reset`.
222
223
224
include::transfer-data-leaks.adoc[]
225
226
BUGS
227
----
229
-Using --recurse-submodules can only fetch new commits in already checked
228
+Using `--recurse-submodules` can only fetch new commits in already checked
229
out submodules right now. When e.g. upstream added a new submodule in the
230
just fetched commits of the superproject the submodule itself cannot be
231
fetched, making it impossible to check out that submodule later without
Documentation/merge-options.adoc
+1
-1
@@ -56,7 +56,7 @@ ifdef::git-pull[]
56
`--ff-only`::
57
Only update to the new history if there is no divergent local
58
history. This is the default when no method for reconciling
59
- divergent histories is provided (via the --rebase=* flags).
59
+ divergent histories is provided (via the `--rebase` flags).
60
61
`--ff`::
62
`--no-ff`::
Documentation/urls-remotes.adoc
+2
-2
@@ -76,7 +76,7 @@ _<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
79
+_<branch>_ is the name of this file in `$GIT_DIR/branches` and
80
_<head>_ defaults to `master`.
81
82
git fetch uses:
@@ -111,7 +111,7 @@ Git defaults to using the upstream branch for remote operations, for example:
111
'origin/main' have diverged, and have 2 and 3 different commits each
112
respectively".
113
114
-The upstream is stored in `.git/config`, in the "remote" and "merge"
114
+The upstream is stored in `.git/config`, in the "`remote`" and "`merge`"
115
fields. For example, if `main`'s upstream is `origin/main`:
116
117
------------