docs: say that `--rebase=preserve` is deprecated
[git/git.git] / Documentation / git-pull.txt
CommitLineData
215a7ad1
JH
1git-pull(1)
2===========
2cf565c5
DG
3
4NAME
5----
153d7265 6git-pull - Fetch from and integrate with another repository or a local branch
2cf565c5
DG
7
8
9SYNOPSIS
10--------
7791a1d9 11[verse]
de613050 12'git pull' [<options>] [<repository> [<refspec>...]]
0c04094b 13
2cf565c5
DG
14
15DESCRIPTION
16-----------
ab9b3138 17
3f8fc184
JN
18Incorporates changes from a remote repository into the current
19branch. In its default mode, `git pull` is shorthand for
20`git fetch` followed by `git merge FETCH_HEAD`.
0c04094b 21
3f8fc184
JN
22More precisely, 'git pull' runs 'git fetch' with the given
23parameters and calls 'git merge' to merge the retrieved branch
24heads into the current branch.
25With `--rebase`, it runs 'git rebase' instead of 'git merge'.
93d69d86 26
3f8fc184
JN
27<repository> should be the name of a remote repository as
28passed to linkgit:git-fetch[1]. <refspec> can name an
29arbitrary remote ref (for example, the name of a tag) or even
0e615b25 30a collection of refs with corresponding remote-tracking branches
3bae8d4d
JN
31(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),
32but usually it is the name of a branch in the remote repository.
3f8fc184
JN
33
34Default values for <repository> and <branch> are read from the
35"remote" and "merge" configuration for the current branch
36as set by linkgit:git-branch[1] `--track`.
37
38Assume the following history exists and the current branch is
39"`master`":
40
41------------
42 A---B---C master on origin
43 /
44 D---E---F---G master
5a3fd6af
JH
45 ^
46 origin/master in your repository
3f8fc184
JN
47------------
48
49Then "`git pull`" will fetch and replay the changes from the remote
50`master` branch since it diverged from the local `master` (i.e., `E`)
51until its current commit (`C`) on top of `master` and record the
52result in a new commit along with the names of the two parent commits
53and a log message from the user describing the changes.
54
55------------
5a3fd6af 56 A---B---C origin/master
3f8fc184
JN
57 / \
58 D---E---F---G---H master
59------------
60
61See linkgit:git-merge[1] for details, including how conflicts
62are presented and handled.
63
2de9b711
TA
64In Git 1.7.0 or later, to cancel a conflicting merge, use
65`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'
e330d8ca 66with uncommitted changes is discouraged: while possible, it leaves you
3f8fc184
JN
67in a state that may be hard to back out of in the case of a conflict.
68
69If any of the remote changes overlap with local uncommitted changes,
d395745d 70the merge will be automatically canceled and the work tree untouched.
3f8fc184
JN
71It is generally best to get any local changes in working order before
72pulling or stash them away with linkgit:git-stash[1].
e330d8ca 73
0c04094b
JH
74OPTIONS
75-------
3f7a9b5a 76
409b8d82
TRC
77-q::
78--quiet::
9839018e
TRC
79 This is passed to both underlying git-fetch to squelch reporting of
80 during transfer, and underlying git-merge to squelch output during
81 merging.
409b8d82
TRC
82
83-v::
84--verbose::
85 Pass --verbose to git-fetch and git-merge.
86
8f0700dd 87--[no-]recurse-submodules[=yes|on-demand|no]::
7811d960 88 This option controls if new commits of all populated submodules should
a6d7eb2c
SB
89 be fetched and updated, too (see linkgit:git-config[1] and
90 linkgit:gitmodules[5]).
91+
92If the checkout is done via rebase, local submodule commits are rebased as well.
93+
94If the update is done via merge, the submodule conflicts are resolved and checked out.
7811d960 95
3f7a9b5a
JA
96Options related to merging
97~~~~~~~~~~~~~~~~~~~~~~~~~~
98
10eb64f5 99:git-pull: 1
37465016 100
d51a4755
JH
101include::merge-options.txt[]
102
d9aa3610 103-r::
1131ec98 104--rebase[=false|true|merges|preserve|interactive]::
66713ef3
SH
105 When true, rebase the current branch on top of the upstream
106 branch after fetching. If there is a remote-tracking branch
107 corresponding to the upstream branch and the upstream branch
108 was rebased since last fetched, the rebase uses that information
109 to avoid rebasing non-local changes.
110+
1131ec98
JS
111When set to `merges`, rebase using `git rebase --rebase-merges` so that
112the local merge commits are included in the rebase (see
113linkgit:git-rebase[1] for details).
114+
7401ab92
JS
115When set to `preserve` (deprecated in favor of `merges`), rebase with the
116`--preserve-merges` option passed to `git rebase` so that locally created
117merge commits will not be flattened.
66713ef3
SH
118+
119When false, merge the current branch into the upstream branch.
11fe3f73 120+
f5eb87b9
JS
121When `interactive`, enable the interactive mode of rebase.
122+
da0005b8 123See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in
c4f4157e 124linkgit:git-config[1] if you want to make `git pull` always use
6cf378f0 125`--rebase` instead of merging.
473d3316 126+
6bfa3c99
JH
127[NOTE]
128This is a potentially _dangerous_ mode of operation.
473d3316
JH
129It rewrites history, which does not bode well when you
130published that history already. Do *not* use this option
131unless you have read linkgit:git-rebase[1] carefully.
cd67e4d4 132
3240240f
SB
133--no-rebase::
134 Override earlier --rebase.
cd67e4d4 135
f66398eb
MJ
136--autostash::
137--no-autostash::
138 Before starting rebase, stash local modifications away (see
e01db917 139 linkgit:git-stash[1]) if needed, and apply the stash entry when
f66398eb
MJ
140 done. `--no-autostash` is useful to override the `rebase.autoStash`
141 configuration variable (see linkgit:git-config[1]).
142+
143This option is only valid when "--rebase" is used.
144
3f7a9b5a
JA
145Options related to fetching
146~~~~~~~~~~~~~~~~~~~~~~~~~~~
147
a288394e
JS
148include::fetch-options.txt[]
149
150include::pull-fetch-param.txt[]
151
152include::urls-remotes.txt[]
153
154include::merge-strategies.txt[]
155
9e2586ff
JH
156DEFAULT BEHAVIOUR
157-----------------
158
159Often people use `git pull` without giving any parameter.
160Traditionally, this has been equivalent to saying `git pull
161origin`. However, when configuration `branch.<name>.remote` is
162present while on branch `<name>`, that value is used instead of
163`origin`.
164
165In order to determine what URL to use to fetch from, the value
166of the configuration `remote.<origin>.url` is consulted
0c79cee6
AD
167and if there is not any such variable, the value on the `URL:` line
168in `$GIT_DIR/remotes/<origin>` is used.
9e2586ff
JH
169
170In order to determine what remote branches to fetch (and
8b3f3f84 171optionally store in the remote-tracking branches) when the command is
9e2586ff
JH
172run without any refspec parameters on the command line, values
173of the configuration variable `remote.<origin>.fetch` are
174consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>`
0c79cee6 175is consulted and its `Pull:` lines are used.
9e2586ff
JH
176In addition to the refspec formats described in the OPTIONS
177section, you can have a globbing refspec that looks like this:
178
179------------
180refs/heads/*:refs/remotes/origin/*
181------------
182
183A globbing refspec must have a non-empty RHS (i.e. must store
8b3f3f84 184what were fetched in remote-tracking branches), and its LHS and RHS
9e2586ff 185must end with `/*`. The above specifies that all remote
8b3f3f84 186branches are tracked using remote-tracking branches in
9e2586ff
JH
187`refs/remotes/origin/` hierarchy under the same name.
188
189The rule to determine which remote branch to merge after
190fetching is a bit involved, in order not to break backward
191compatibility.
192
193If explicit refspecs were given on the command
194line of `git pull`, they are all merged.
195
196When no refspec was given on the command line, then `git pull`
197uses the refspec from the configuration or
198`$GIT_DIR/remotes/<origin>`. In such cases, the following
199rules apply:
200
201. If `branch.<name>.merge` configuration for the current
202 branch `<name>` exists, that is the name of the branch at the
203 remote site that is merged.
204
205. If the refspec is a globbing one, nothing is merged.
206
207. Otherwise the remote branch of the first refspec is merged.
208
209
37465016
JH
210EXAMPLES
211--------
212
921177f5
CC
213* Update the remote-tracking branches for the repository
214 you cloned from, then merge one of them into your
215 current branch:
216+
217------------------------------------------------
d395745d
RG
218$ git pull
219$ git pull origin
921177f5
CC
220------------------------------------------------
221+
222Normally the branch merged in is the HEAD of the remote repository,
223but the choice is determined by the branch.<name>.remote and
224branch.<name>.merge options; see linkgit:git-config[1] for details.
225
226* Merge into the current branch the remote branch `next`:
227+
228------------------------------------------------
229$ git pull origin next
230------------------------------------------------
231+
232This leaves a copy of `next` temporarily in FETCH_HEAD, but
d504f697
CB
233does not update any remote-tracking branches. Using remote-tracking
234branches, the same can be done by invoking fetch and merge:
921177f5
CC
235+
236------------------------------------------------
d504f697
CB
237$ git fetch origin
238$ git merge origin/next
921177f5 239------------------------------------------------
bccf5956 240
37465016 241
38ef8a76 242If you tried a pull which resulted in complex conflicts and
0b444cdb 243would want to start over, you can recover with 'git reset'.
3ae854c3
JH
244
245
235ec243
MM
246include::transfer-data-leaks.txt[]
247
794a3592
JL
248BUGS
249----
250Using --recurse-submodules can only fetch new commits in already checked
251out submodules right now. When e.g. upstream added a new submodule in the
252just fetched commits of the superproject the submodule itself can not be
253fetched, making it impossible to check out that submodule later without
2de9b711 254having to do a fetch again. This is expected to be fixed in a future Git
794a3592
JL
255version.
256
fdd08979
JH
257SEE ALSO
258--------
5162e697 259linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1]
fdd08979 260
2cf565c5
DG
261GIT
262---
9e1f0a85 263Part of the linkgit:git[1] suite