pull: allow interactive rebase with --rebase=interactive
[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]
3f8fc184 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,
70the merge will be automatically cancelled and the work tree untouched.
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
JL
88 This option controls if new commits of all populated submodules should
89 be fetched too (see linkgit:git-config[1] and linkgit:gitmodules[5]).
90 That might be necessary to get the data needed for merging submodule
2de9b711 91 commits, a feature Git learned in 1.7.3. Notice that the result of a
7811d960
JL
92 merge will not be checked out in the submodule, "git submodule update"
93 has to be called afterwards to bring the work tree up to date with the
94 merge result.
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::
f5eb87b9 104--rebase[=false|true|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+
129260cb
SS
111When set to preserve, rebase with the `--preserve-merges` option passed
112to `git rebase` so that locally created merge commits will not be flattened.
66713ef3
SH
113+
114When false, merge the current branch into the upstream branch.
11fe3f73 115+
f5eb87b9
JS
116When `interactive`, enable the interactive mode of rebase.
117+
da0005b8 118See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in
c4f4157e 119linkgit:git-config[1] if you want to make `git pull` always use
6cf378f0 120`--rebase` instead of merging.
473d3316 121+
6bfa3c99
JH
122[NOTE]
123This is a potentially _dangerous_ mode of operation.
473d3316
JH
124It rewrites history, which does not bode well when you
125published that history already. Do *not* use this option
126unless you have read linkgit:git-rebase[1] carefully.
cd67e4d4 127
3240240f
SB
128--no-rebase::
129 Override earlier --rebase.
cd67e4d4 130
3f7a9b5a
JA
131Options related to fetching
132~~~~~~~~~~~~~~~~~~~~~~~~~~~
133
a288394e
JS
134include::fetch-options.txt[]
135
136include::pull-fetch-param.txt[]
137
138include::urls-remotes.txt[]
139
140include::merge-strategies.txt[]
141
9e2586ff
JH
142DEFAULT BEHAVIOUR
143-----------------
144
145Often people use `git pull` without giving any parameter.
146Traditionally, this has been equivalent to saying `git pull
147origin`. However, when configuration `branch.<name>.remote` is
148present while on branch `<name>`, that value is used instead of
149`origin`.
150
151In order to determine what URL to use to fetch from, the value
152of the configuration `remote.<origin>.url` is consulted
153and if there is not any such variable, the value on `URL: ` line
154in `$GIT_DIR/remotes/<origin>` file is used.
155
156In order to determine what remote branches to fetch (and
8b3f3f84 157optionally store in the remote-tracking branches) when the command is
9e2586ff
JH
158run without any refspec parameters on the command line, values
159of the configuration variable `remote.<origin>.fetch` are
160consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>`
161file is consulted and its `Pull: ` lines are used.
162In addition to the refspec formats described in the OPTIONS
163section, you can have a globbing refspec that looks like this:
164
165------------
166refs/heads/*:refs/remotes/origin/*
167------------
168
169A globbing refspec must have a non-empty RHS (i.e. must store
8b3f3f84 170what were fetched in remote-tracking branches), and its LHS and RHS
9e2586ff 171must end with `/*`. The above specifies that all remote
8b3f3f84 172branches are tracked using remote-tracking branches in
9e2586ff
JH
173`refs/remotes/origin/` hierarchy under the same name.
174
175The rule to determine which remote branch to merge after
176fetching is a bit involved, in order not to break backward
177compatibility.
178
179If explicit refspecs were given on the command
180line of `git pull`, they are all merged.
181
182When no refspec was given on the command line, then `git pull`
183uses the refspec from the configuration or
184`$GIT_DIR/remotes/<origin>`. In such cases, the following
185rules apply:
186
187. If `branch.<name>.merge` configuration for the current
188 branch `<name>` exists, that is the name of the branch at the
189 remote site that is merged.
190
191. If the refspec is a globbing one, nothing is merged.
192
193. Otherwise the remote branch of the first refspec is merged.
194
195
37465016
JH
196EXAMPLES
197--------
198
921177f5
CC
199* Update the remote-tracking branches for the repository
200 you cloned from, then merge one of them into your
201 current branch:
202+
203------------------------------------------------
204$ git pull, git pull origin
205------------------------------------------------
206+
207Normally the branch merged in is the HEAD of the remote repository,
208but the choice is determined by the branch.<name>.remote and
209branch.<name>.merge options; see linkgit:git-config[1] for details.
210
211* Merge into the current branch the remote branch `next`:
212+
213------------------------------------------------
214$ git pull origin next
215------------------------------------------------
216+
217This leaves a copy of `next` temporarily in FETCH_HEAD, but
d504f697
CB
218does not update any remote-tracking branches. Using remote-tracking
219branches, the same can be done by invoking fetch and merge:
921177f5
CC
220+
221------------------------------------------------
d504f697
CB
222$ git fetch origin
223$ git merge origin/next
921177f5 224------------------------------------------------
bccf5956 225
37465016 226
38ef8a76 227If you tried a pull which resulted in complex conflicts and
0b444cdb 228would want to start over, you can recover with 'git reset'.
3ae854c3
JH
229
230
794a3592
JL
231BUGS
232----
233Using --recurse-submodules can only fetch new commits in already checked
234out submodules right now. When e.g. upstream added a new submodule in the
235just fetched commits of the superproject the submodule itself can not be
236fetched, making it impossible to check out that submodule later without
2de9b711 237having to do a fetch again. This is expected to be fixed in a future Git
794a3592
JL
238version.
239
fdd08979
JH
240SEE ALSO
241--------
5162e697 242linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1]
fdd08979 243
2cf565c5
DG
244GIT
245---
9e1f0a85 246Part of the linkgit:git[1] suite