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
14 Incorporates changes from a remote repository into the current branch.
15 In its default mode, git pull is shorthand for git fetch followed by
16 git merge FETCH_HEAD.
17 More precisely, git pull runs git fetch with the given parameters and
19 calls git merge to merge the retrieved branch heads into the current
20 branch. With --rebase, it runs git rebase instead of git merge.
21 <repository> should be the name of a remote repository as passed to
23 git-fetch(1). <refspec> can name an arbitrary remote ref (for example,
24 the name of a tag) or even a collection of refs with corresponding
25 remote-tracking branches (e.g., refs/heads/*:refs/remotes/origin/*),
26 but usually it is the name of a branch in the remote repository.
27 Default values for <repository> and <branch> are read from the "remote"
29 and "merge" configuration for the current branch as set by git-
30 branch(1) --track.
31 Assume the following history exists and the current branch is "master":
33 A---B---C master on origin
35 /
36 D---E---F---G master
37 Then "git pull" will fetch and replay the changes from the remote
40 master branch since it diverged from the local master (i.e., E) until
41 its current commit (C) on top of master and record the result in a new
42 commit along with the names of the two parent commits and a log message
43 from the user describing the changes.
44 A---B---C remotes/origin/master
46 / \
47 D---E---F---G---H master
48 See git-merge(1) for details, including how conflicts are presented and
51 handled.
52 In Git 1.7.0 or later, to cancel a conflicting merge, use git reset
54 --merge. Warning: In older versions of Git, running git pull with
55 uncommitted changes is discouraged: while possible, it leaves you in a
56 state that may be hard to back out of in the case of a conflict.
57 If any of the remote changes overlap with local uncommitted changes,
59 the merge will be automatically cancelled and the work tree untouched.
60 It is generally best to get any local changes in working order before
61 pulling or stash them away with git-stash(1).
62
64 Options meant for git pull itself and the underlying git merge must be
65 given before the options meant for git fetch.
66 -q, --quiet
68 This is passed to both underlying git-fetch to squelch reporting of
69 during transfer, and underlying git-merge to squelch output during
70 merging.
71 -v, --verbose
73 Pass --verbose to git-fetch and git-merge.
74 --[no-]recurse-submodules[=yes|on-demand|no]
76 This option controls if new commits of all populated submodules
77 should be fetched too (see git-config(1) and gitmodules(5)). That
78 might be necessary to get the data needed for merging submodule
79 commits, a feature Git learned in 1.7.3. Notice that the result of
80 a merge will not be checked out in the submodule, "git submodule
81 update" has to be called afterwards to bring the work tree up to
82 date with the merge result.
83 Options related to merging
85 --commit, --no-commit
86 Perform the merge and commit the result. This option can be used to
87 override --no-commit.
88 With --no-commit perform the merge but pretend the merge failed and
90 do not autocommit, to give the user a chance to inspect and further
91 tweak the merge result before committing.
92 --edit, --no-edit
94 Invoke an editor before committing successful mechanical merge to
95 further edit the auto-generated merge message, so that the user can
96 explain and justify the merge. The --no-edit option can be used to
97 accept the auto-generated message (this is generally discouraged).
98 The --edit option is still useful if you are giving a draft message
99 with the -m option from the command line and want to edit it in the
100 editor.
101 Older scripts may depend on the historical behaviour of not
103 allowing the user to edit the merge log message. They will see an
104 editor opened when they run git merge. To make it easier to adjust
105 such scripts to the updated behaviour, the environment variable
106 GIT_MERGE_AUTOEDIT can be set to no at the beginning of them.
107 --ff
109 When the merge resolves as a fast-forward, only update the branch
110 pointer, without creating a merge commit. This is the default
111 behavior.
112 --no-ff
114 Create a merge commit even when the merge resolves as a
115 fast-forward. This is the default behaviour when merging an
116 annotated (and possibly signed) tag.
117 --ff-only
119 Refuse to merge and exit with a non-zero status unless the current
120 HEAD is already up-to-date or the merge can be resolved as a
121 fast-forward.
122 --log[=<n>], --no-log
124 In addition to branch names, populate the log message with one-line
125 descriptions from at most <n> actual commits that are being merged.
126 See also git-fmt-merge-msg(1).
127 With --no-log do not list one-line descriptions from the actual
129 commits being merged.
130 --stat, -n, --no-stat
132 Show a diffstat at the end of the merge. The diffstat is also
133 controlled by the configuration option merge.stat.
134 With -n or --no-stat do not show a diffstat at the end of the
136 merge.
137 --squash, --no-squash
139 Produce the working tree and index state as if a real merge
140 happened (except for the merge information), but do not actually
141 make a commit or move the HEAD, nor record $GIT_DIR/MERGE_HEAD to
142 cause the next git commit command to create a merge commit. This
143 allows you to create a single commit on top of the current branch
144 whose effect is the same as merging another branch (or more in case
145 of an octopus).
146 With --no-squash perform the merge and commit the result. This
148 option can be used to override --squash.
149 -s <strategy>, --strategy=<strategy>
151 Use the given merge strategy; can be supplied more than once to
152 specify them in the order they should be tried. If there is no -s
153 option, a built-in list of strategies is used instead (git
154 merge-recursive when merging a single head, git merge-octopus
155 otherwise).
156 -X <option>, --strategy-option=<option>
158 Pass merge strategy specific option through to the merge strategy.
159 --verify-signatures, --no-verify-signatures
161 Verify that the commits being merged have good and trusted GPG
162 signatures and abort the merge in case they do not.
163 --summary, --no-summary
165 Synonyms to --stat and --no-stat; these are deprecated and will be
166 removed in the future.
167 -q, --quiet
169 Operate quietly. Implies --no-progress.
170 -v, --verbose
172 Be verbose.
173 --progress, --no-progress
175 Turn progress on/off explicitly. If neither is specified, progress
176 is shown if standard error is connected to a terminal. Note that
177 not all merge strategies may support progress reporting.
178 -r, --rebase
180 Rebase the current branch on top of the upstream branch after
181 fetching. If there is a remote-tracking branch corresponding to the
182 upstream branch and the upstream branch was rebased since last
183 fetched, the rebase uses that information to avoid rebasing
184 non-local changes.
185 See pull.rebase, branch.<name>.rebase and branch.autosetuprebase in
187 git-config(1) if you want to make git pull always use --rebase
188 instead of merging.
189 Note
191 This is a potentially dangerous mode of operation. It rewrites
192 history, which does not bode well when you published that
193 history already. Do not use this option unless you have read
194 git-rebase(1) carefully.
195 --no-rebase
197 Override earlier --rebase.
198 Options related to fetching
200 --all
201 Fetch all remotes.
202 -a, --append
204 Append ref names and object names of fetched refs to the existing
205 contents of .git/FETCH_HEAD. Without this option old data in
206 .git/FETCH_HEAD will be overwritten.
207 --depth=<depth>
209 Deepen or shorten the history of a shallow repository created by
210 git clone with --depth=<depth> option (see git-clone(1)) to the
211 specified number of commits from the tip of each remote branch
212 history. Tags for the deepened commits are not fetched.
213 --unshallow
215 Convert a shallow repository to a complete one, removing all the
216 limitations imposed by shallow repositories.
217 -f, --force
219 When git fetch is used with <rbranch>:<lbranch> refspec, it refuses
220 to update the local branch <lbranch> unless the remote branch
221 <rbranch> it fetches is a descendant of <lbranch>. This option
222 overrides that check.
223 -k, --keep
225 Keep downloaded pack.
226 --no-tags
228 By default, tags that point at objects that are downloaded from the
229 remote repository are fetched and stored locally. This option
230 disables this automatic tag following. The default behavior for a
231 remote may be specified with the remote.<name>.tagopt setting. See
232 git-config(1).
233 -u, --update-head-ok
235 By default git fetch refuses to update the head which corresponds
236 to the current branch. This flag disables the check. This is purely
237 for the internal use for git pull to communicate with git fetch,
238 and unless you are implementing your own Porcelain you are not
239 supposed to use it.
240 --upload-pack <upload-pack>
242 When given, and the repository to fetch from is handled by git
243 fetch-pack, --exec=<upload-pack> is passed to the command to
244 specify non-default path for the command run on the other end.
245 --progress
247 Progress status is reported on the standard error stream by default
248 when it is attached to a terminal, unless -q is specified. This
249 flag forces progress status even if the standard error stream is
250 not directed to a terminal.
251 <repository>
253 The "remote" repository that is the source of a fetch or pull
254 operation. This parameter can be either a URL (see the section GIT
255 URLS below) or the name of a remote (see the section REMOTES
256 below).
257 <refspec>
259 The format of a <refspec> parameter is an optional plus +, followed
260 by the source ref <src>, followed by a colon :, followed by the
261 destination ref <dst>.
262 The remote ref that matches <src> is fetched, and if <dst> is not
264 empty string, the local ref that matches it is fast-forwarded using
265 <src>. If the optional plus + is used, the local ref is updated
266 even if it does not result in a fast-forward update.
267 Note
269 If the remote branch from which you want to pull is modified in
270 non-linear ways such as being rewound and rebased frequently,
271 then a pull will attempt a merge with an older version of
272 itself, likely conflict, and fail. It is under these conditions
273 that you would want to use the + sign to indicate
274 non-fast-forward updates will be needed. There is currently no
275 easy way to determine or declare that a branch will be made
276 available in a repository with this behavior; the pulling user
277 simply must know this is the expected usage pattern for a
278 branch.
279 Note
281 You never do your own development on branches that appear on
282 the right hand side of a <refspec> colon on Pull: lines; they
283 are to be updated by git fetch. If you intend to do development
284 derived from a remote branch B, have a Pull: line to track it
285 (i.e. Pull: B:remote-B), and have a separate branch my-B to do
286 your development on top of it. The latter is created by git
287 branch my-B remote-B (or its equivalent git checkout -b my-B
288 remote-B). Run git fetch to keep track of the progress of the
289 remote side, and when you see something new on the remote
290 branch, merge it into your development branch with git pull .
291 remote-B, while you are on my-B branch.
292 Note
294 There is a difference between listing multiple <refspec>
295 directly on git pull command line and having multiple Pull:
296 <refspec> lines for a <repository> and running git pull command
297 without any explicit <refspec> parameters. <refspec> listed
298 explicitly on the command line are always merged into the
299 current branch after fetching. In other words, if you list more
300 than one remote refs, you would be making an Octopus. While git
301 pull run without any explicit <refspec> parameter takes default
302 <refspec>s from Pull: lines, it merges only the first <refspec>
303 found into the current branch, after fetching all the remote
304 refs. This is because making an Octopus from remote refs is
305 rarely done, while keeping track of multiple remote heads in
306 one-go by fetching more than one is often useful.
307 Some short-cut notations are also supported.
308 · tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; it
310 requests fetching everything up to the given tag.
311 · A parameter <ref> without a colon is equivalent to <ref>: when
313 pulling/fetching, so it merges <ref> into the current branch
314 without storing the remote branch anywhere locally
315
317 In general, URLs contain information about the transport protocol, the
318 address of the remote server, and the path to the repository. Depending
319 on the transport protocol, some of this information may be absent.
320 Git supports ssh, git, http, and https protocols (in addition, ftp, and
322 ftps can be used for fetching and rsync can be used for fetching and
323 pushing, but these are inefficient and deprecated; do not use them).
324 The following syntaxes may be used with them:
326 · ssh://[user@]host.xz[:port]/path/to/repo.git/
328 · git://host.xz[:port]/path/to/repo.git/
330 · http[s]://host.xz[:port]/path/to/repo.git/
332 · ftp[s]://host.xz[:port]/path/to/repo.git/
334 · rsync://host.xz/path/to/repo.git/
336 An alternative scp-like syntax may also be used with the ssh protocol:
338 · [user@]host.xz:path/to/repo.git/
340 The ssh and git protocols additionally support ~username expansion:
342 · ssh://[user@]host.xz[:port]/~[user]/path/to/repo.git/
344 · git://host.xz[:port]/~[user]/path/to/repo.git/
346 · [user@]host.xz:/~[user]/path/to/repo.git/
348 For local repositories, also supported by Git natively, the following
350 syntaxes may be used:
351 · /path/to/repo.git/
353 · file:///path/to/repo.git/
355 These two syntaxes are mostly equivalent, except when cloning, when the
357 former implies --local option. See git-clone(1) for details.
358 When Git doesn’t know how to handle a certain transport protocol, it
360 attempts to use the remote-<transport> remote helper, if one exists. To
361 explicitly request a remote helper, the following syntax may be used:
362 · <transport>::<address>
364 where <address> may be a path, a server and path, or an arbitrary
366 URL-like string recognized by the specific remote helper being invoked.
367 See gitremote-helpers(1) for details.
368 If there are a large number of similarly-named remote repositories and
370 you want to use a different format for them (such that the URLs you use
371 will be rewritten into URLs that work), you can create a configuration
372 section of the form:
373 [url "<actual url base>"]
375 insteadOf = <other url base>
376 For example, with this:
379 [url "git://git.host.xz/"]
381 insteadOf = host.xz:/path/to/
382 insteadOf = work:
383 a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
386 rewritten in any context that takes a URL to be
387 "git://git.host.xz/repo.git".
388 If you want to rewrite URLs for push only, you can create a
390 configuration section of the form:
391 [url "<actual url base>"]
393 pushInsteadOf = <other url base>
394 For example, with this:
397 [url "ssh://example.org/"]
399 pushInsteadOf = git://example.org/
400 a URL like "git://example.org/path/to/repo.git" will be rewritten to
403 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still
404 use the original URL.
405
407 The name of one of the following can be used instead of a URL as
408 <repository> argument:
409 · a remote in the Git configuration file: $GIT_DIR/config,
411 · a file in the $GIT_DIR/remotes directory, or
413 · a file in the $GIT_DIR/branches directory.
415 All of these also allow you to omit the refspec from the command line
417 because they each contain a refspec which git will use by default.
418 Named remote in configuration file
420 You can choose to provide the name of a remote which you had previously
421 configured using git-remote(1), git-config(1) or even by a manual edit
422 to the $GIT_DIR/config file. The URL of this remote will be used to
423 access the repository. The refspec of this remote will be used by
424 default when you do not provide a refspec on the command line. The
425 entry in the config file would appear like this:
426 [remote "<name>"]
428 url = <url>
429 pushurl = <pushurl>
430 push = <refspec>
431 fetch = <refspec>
432 The <pushurl> is used for pushes only. It is optional and defaults to
435 <url>.
436 Named file in $GIT_DIR/remotes
438 You can choose to provide the name of a file in $GIT_DIR/remotes. The
439 URL in this file will be used to access the repository. The refspec in
440 this file will be used as default when you do not provide a refspec on
441 the command line. This file should have the following format:
442 URL: one of the above URL format
444 Push: <refspec>
445 Pull: <refspec>
446 Push: lines are used by git push and Pull: lines are used by git pull
449 and git fetch. Multiple Push: and Pull: lines may be specified for
450 additional branch mappings.
451 Named file in $GIT_DIR/branches
453 You can choose to provide the name of a file in $GIT_DIR/branches. The
454 URL in this file will be used to access the repository. This file
455 should have the following format:
456 <url>#<head>
458 <url> is required; #<head> is optional.
461 Depending on the operation, git will use one of the following refspecs,
463 if you don’t provide one on the command line. <branch> is the name of
464 this file in $GIT_DIR/branches and <head> defaults to master.
465 git fetch uses:
467 refs/heads/<head>:refs/heads/<branch>
469 git push uses:
472 HEAD:refs/heads/<head>
474
477 The merge mechanism (git-merge and git-pull commands) allows the
478 backend merge strategies to be chosen with -s option. Some strategies
479 can also take their own options, which can be passed by giving
480 -X<option> arguments to git-merge and/or git-pull.
481 resolve
483 This can only resolve two heads (i.e. the current branch and
484 another branch you pulled from) using a 3-way merge algorithm. It
485 tries to carefully detect criss-cross merge ambiguities and is
486 considered generally safe and fast.
487 recursive
489 This can only resolve two heads using a 3-way merge algorithm. When
490 there is more than one common ancestor that can be used for 3-way
491 merge, it creates a merged tree of the common ancestors and uses
492 that as the reference tree for the 3-way merge. This has been
493 reported to result in fewer merge conflicts without causing
494 mis-merges by tests done on actual merge commits taken from Linux
495 2.6 kernel development history. Additionally this can detect and
496 handle merges involving renames. This is the default merge strategy
497 when pulling or merging one branch.
498 The recursive strategy can take the following options:
500 ours
502 This option forces conflicting hunks to be auto-resolved
503 cleanly by favoring our version. Changes from the other tree
504 that do not conflict with our side are reflected to the merge
505 result. For a binary file, the entire contents are taken from
506 our side.
507 This should not be confused with the ours merge strategy, which
509 does not even look at what the other tree contains at all. It
510 discards everything the other tree did, declaring our history
511 contains all that happened in it.
512 theirs
514 This is the opposite of ours.
515 patience
517 With this option, merge-recursive spends a little extra time to
518 avoid mismerges that sometimes occur due to unimportant
519 matching lines (e.g., braces from distinct functions). Use this
520 when the branches to be merged have diverged wildly. See also
521 git-diff(1)--patience.
522 diff-algorithm=[patience|minimal|histogram|myers]
524 Tells merge-recursive to use a different diff algorithm, which
525 can help avoid mismerges that occur due to unimportant matching
526 lines (such as braces from distinct functions). See also git-
527 diff(1)--diff-algorithm.
528 ignore-space-change, ignore-all-space, ignore-space-at-eol
530 Treats lines with the indicated type of whitespace change as
531 unchanged for the sake of a three-way merge. Whitespace changes
532 mixed with other changes to a line are not ignored. See also
533 git-diff(1)-b, -w, and --ignore-space-at-eol.
534 · If their version only introduces whitespace changes to a
536 line, our version is used;
537 · If our version introduces whitespace changes but their
539 version includes a substantial change, their version is
540 used;
541 · Otherwise, the merge proceeds in the usual way.
543 renormalize
545 This runs a virtual check-out and check-in of all three stages
546 of a file when resolving a three-way merge. This option is
547 meant to be used when merging branches with different clean
548 filters or end-of-line normalization rules. See "Merging
549 branches with differing checkin/checkout attributes" in
550 gitattributes(5) for details.
551 no-renormalize
553 Disables the renormalize option. This overrides the
554 merge.renormalize configuration variable.
555 rename-threshold=<n>
557 Controls the similarity threshold used for rename detection.
558 See also git-diff(1)-M.
559 subtree[=<path>]
561 This option is a more advanced form of subtree strategy, where
562 the strategy makes a guess on how two trees must be shifted to
563 match with each other when merging. Instead, the specified path
564 is prefixed (or stripped from the beginning) to make the shape
565 of two trees to match.
566 octopus
568 This resolves cases with more than two heads, but refuses to do a
569 complex merge that needs manual resolution. It is primarily meant
570 to be used for bundling topic branch heads together. This is the
571 default merge strategy when pulling or merging more than one
572 branch.
573 ours
575 This resolves any number of heads, but the resulting tree of the
576 merge is always that of the current branch head, effectively
577 ignoring all changes from all other branches. It is meant to be
578 used to supersede old development history of side branches. Note
579 that this is different from the -Xours option to the recursive
580 merge strategy.
581 subtree
583 This is a modified recursive strategy. When merging trees A and B,
584 if B corresponds to a subtree of A, B is first adjusted to match
585 the tree structure of A, instead of reading the trees at the same
586 level. This adjustment is also done to the common ancestor tree.
587
589 Often people use git pull without giving any parameter. Traditionally,
590 this has been equivalent to saying git pull origin. However, when
591 configuration branch.<name>.remote is present while on branch <name>,
592 that value is used instead of origin.
593 In order to determine what URL to use to fetch from, the value of the
595 configuration remote.<origin>.url is consulted and if there is not any
596 such variable, the value on URL: ` line in `$GIT_DIR/remotes/<origin>
597 file is used.
598 In order to determine what remote branches to fetch (and optionally
600 store in the remote-tracking branches) when the command is run without
601 any refspec parameters on the command line, values of the configuration
602 variable remote.<origin>.fetch are consulted, and if there aren’t any,
603 $GIT_DIR/remotes/<origin> file is consulted and its `Pull: ` lines are
604 used. In addition to the refspec formats described in the OPTIONS
605 section, you can have a globbing refspec that looks like this:
606 refs/heads/*:refs/remotes/origin/*
608 A globbing refspec must have a non-empty RHS (i.e. must store what were
611 fetched in remote-tracking branches), and its LHS and RHS must end with
612 /*. The above specifies that all remote branches are tracked using
613 remote-tracking branches in refs/remotes/origin/ hierarchy under the
614 same name.
615 The rule to determine which remote branch to merge after fetching is a
617 bit involved, in order not to break backward compatibility.
618 If explicit refspecs were given on the command line of git pull, they
620 are all merged.
621 When no refspec was given on the command line, then git pull uses the
623 refspec from the configuration or $GIT_DIR/remotes/<origin>. In such
624 cases, the following rules apply:
625 1. If branch.<name>.merge configuration for the current branch <name>
627 exists, that is the name of the branch at the remote site that is
628 merged.
629 2. If the refspec is a globbing one, nothing is merged.
631 3. Otherwise the remote branch of the first refspec is merged.
633
635 · Update the remote-tracking branches for the repository you cloned
636 from, then merge one of them into your current branch:
637 $ git pull, git pull origin
639 Normally the branch merged in is the HEAD of the remote repository,
641 but the choice is determined by the branch.<name>.remote and
642 branch.<name>.merge options; see git-config(1) for details.
643 · Merge into the current branch the remote branch next:
645 $ git pull origin next
647 This leaves a copy of next temporarily in FETCH_HEAD, but does not
649 update any remote-tracking branches. Using remote-tracking
650 branches, the same can be done by invoking fetch and merge:
651 $ git fetch origin
653 $ git merge origin/next
654 If you tried a pull which resulted in complex conflicts and would want
657 to start over, you can recover with git reset.
658
660 Using --recurse-submodules can only fetch new commits in already
661 checked out submodules right now. When e.g. upstream added a new
662 submodule in the just fetched commits of the superproject the submodule
663 itself can not be fetched, making it impossible to check out that
664 submodule later without having to do a fetch again. This is expected to
665 be fixed in a future Git version.
666
668 git-fetch(1), git-merge(1), git-config(1)
669
671 Part of the git(1) suite
672Git 1.8.3.1 11/19/2018 GIT-PULL(1)