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 Incorporates changes from a remote repository into the current branch.
14 In its default mode, git pull is shorthand for git fetch followed by
15 git merge FETCH_HEAD.
16 More precisely, git pull runs git fetch with the given parameters and
18 calls git merge to merge the retrieved branch heads into the current
19 branch. With --rebase, it runs git rebase instead of git merge.
20 <repository> should be the name of a remote repository as passed to
22 git-fetch(1). <refspec> can name an arbitrary remote ref (for example,
23 the name of a tag) or even a collection of refs with corresponding
24 remote-tracking branches (e.g., refs/heads/*:refs/remotes/origin/*),
25 but usually it is the name of a branch in the remote repository.
26 Default values for <repository> and <branch> are read from the "remote"
28 and "merge" configuration for the current branch as set by git-
29 branch(1) --track.
30 Assume the following history exists and the current branch is "master":
32 A---B---C master on origin
34 /
35 D---E---F---G master
36 Then "git pull" will fetch and replay the changes from the remote
39 master branch since it diverged from the local master (i.e., E) until
40 its current commit (C) on top of master and record the result in a new
41 commit along with the names of the two parent commits and a log message
42 from the user describing the changes.
43 A---B---C remotes/origin/master
45 / \
46 D---E---F---G---H master
47 See git-merge(1) for details, including how conflicts are presented and
50 handled.
51 In git 1.7.0 or later, to cancel a conflicting merge, use git reset
53 --merge. Warning: In older versions of git, running git pull with
54 uncommitted changes is discouraged: while possible, it leaves you in a
55 state that may be hard to back out of in the case of a conflict.
56 If any of the remote changes overlap with local uncommitted changes,
58 the merge will be automatically cancelled and the work tree untouched.
59 It is generally best to get any local changes in working order before
60 pulling or stash them away with git-stash(1).
61
63 Options meant for git pull itself and the underlying git merge must be
64 given before the options meant for git fetch.
65 -q, --quiet
67 This is passed to both underlying git-fetch to squelch reporting of
68 during transfer, and underlying git-merge to squelch output during
69 merging.
70 -v, --verbose
72 Pass --verbose to git-fetch and git-merge.
73 --[no-]recurse-submodules
75 This option controls if new commits of all populated submodules
76 should be fetched too (see git-config(1) and gitmodules(5)). That
77 might be necessary to get the data needed for merging submodule
78 commits, a feature git learned in 1.7.3. Notice that the result of
79 a merge will not be checked out in the submodule, "git submodule
80 update" has to be called afterwards to bring the work tree up to
81 date with the merge result.
82 Options related to merging
84 --commit, --no-commit
85 Perform the merge and commit the result. This option can be used to
86 override --no-commit.
87 With --no-commit perform the merge but pretend the merge failed and
89 do not autocommit, to give the user a chance to inspect and further
90 tweak the merge result before committing.
91 --ff, --no-ff
93 Do not generate a merge commit if the merge resolved as a
94 fast-forward, only update the branch pointer. This is the default
95 behavior of git-merge.
96 With --no-ff Generate a merge commit even if the merge resolved as
98 a fast-forward.
99 --log[=<n>], --no-log
101 In addition to branch names, populate the log message with one-line
102 descriptions from at most <n> actual commits that are being merged.
103 See also git-fmt-merge-msg(1).
104 With --no-log do not list one-line descriptions from the actual
106 commits being merged.
107 --stat, -n, --no-stat
109 Show a diffstat at the end of the merge. The diffstat is also
110 controlled by the configuration option merge.stat.
111 With -n or --no-stat do not show a diffstat at the end of the
113 merge.
114 --squash, --no-squash
116 Produce the working tree and index state as if a real merge
117 happened (except for the merge information), but do not actually
118 make a commit or move the HEAD, nor record $GIT_DIR/MERGE_HEAD to
119 cause the next git commit command to create a merge commit. This
120 allows you to create a single commit on top of the current branch
121 whose effect is the same as merging another branch (or more in case
122 of an octopus).
123 With --no-squash perform the merge and commit the result. This
125 option can be used to override --squash.
126 --ff-only
128 Refuse to merge and exit with a non-zero status unless the current
129 HEAD is already up-to-date or the merge can be resolved as a
130 fast-forward.
131 -s <strategy>, --strategy=<strategy>
133 Use the given merge strategy; can be supplied more than once to
134 specify them in the order they should be tried. If there is no -s
135 option, a built-in list of strategies is used instead (git
136 merge-recursive when merging a single head, git merge-octopus
137 otherwise).
138 -X <option>, --strategy-option=<option>
140 Pass merge strategy specific option through to the merge strategy.
141 --summary, --no-summary
143 Synonyms to --stat and --no-stat; these are deprecated and will be
144 removed in the future.
145 -q, --quiet
147 Operate quietly.
148 -v, --verbose
150 Be verbose.
151 --rebase
153 Rebase the current branch on top of the upstream branch after
154 fetching. If there is a remote-tracking branch corresponding to the
155 upstream branch and the upstream branch was rebased since last
156 fetched, the rebase uses that information to avoid rebasing
157 non-local changes.
158 See branch.<name>.rebase and branch.autosetuprebase in git-
160 config(1) if you want to make git pull always use --rebase instead
161 of merging.
162 Note
164 This is a potentially dangerous mode of operation. It rewrites
165 history, which does not bode well when you published that
166 history already. Do not use this option unless you have read
167 git-rebase(1) carefully.
168 --no-rebase
170 Override earlier --rebase.
171 Options related to fetching
173 --all
174 Fetch all remotes.
175 -a, --append
177 Append ref names and object names of fetched refs to the existing
178 contents of .git/FETCH_HEAD. Without this option old data in
179 .git/FETCH_HEAD will be overwritten.
180 --depth=<depth>
182 Deepen the history of a shallow repository created by git clone
183 with --depth=<depth> option (see git-clone(1)) by the specified
184 number of commits.
185 -f, --force
187 When git fetch is used with <rbranch>:<lbranch> refspec, it refuses
188 to update the local branch <lbranch> unless the remote branch
189 <rbranch> it fetches is a descendant of <lbranch>. This option
190 overrides that check.
191 -k, --keep
193 Keep downloaded pack.
194 --no-tags
196 By default, tags that point at objects that are downloaded from the
197 remote repository are fetched and stored locally. This option
198 disables this automatic tag following. The default behavior for a
199 remote may be specified with the remote.<name>.tagopt setting. See
200 git-config(1).
201 -u, --update-head-ok
203 By default git fetch refuses to update the head which corresponds
204 to the current branch. This flag disables the check. This is purely
205 for the internal use for git pull to communicate with git fetch,
206 and unless you are implementing your own Porcelain you are not
207 supposed to use it.
208 --upload-pack <upload-pack>
210 When given, and the repository to fetch from is handled by git
211 fetch-pack, --exec=<upload-pack> is passed to the command to
212 specify non-default path for the command run on the other end.
213 --progress
215 Progress status is reported on the standard error stream by default
216 when it is attached to a terminal, unless -q is specified. This
217 flag forces progress status even if the standard error stream is
218 not directed to a terminal.
219 <repository>
221 The "remote" repository that is the source of a fetch or pull
222 operation. This parameter can be either a URL (see the section GIT
223 URLS below) or the name of a remote (see the section REMOTES
224 below).
225 <refspec>
227 The format of a <refspec> parameter is an optional plus +, followed
228 by the source ref <src>, followed by a colon :, followed by the
229 destination ref <dst>.
230 The remote ref that matches <src> is fetched, and if <dst> is not
232 empty string, the local ref that matches it is fast-forwarded using
233 <src>. If the optional plus + is used, the local ref is updated
234 even if it does not result in a fast-forward update.
235 Note
237 If the remote branch from which you want to pull is modified in
238 non-linear ways such as being rewound and rebased frequently,
239 then a pull will attempt a merge with an older version of
240 itself, likely conflict, and fail. It is under these conditions
241 that you would want to use the + sign to indicate
242 non-fast-forward updates will be needed. There is currently no
243 easy way to determine or declare that a branch will be made
244 available in a repository with this behavior; the pulling user
245 simply must know this is the expected usage pattern for a
246 branch.
247 Note
249 You never do your own development on branches that appear on
250 the right hand side of a <refspec> colon on Pull: lines; they
251 are to be updated by git fetch. If you intend to do development
252 derived from a remote branch B, have a Pull: line to track it
253 (i.e. Pull: B:remote-B), and have a separate branch my-B to do
254 your development on top of it. The latter is created by git
255 branch my-B remote-B (or its equivalent git checkout -b my-B
256 remote-B). Run git fetch to keep track of the progress of the
257 remote side, and when you see something new on the remote
258 branch, merge it into your development branch with git pull .
259 remote-B, while you are on my-B branch.
260 Note
262 There is a difference between listing multiple <refspec>
263 directly on git pull command line and having multiple Pull:
264 <refspec> lines for a <repository> and running git pull command
265 without any explicit <refspec> parameters. <refspec> listed
266 explicitly on the command line are always merged into the
267 current branch after fetching. In other words, if you list more
268 than one remote refs, you would be making an Octopus. While git
269 pull run without any explicit <refspec> parameter takes default
270 <refspec>s from Pull: lines, it merges only the first <refspec>
271 found into the current branch, after fetching all the remote
272 refs. This is because making an Octopus from remote refs is
273 rarely done, while keeping track of multiple remote heads in
274 one-go by fetching more than one is often useful.
275 Some short-cut notations are also supported.
276 · tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>;
278 it requests fetching everything up to the given tag.
279 · A parameter <ref> without a colon is equivalent to <ref>: when
281 pulling/fetching, so it merges <ref> into the current branch
282 without storing the remote branch anywhere locally
283
285 In general, URLs contain information about the transport protocol, the
286 address of the remote server, and the path to the repository. Depending
287 on the transport protocol, some of this information may be absent.
288 Git natively supports ssh, git, http, https, ftp, ftps, and rsync
290 protocols. The following syntaxes may be used with them:
291 · ssh://[user@]host.xz[:port]/path/to/repo.git/
293 · git://host.xz[:port]/path/to/repo.git/
295 · http[s]://host.xz[:port]/path/to/repo.git/
297 · ftp[s]://host.xz[:port]/path/to/repo.git/
299 · rsync://host.xz/path/to/repo.git/
301 An alternative scp-like syntax may also be used with the ssh protocol:
303 · [user@]host.xz:path/to/repo.git/
305 The ssh and git protocols additionally support ~username expansion:
307 · ssh://[user@]host.xz[:port]/~[user]/path/to/repo.git/
309 · git://host.xz[:port]/~[user]/path/to/repo.git/
311 · [user@]host.xz:/~[user]/path/to/repo.git/
313 For local repositories, also supported by git natively, the following
315 syntaxes may be used:
316 · /path/to/repo.git/
318 · file:///path/to/repo.git/
320 These two syntaxes are mostly equivalent, except when cloning, when the
322 former implies --local option. See git-clone(1) for details.
323 When git doesn’t know how to handle a certain transport protocol, it
325 attempts to use the remote-<transport> remote helper, if one exists. To
326 explicitly request a remote helper, the following syntax may be used:
327 · <transport>::<address>
329 where <address> may be a path, a server and path, or an arbitrary
331 URL-like string recognized by the specific remote helper being invoked.
332 See git-remote-helpers(1) for details.
333 If there are a large number of similarly-named remote repositories and
335 you want to use a different format for them (such that the URLs you use
336 will be rewritten into URLs that work), you can create a configuration
337 section of the form:
338 [url "<actual url base>"]
340 insteadOf = <other url base>
341 For example, with this:
344 [url "git://git.host.xz/"]
346 insteadOf = host.xz:/path/to/
347 insteadOf = work:
348 a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
351 rewritten in any context that takes a URL to be
352 "git://git.host.xz/repo.git".
353 If you want to rewrite URLs for push only, you can create a
355 configuration section of the form:
356 [url "<actual url base>"]
358 pushInsteadOf = <other url base>
359 For example, with this:
362 [url "ssh://example.org/"]
364 pushInsteadOf = git://example.org/
365 a URL like "git://example.org/path/to/repo.git" will be rewritten to
368 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still
369 use the original URL.
370
372 The name of one of the following can be used instead of a URL as
373 <repository> argument:
374 · a remote in the git configuration file: $GIT_DIR/config,
376 · a file in the $GIT_DIR/remotes directory, or
378 · a file in the $GIT_DIR/branches directory.
380 All of these also allow you to omit the refspec from the command line
382 because they each contain a refspec which git will use by default.
383 Named remote in configuration file
385 You can choose to provide the name of a remote which you had previously
386 configured using git-remote(1), git-config(1) or even by a manual edit
387 to the $GIT_DIR/config file. The URL of this remote will be used to
388 access the repository. The refspec of this remote will be used by
389 default when you do not provide a refspec on the command line. The
390 entry in the config file would appear like this:
391 [remote "<name>"]
393 url = <url>
394 pushurl = <pushurl>
395 push = <refspec>
396 fetch = <refspec>
397 The <pushurl> is used for pushes only. It is optional and defaults to
400 <url>.
401 Named file in $GIT_DIR/remotes
403 You can choose to provide the name of a file in $GIT_DIR/remotes. The
404 URL in this file will be used to access the repository. The refspec in
405 this file will be used as default when you do not provide a refspec on
406 the command line. This file should have the following format:
407 URL: one of the above URL format
409 Push: <refspec>
410 Pull: <refspec>
411 Push: lines are used by git push and Pull: lines are used by git pull
414 and git fetch. Multiple Push: and Pull: lines may be specified for
415 additional branch mappings.
416 Named file in $GIT_DIR/branches
418 You can choose to provide the name of a file in $GIT_DIR/branches. The
419 URL in this file will be used to access the repository. This file
420 should have the following format:
421 <url>#<head>
423 <url> is required; #<head> is optional.
426 Depending on the operation, git will use one of the following refspecs,
428 if you don’t provide one on the command line. <branch> is the name of
429 this file in $GIT_DIR/branches and <head> defaults to master.
430 git fetch uses:
432 refs/heads/<head>:refs/heads/<branch>
434 git push uses:
437 HEAD:refs/heads/<head>
439
442 The merge mechanism (git-merge and git-pull commands) allows the
443 backend merge strategies to be chosen with -s option. Some strategies
444 can also take their own options, which can be passed by giving
445 -X<option> arguments to git-merge and/or git-pull.
446 resolve
448 This can only resolve two heads (i.e. the current branch and
449 another branch you pulled from) using a 3-way merge algorithm. It
450 tries to carefully detect criss-cross merge ambiguities and is
451 considered generally safe and fast.
452 recursive
454 This can only resolve two heads using a 3-way merge algorithm. When
455 there is more than one common ancestor that can be used for 3-way
456 merge, it creates a merged tree of the common ancestors and uses
457 that as the reference tree for the 3-way merge. This has been
458 reported to result in fewer merge conflicts without causing
459 mis-merges by tests done on actual merge commits taken from Linux
460 2.6 kernel development history. Additionally this can detect and
461 handle merges involving renames. This is the default merge strategy
462 when pulling or merging one branch.
463 The recursive strategy can take the following options:
465 ours
467 This option forces conflicting hunks to be auto-resolved
468 cleanly by favoring our version. Changes from the other tree
469 that do not conflict with our side are reflected to the merge
470 result.
471 This should not be confused with the ours merge strategy, which
473 does not even look at what the other tree contains at all. It
474 discards everything the other tree did, declaring our history
475 contains all that happened in it.
476 theirs
478 This is opposite of ours.
479 patience
481 With this option, merge-recursive spends a little extra time to
482 avoid mismerges that sometimes occur due to unimportant
483 matching lines (e.g., braces from distinct functions). Use this
484 when the branches to be merged have diverged wildly. See also
485 git-diff(1) --patience.
486 ignore-space-change, ignore-all-space, ignore-space-at-eol
488 Treats lines with the indicated type of whitespace change as
489 unchanged for the sake of a three-way merge. Whitespace changes
490 mixed with other changes to a line are not ignored. See also
491 git-diff(1) -b, -w, and --ignore-space-at-eol.
492 · If their version only introduces whitespace changes to a
494 line, our version is used;
495 · If our version introduces whitespace changes but their
497 version includes a substantial change, their version is
498 used;
499 · Otherwise, the merge proceeds in the usual way.
501 renormalize
503 This runs a virtual check-out and check-in of all three stages
504 of a file when resolving a three-way merge. This option is
505 meant to be used when merging branches with different clean
506 filters or end-of-line normalization rules. See "Merging
507 branches with differing checkin/checkout attributes" in
508 gitattributes(5) for details.
509 no-renormalize
511 Disables the renormalize option. This overrides the
512 merge.renormalize configuration variable.
513 rename-threshold=<n>
515 Controls the similarity threshold used for rename detection.
516 See also git-diff(1) -M.
517 subtree[=<path>]
519 This option is a more advanced form of subtree strategy, where
520 the strategy makes a guess on how two trees must be shifted to
521 match with each other when merging. Instead, the specified path
522 is prefixed (or stripped from the beginning) to make the shape
523 of two trees to match.
524 octopus
526 This resolves cases with more than two heads, but refuses to do a
527 complex merge that needs manual resolution. It is primarily meant
528 to be used for bundling topic branch heads together. This is the
529 default merge strategy when pulling or merging more than one
530 branch.
531 ours
533 This resolves any number of heads, but the resulting tree of the
534 merge is always that of the current branch head, effectively
535 ignoring all changes from all other branches. It is meant to be
536 used to supersede old development history of side branches. Note
537 that this is different from the -Xours option to the recursive
538 merge strategy.
539 subtree
541 This is a modified recursive strategy. When merging trees A and B,
542 if B corresponds to a subtree of A, B is first adjusted to match
543 the tree structure of A, instead of reading the trees at the same
544 level. This adjustment is also done to the common ancestor tree.
545
547 Often people use git pull without giving any parameter. Traditionally,
548 this has been equivalent to saying git pull origin. However, when
549 configuration branch.<name>.remote is present while on branch <name>,
550 that value is used instead of origin.
551 In order to determine what URL to use to fetch from, the value of the
553 configuration remote.<origin>.url is consulted and if there is not any
554 such variable, the value on URL: ` line in `$GIT_DIR/remotes/<origin>
555 file is used.
556 In order to determine what remote branches to fetch (and optionally
558 store in the remote-tracking branches) when the command is run without
559 any refspec parameters on the command line, values of the configuration
560 variable remote.<origin>.fetch are consulted, and if there aren’t any,
561 $GIT_DIR/remotes/<origin> file is consulted and its `Pull: ` lines are
562 used. In addition to the refspec formats described in the OPTIONS
563 section, you can have a globbing refspec that looks like this:
564 refs/heads/*:refs/remotes/origin/*
566 A globbing refspec must have a non-empty RHS (i.e. must store what were
569 fetched in remote-tracking branches), and its LHS and RHS must end with
570 /*. The above specifies that all remote branches are tracked using
571 remote-tracking branches in refs/remotes/origin/ hierarchy under the
572 same name.
573 The rule to determine which remote branch to merge after fetching is a
575 bit involved, in order not to break backward compatibility.
576 If explicit refspecs were given on the command line of git pull, they
578 are all merged.
579 When no refspec was given on the command line, then git pull uses the
581 refspec from the configuration or $GIT_DIR/remotes/<origin>. In such
582 cases, the following rules apply:
583 1. If branch.<name>.merge configuration for the current branch <name>
585 exists, that is the name of the branch at the remote site that is
586 merged.
587 2. If the refspec is a globbing one, nothing is merged.
589 3. Otherwise the remote branch of the first refspec is merged.
591
593 · Update the remote-tracking branches for the repository you cloned
594 from, then merge one of them into your current branch:
595 $ git pull, git pull origin
597 Normally the branch merged in is the HEAD of the remote repository,
599 but the choice is determined by the branch.<name>.remote and
600 branch.<name>.merge options; see git-config(1) for details.
601 · Merge into the current branch the remote branch next:
603 $ git pull origin next
605 This leaves a copy of next temporarily in FETCH_HEAD, but does not
607 update any remote-tracking branches. Using remote-tracking
608 branches, the same can be done by invoking fetch and merge:
609 $ git fetch origin
611 $ git merge origin/next
612 If you tried a pull which resulted in a complex conflicts and would
615 want to start over, you can recover with git reset.
616
618 git-fetch(1), git-merge(1), git-config(1)
619
621 Written by Linus Torvalds <torvalds@osdl.org[1]> and Junio C Hamano
622 <gitster@pobox.com[2]>
623
625 Documentation by Jon Loeliger, David Greaves, Junio C Hamano and the
626 git-list <git@vger.kernel.org[3]>.
627
629 Part of the git(1) suite
630
632 1. torvalds@osdl.org
633 mailto:torvalds@osdl.org
634 2. gitster@pobox.com
636 mailto:gitster@pobox.com
637 3. git@vger.kernel.org
639 mailto:git@vger.kernel.org
640Git 1.7.4.4 04/11/2011 GIT-PULL(1)