1GIT-PULL(1) Git Manual GIT-PULL(1)
2
6 git-pull - Fetch from and merge with another repository or a local
7 branch
8
10 git pull <options> <repository> <refspec>...
11
13 Runs git fetch with the given parameters, and calls git merge to merge
14 the retrieved head(s) into the current branch. With --rebase, calls git
15 rebase instead of git merge.
16 Note that you can use . (current directory) as the <repository> to pull
18 from the local repository — this is useful when merging local branches
19 into the current branch.
20 Also note that options meant for git pull itself and underlying git
22 merge must be given before the options meant for git fetch.
23 Warning: Running git pull (actually, the underlying git merge) with
25 uncommitted changes is discouraged: while possible, it leaves you in a
26 state that is hard to back out of in the case of a conflict.
27
29 -q, --quiet
30 This is passed to both underlying git-fetch to squelch reporting of
31 during transfer, and underlying git-merge to squelch output during
32 merging.
33 -v, --verbose
35 Pass --verbose to git-fetch and git-merge.
36 Options related to merging
38 --commit, --no-commit
39 Perform the merge and commit the result. This option can be used to
40 override --no-commit.
41 With --no-commit perform the merge but pretend the merge failed and
43 do not autocommit, to give the user a chance to inspect and further
44 tweak the merge result before committing.
45 --ff, --no-ff
47 Do not generate a merge commit if the merge resolved as a
48 fast-forward, only update the branch pointer. This is the default
49 behavior of git-merge.
50 With --no-ff Generate a merge commit even if the merge resolved as
52 a fast-forward.
53 --log, --no-log
55 In addition to branch names, populate the log message with one-line
56 descriptions from the actual commits that are being merged.
57 With --no-log do not list one-line descriptions from the actual
59 commits being merged.
60 --stat, -n, --no-stat
62 Show a diffstat at the end of the merge. The diffstat is also
63 controlled by the configuration option merge.stat.
64 With -n or --no-stat do not show a diffstat at the end of the
66 merge.
67 --squash, --no-squash
69 Produce the working tree and index state as if a real merge
70 happened (except for the merge information), but do not actually
71 make a commit or move the HEAD, nor record $GIT_DIR/MERGE_HEAD to
72 cause the next git commit command to create a merge commit. This
73 allows you to create a single commit on top of the current branch
74 whose effect is the same as merging another branch (or more in case
75 of an octopus).
76 With --no-squash perform the merge and commit the result. This
78 option can be used to override --squash.
79 --ff-only
81 Refuse to merge and exit with a non-zero status unless the current
82 HEAD is already up-to-date or the merge can be resolved as a
83 fast-forward.
84 -s <strategy>, --strategy=<strategy>
86 Use the given merge strategy; can be supplied more than once to
87 specify them in the order they should be tried. If there is no -s
88 option, a built-in list of strategies is used instead (git
89 merge-recursive when merging a single head, git merge-octopus
90 otherwise).
91 -X <option>, --strategy-option=<option>
93 Pass merge strategy specific option through to the merge strategy.
94 --summary, --no-summary
96 Synonyms to --stat and --no-stat; these are deprecated and will be
97 removed in the future.
98 -q, --quiet
100 Operate quietly.
101 -v, --verbose
103 Be verbose.
104 --rebase
106 Instead of a merge, perform a rebase after fetching. If there is a
107 remote ref for the upstream branch, and this branch was rebased
108 since last fetched, the rebase uses that information to avoid
109 rebasing non-local changes. To make this the default for branch
110 <name>, set configuration branch.<name>.rebase to true.
111 Note
113 This is a potentially dangerous mode of operation. It rewrites
114 history, which does not bode well when you published that
115 history already. Do not use this option unless you have read
116 git-rebase(1) carefully.
117 --no-rebase
119 Override earlier --rebase.
120 Options related to fetching
122 --all
123 Fetch all remotes.
124 -a, --append
126 Append ref names and object names of fetched refs to the existing
127 contents of .git/FETCH_HEAD. Without this option old data in
128 .git/FETCH_HEAD will be overwritten.
129 --depth=<depth>
131 Deepen the history of a shallow repository created by git clone
132 with --depth=<depth> option (see git-clone(1)) by the specified
133 number of commits.
134 -f, --force
136 When git fetch is used with <rbranch>:<lbranch> refspec, it refuses
137 to update the local branch <lbranch> unless the remote branch
138 <rbranch> it fetches is a descendant of <lbranch>. This option
139 overrides that check.
140 -k, --keep
142 Keep downloaded pack.
143 --no-tags
145 By default, tags that point at objects that are downloaded from the
146 remote repository are fetched and stored locally. This option
147 disables this automatic tag following.
148 -t, --tags
150 Most of the tags are fetched automatically as branch heads are
151 downloaded, but tags that do not point at objects reachable from
152 the branch heads that are being tracked will not be fetched by this
153 mechanism. This flag lets all tags and their associated objects be
154 downloaded.
155 -u, --update-head-ok
157 By default git fetch refuses to update the head which corresponds
158 to the current branch. This flag disables the check. This is purely
159 for the internal use for git pull to communicate with git fetch,
160 and unless you are implementing your own Porcelain you are not
161 supposed to use it.
162 --upload-pack <upload-pack>
164 When given, and the repository to fetch from is handled by git
165 fetch-pack, --exec=<upload-pack> is passed to the command to
166 specify non-default path for the command run on the other end.
167 --progress
169 Progress status is reported on the standard error stream by default
170 when it is attached to a terminal, unless -q is specified. This
171 flag forces progress status even if the standard error stream is
172 not directed to a terminal.
173 <repository>
175 The "remote" repository that is the source of a fetch or pull
176 operation. This parameter can be either a URL (see the section GIT
177 URLS below) or the name of a remote (see the section REMOTES
178 below).
179 <refspec>
181 The format of a <refspec> parameter is an optional plus +, followed
182 by the source ref <src>, followed by a colon :, followed by the
183 destination ref <dst>.
184 The remote ref that matches <src> is fetched, and if <dst> is not
186 empty string, the local ref that matches it is fast-forwarded using
187 <src>. If the optional plus + is used, the local ref is updated
188 even if it does not result in a fast-forward update.
189 Note
191 If the remote branch from which you want to pull is modified in
192 non-linear ways such as being rewound and rebased frequently,
193 then a pull will attempt a merge with an older version of
194 itself, likely conflict, and fail. It is under these conditions
195 that you would want to use the + sign to indicate
196 non-fast-forward updates will be needed. There is currently no
197 easy way to determine or declare that a branch will be made
198 available in a repository with this behavior; the pulling user
199 simply must know this is the expected usage pattern for a
200 branch.
201 Note
203 You never do your own development on branches that appear on
204 the right hand side of a <refspec> colon on Pull: lines; they
205 are to be updated by git fetch. If you intend to do development
206 derived from a remote branch B, have a Pull: line to track it
207 (i.e. Pull: B:remote-B), and have a separate branch my-B to do
208 your development on top of it. The latter is created by git
209 branch my-B remote-B (or its equivalent git checkout -b my-B
210 remote-B). Run git fetch to keep track of the progress of the
211 remote side, and when you see something new on the remote
212 branch, merge it into your development branch with git pull .
213 remote-B, while you are on my-B branch.
214 Note
216 There is a difference between listing multiple <refspec>
217 directly on git pull command line and having multiple Pull:
218 <refspec> lines for a <repository> and running git pull command
219 without any explicit <refspec> parameters. <refspec> listed
220 explicitly on the command line are always merged into the
221 current branch after fetching. In other words, if you list more
222 than one remote refs, you would be making an Octopus. While git
223 pull run without any explicit <refspec> parameter takes default
224 <refspec>s from Pull: lines, it merges only the first <refspec>
225 found into the current branch, after fetching all the remote
226 refs. This is because making an Octopus from remote refs is
227 rarely done, while keeping track of multiple remote heads in
228 one-go by fetching more than one is often useful.
229 Some short-cut notations are also supported.
230 · tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>;
232 it requests fetching everything up to the given tag.
233 · A parameter <ref> without a colon is equivalent to <ref>: when
235 pulling/fetching, so it merges <ref> into the current branch
236 without storing the remote branch anywhere locally
237
239 In general, URLs contain information about the transport protocol, the
240 address of the remote server, and the path to the repository. Depending
241 on the transport protocol, some of this information may be absent.
242 Git natively supports ssh, git, http, https, ftp, ftps, and rsync
244 protocols. The following syntaxes may be used with them:
245 · ssh://[user@]host.xz[:port]/path/to/repo.git/
247 · git://host.xz[:port]/path/to/repo.git/
249 · http[s]://host.xz[:port]/path/to/repo.git/
251 · ftp[s]://host.xz[:port]/path/to/repo.git/
253 · rsync://host.xz/path/to/repo.git/
255 An alternative scp-like syntax may also be used with the ssh protocol:
257 · [user@]host.xz:path/to/repo.git/
259 The ssh and git protocols additionally support ~username expansion:
261 · ssh://[user@]host.xz[:port]/~[user]/path/to/repo.git/
263 · git://host.xz[:port]/~[user]/path/to/repo.git/
265 · [user@]host.xz:/~[user]/path/to/repo.git/
267 For local respositories, also supported by git natively, the following
269 syntaxes may be used:
270 · /path/to/repo.git/
272 · file:///path/to/repo.git/
274 These two syntaxes are mostly equivalent, except when cloning, when the
276 former implies --local option. See git-clone(1) for details.
277 When git doesn’t know how to handle a certain transport protocol, it
279 attempts to use the remote-<transport> remote helper, if one exists. To
280 explicitly request a remote helper, the following syntax may be used:
281 · <transport>::<address>
283 where <address> may be a path, a server and path, or an arbitrary
285 URL-like string recognized by the specific remote helper being invoked.
286 See git-remote-helpers(1) for details.
287 If there are a large number of similarly-named remote repositories and
289 you want to use a different format for them (such that the URLs you use
290 will be rewritten into URLs that work), you can create a configuration
291 section of the form:
292 [url "<actual url base>"]
294 insteadOf = <other url base>
295 For example, with this:
298 [url "git://git.host.xz/"]
300 insteadOf = host.xz:/path/to/
301 insteadOf = work:
302 a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
305 rewritten in any context that takes a URL to be
306 "git://git.host.xz/repo.git".
307 If you want to rewrite URLs for push only, you can create a
309 configuration section of the form:
310 [url "<actual url base>"]
312 pushInsteadOf = <other url base>
313 For example, with this:
316 [url "ssh://example.org/"]
318 pushInsteadOf = git://example.org/
319 a URL like "git://example.org/path/to/repo.git" will be rewritten to
322 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still
323 use the original URL.
324
326 The name of one of the following can be used instead of a URL as
327 <repository> argument:
328 · a remote in the git configuration file: $GIT_DIR/config,
330 · a file in the $GIT_DIR/remotes directory, or
332 · a file in the $GIT_DIR/branches directory.
334 All of these also allow you to omit the refspec from the command line
336 because they each contain a refspec which git will use by default.
337 Named remote in configuration file
339 You can choose to provide the name of a remote which you had previously
340 configured using git-remote(1), git-config(1) or even by a manual edit
341 to the $GIT_DIR/config file. The URL of this remote will be used to
342 access the repository. The refspec of this remote will be used by
343 default when you do not provide a refspec on the command line. The
344 entry in the config file would appear like this:
345 [remote "<name>"]
347 url = <url>
348 pushurl = <pushurl>
349 push = <refspec>
350 fetch = <refspec>
351 The <pushurl> is used for pushes only. It is optional and defaults to
354 <url>.
355 Named file in $GIT_DIR/remotes
357 You can choose to provide the name of a file in $GIT_DIR/remotes. The
358 URL in this file will be used to access the repository. The refspec in
359 this file will be used as default when you do not provide a refspec on
360 the command line. This file should have the following format:
361 URL: one of the above URL format
363 Push: <refspec>
364 Pull: <refspec>
365 Push: lines are used by git push and Pull: lines are used by git pull
368 and git fetch. Multiple Push: and Pull: lines may be specified for
369 additional branch mappings.
370 Named file in $GIT_DIR/branches
372 You can choose to provide the name of a file in $GIT_DIR/branches. The
373 URL in this file will be used to access the repository. This file
374 should have the following format:
375 <url>#<head>
377 <url> is required; #<head> is optional.
380 Depending on the operation, git will use one of the following refspecs,
382 if you don’t provide one on the command line. <branch> is the name of
383 this file in $GIT_DIR/branches and <head> defaults to master.
384 git fetch uses:
386 refs/heads/<head>:refs/heads/<branch>
388 git push uses:
391 HEAD:refs/heads/<head>
393
396 The merge mechanism (git-merge and git-pull commands) allows the
397 backend merge strategies to be chosen with -s option. Some strategies
398 can also take their own options, which can be passed by giving
399 -X<option> arguments to git-merge and/or git-pull.
400 resolve
402 This can only resolve two heads (i.e. the current branch and
403 another branch you pulled from) using a 3-way merge algorithm. It
404 tries to carefully detect criss-cross merge ambiguities and is
405 considered generally safe and fast.
406 recursive
408 This can only resolve two heads using a 3-way merge algorithm. When
409 there is more than one common ancestor that can be used for 3-way
410 merge, it creates a merged tree of the common ancestors and uses
411 that as the reference tree for the 3-way merge. This has been
412 reported to result in fewer merge conflicts without causing
413 mis-merges by tests done on actual merge commits taken from Linux
414 2.6 kernel development history. Additionally this can detect and
415 handle merges involving renames. This is the default merge strategy
416 when pulling or merging one branch.
417 The recursive strategy can take the following options:
419 ours
421 This option forces conflicting hunks to be auto-resolved
422 cleanly by favoring our version. Changes from the other tree
423 that do not conflict with our side are reflected to the merge
424 result.
425 This should not be confused with the ours merge strategy, which
427 does not even look at what the other tree contains at all. It
428 discards everything the other tree did, declaring our history
429 contains all that happened in it.
430 theirs
432 This is opposite of ours.
433 subtree[=path]
435 This option is a more advanced form of subtree strategy, where
436 the strategy makes a guess on how two trees must be shifted to
437 match with each other when merging. Instead, the specified path
438 is prefixed (or stripped from the beginning) to make the shape
439 of two trees to match.
440 octopus
442 This resolves cases with more than two heads, but refuses to do a
443 complex merge that needs manual resolution. It is primarily meant
444 to be used for bundling topic branch heads together. This is the
445 default merge strategy when pulling or merging more than one
446 branch.
447 ours
449 This resolves any number of heads, but the resulting tree of the
450 merge is always that of the current branch head, effectively
451 ignoring all changes from all other branches. It is meant to be
452 used to supersede old development history of side branches. Note
453 that this is different from the -Xours option to the recursive
454 merge strategy.
455 subtree
457 This is a modified recursive strategy. When merging trees A and B,
458 if B corresponds to a subtree of A, B is first adjusted to match
459 the tree structure of A, instead of reading the trees at the same
460 level. This adjustment is also done to the common ancestor tree.
461
463 Often people use git pull without giving any parameter. Traditionally,
464 this has been equivalent to saying git pull origin. However, when
465 configuration branch.<name>.remote is present while on branch <name>,
466 that value is used instead of origin.
467 In order to determine what URL to use to fetch from, the value of the
469 configuration remote.<origin>.url is consulted and if there is not any
470 such variable, the value on URL: ` line in `$GIT_DIR/remotes/<origin>
471 file is used.
472 In order to determine what remote branches to fetch (and optionally
474 store in the tracking branches) when the command is run without any
475 refspec parameters on the command line, values of the configuration
476 variable remote.<origin>.fetch are consulted, and if there aren’t any,
477 $GIT_DIR/remotes/<origin> file is consulted and its `Pull: ` lines are
478 used. In addition to the refspec formats described in the OPTIONS
479 section, you can have a globbing refspec that looks like this:
480 refs/heads/*:refs/remotes/origin/*
482 A globbing refspec must have a non-empty RHS (i.e. must store what were
485 fetched in tracking branches), and its LHS and RHS must end with /*.
486 The above specifies that all remote branches are tracked using tracking
487 branches in refs/remotes/origin/ hierarchy under the same name.
488 The rule to determine which remote branch to merge after fetching is a
490 bit involved, in order not to break backward compatibility.
491 If explicit refspecs were given on the command line of git pull, they
493 are all merged.
494 When no refspec was given on the command line, then git pull uses the
496 refspec from the configuration or $GIT_DIR/remotes/<origin>. In such
497 cases, the following rules apply:
498 1. If branch.<name>.merge configuration for the current branch <name>
500 exists, that is the name of the branch at the remote site that is
501 merged.
502 2. If the refspec is a globbing one, nothing is merged.
504 3. Otherwise the remote branch of the first refspec is merged.
506
508 · Update the remote-tracking branches for the repository you cloned
509 from, then merge one of them into your current branch:
510 $ git pull, git pull origin
512 Normally the branch merged in is the HEAD of the remote repository,
514 but the choice is determined by the branch.<name>.remote and
515 branch.<name>.merge options; see git-config(1) for details.
516 · Merge into the current branch the remote branch next:
518 $ git pull origin next
520 This leaves a copy of next temporarily in FETCH_HEAD, but does not
522 update any remote-tracking branches. Using remote-tracking
523 branches, the same can be done by invoking fetch and merge:
524 $ git fetch origin
526 $ git merge origin/next
527 If you tried a pull which resulted in a complex conflicts and would
530 want to start over, you can recover with git reset.
531
533 git-fetch(1), git-merge(1), git-config(1)
534
536 Written by Linus Torvalds <torvalds@osdl.org[1]> and Junio C Hamano
537 <gitster@pobox.com[2]>
538
540 Documentation by Jon Loeliger, David Greaves, Junio C Hamano and the
541 git-list <git@vger.kernel.org[3]>.
542
544 Part of the git(1) suite
545
547 1. torvalds@osdl.org
548 mailto:torvalds@osdl.org
549 2. gitster@pobox.com
551 mailto:gitster@pobox.com
552 3. git@vger.kernel.org
554 mailto:git@vger.kernel.org
555Git 1.7.1 08/16/2017 GIT-PULL(1)