]>
Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-pull(1) |
2 | =========== | |
2cf565c5 DG |
3 | |
4 | NAME | |
5 | ---- | |
153d7265 | 6 | git-pull - Fetch from and integrate with another repository or a local branch |
2cf565c5 DG |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
7791a1d9 | 11 | [verse] |
de613050 | 12 | 'git pull' [<options>] [<repository> [<refspec>...]] |
0c04094b | 13 | |
2cf565c5 DG |
14 | |
15 | DESCRIPTION | |
16 | ----------- | |
ab9b3138 | 17 | |
3f8fc184 JN |
18 | Incorporates changes from a remote repository into the current |
19 | branch. In its default mode, `git pull` is shorthand for | |
20 | `git fetch` followed by `git merge FETCH_HEAD`. | |
0c04094b | 21 | |
3f8fc184 JN |
22 | More precisely, 'git pull' runs 'git fetch' with the given |
23 | parameters and calls 'git merge' to merge the retrieved branch | |
24 | heads into the current branch. | |
25 | With `--rebase`, it runs 'git rebase' instead of 'git merge'. | |
93d69d86 | 26 | |
3f8fc184 JN |
27 | <repository> should be the name of a remote repository as |
28 | passed to linkgit:git-fetch[1]. <refspec> can name an | |
29 | arbitrary remote ref (for example, the name of a tag) or even | |
0e615b25 | 30 | a collection of refs with corresponding remote-tracking branches |
3bae8d4d JN |
31 | (e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}), |
32 | but usually it is the name of a branch in the remote repository. | |
3f8fc184 JN |
33 | |
34 | Default values for <repository> and <branch> are read from the | |
35 | "remote" and "merge" configuration for the current branch | |
36 | as set by linkgit:git-branch[1] `--track`. | |
37 | ||
38 | Assume 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 | ||
49 | Then "`git pull`" will fetch and replay the changes from the remote | |
50 | `master` branch since it diverged from the local `master` (i.e., `E`) | |
51 | until its current commit (`C`) on top of `master` and record the | |
52 | result in a new commit along with the names of the two parent commits | |
53 | and 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 | ||
61 | See linkgit:git-merge[1] for details, including how conflicts | |
62 | are presented and handled. | |
63 | ||
2de9b711 TA |
64 | In 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 | 66 | with uncommitted changes is discouraged: while possible, it leaves you |
3f8fc184 JN |
67 | in a state that may be hard to back out of in the case of a conflict. |
68 | ||
69 | If any of the remote changes overlap with local uncommitted changes, | |
d395745d | 70 | the merge will be automatically canceled and the work tree untouched. |
3f8fc184 JN |
71 | It is generally best to get any local changes in working order before |
72 | pulling or stash them away with linkgit:git-stash[1]. | |
e330d8ca | 73 | |
0c04094b JH |
74 | OPTIONS |
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 | + | |
92 | If the checkout is done via rebase, local submodule commits are rebased as well. | |
93 | + | |
94 | If the update is done via merge, the submodule conflicts are resolved and checked out. | |
7811d960 | 95 | |
3f7a9b5a JA |
96 | Options related to merging |
97 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
98 | ||
10eb64f5 | 99 | :git-pull: 1 |
37465016 | 100 | |
d51a4755 JH |
101 | include::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 |
111 | When set to `merges`, rebase using `git rebase --rebase-merges` so that |
112 | the local merge commits are included in the rebase (see | |
113 | linkgit:git-rebase[1] for details). | |
114 | + | |
7401ab92 JS |
115 | When set to `preserve` (deprecated in favor of `merges`), rebase with the |
116 | `--preserve-merges` option passed to `git rebase` so that locally created | |
117 | merge commits will not be flattened. | |
66713ef3 SH |
118 | + |
119 | When false, merge the current branch into the upstream branch. | |
11fe3f73 | 120 | + |
f5eb87b9 JS |
121 | When `interactive`, enable the interactive mode of rebase. |
122 | + | |
da0005b8 | 123 | See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in |
c4f4157e | 124 | linkgit:git-config[1] if you want to make `git pull` always use |
6cf378f0 | 125 | `--rebase` instead of merging. |
473d3316 | 126 | + |
6bfa3c99 JH |
127 | [NOTE] |
128 | This is a potentially _dangerous_ mode of operation. | |
473d3316 JH |
129 | It rewrites history, which does not bode well when you |
130 | published that history already. Do *not* use this option | |
131 | unless 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 | + | |
143 | This option is only valid when "--rebase" is used. | |
144 | ||
3f7a9b5a JA |
145 | Options related to fetching |
146 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
147 | ||
a288394e JS |
148 | include::fetch-options.txt[] |
149 | ||
150 | include::pull-fetch-param.txt[] | |
151 | ||
152 | include::urls-remotes.txt[] | |
153 | ||
154 | include::merge-strategies.txt[] | |
155 | ||
9e2586ff JH |
156 | DEFAULT BEHAVIOUR |
157 | ----------------- | |
158 | ||
159 | Often people use `git pull` without giving any parameter. | |
160 | Traditionally, this has been equivalent to saying `git pull | |
161 | origin`. However, when configuration `branch.<name>.remote` is | |
162 | present while on branch `<name>`, that value is used instead of | |
163 | `origin`. | |
164 | ||
165 | In order to determine what URL to use to fetch from, the value | |
166 | of the configuration `remote.<origin>.url` is consulted | |
0c79cee6 AD |
167 | and if there is not any such variable, the value on the `URL:` line |
168 | in `$GIT_DIR/remotes/<origin>` is used. | |
9e2586ff JH |
169 | |
170 | In order to determine what remote branches to fetch (and | |
8b3f3f84 | 171 | optionally store in the remote-tracking branches) when the command is |
9e2586ff JH |
172 | run without any refspec parameters on the command line, values |
173 | of the configuration variable `remote.<origin>.fetch` are | |
174 | consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>` | |
0c79cee6 | 175 | is consulted and its `Pull:` lines are used. |
9e2586ff JH |
176 | In addition to the refspec formats described in the OPTIONS |
177 | section, you can have a globbing refspec that looks like this: | |
178 | ||
179 | ------------ | |
180 | refs/heads/*:refs/remotes/origin/* | |
181 | ------------ | |
182 | ||
183 | A globbing refspec must have a non-empty RHS (i.e. must store | |
8b3f3f84 | 184 | what were fetched in remote-tracking branches), and its LHS and RHS |
9e2586ff | 185 | must end with `/*`. The above specifies that all remote |
8b3f3f84 | 186 | branches are tracked using remote-tracking branches in |
9e2586ff JH |
187 | `refs/remotes/origin/` hierarchy under the same name. |
188 | ||
189 | The rule to determine which remote branch to merge after | |
190 | fetching is a bit involved, in order not to break backward | |
191 | compatibility. | |
192 | ||
193 | If explicit refspecs were given on the command | |
194 | line of `git pull`, they are all merged. | |
195 | ||
196 | When no refspec was given on the command line, then `git pull` | |
197 | uses the refspec from the configuration or | |
198 | `$GIT_DIR/remotes/<origin>`. In such cases, the following | |
199 | rules 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 |
210 | EXAMPLES |
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 | + | |
222 | Normally the branch merged in is the HEAD of the remote repository, | |
223 | but the choice is determined by the branch.<name>.remote and | |
224 | branch.<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 | + | |
232 | This leaves a copy of `next` temporarily in FETCH_HEAD, but | |
d504f697 CB |
233 | does not update any remote-tracking branches. Using remote-tracking |
234 | branches, 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 | 242 | If you tried a pull which resulted in complex conflicts and |
0b444cdb | 243 | would want to start over, you can recover with 'git reset'. |
3ae854c3 JH |
244 | |
245 | ||
235ec243 MM |
246 | include::transfer-data-leaks.txt[] |
247 | ||
794a3592 JL |
248 | BUGS |
249 | ---- | |
250 | Using --recurse-submodules can only fetch new commits in already checked | |
251 | out submodules right now. When e.g. upstream added a new submodule in the | |
252 | just fetched commits of the superproject the submodule itself can not be | |
253 | fetched, making it impossible to check out that submodule later without | |
2de9b711 | 254 | having to do a fetch again. This is expected to be fixed in a future Git |
794a3592 JL |
255 | version. |
256 | ||
fdd08979 JH |
257 | SEE ALSO |
258 | -------- | |
5162e697 | 259 | linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1] |
fdd08979 | 260 | |
2cf565c5 DG |
261 | GIT |
262 | --- | |
9e1f0a85 | 263 | Part of the linkgit:git[1] suite |