1GIT-PULL(1)                       Git Manual                       GIT-PULL(1)
2
3
4

NAME

6       git-pull - Fetch from and merge with another repository or a local
7       branch
8

SYNOPSIS

10       git pull <options> <repository> <refspec>...
11

DESCRIPTION

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
17       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
21       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
24       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

OPTIONS

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
34       -v, --verbose
35           Pass --verbose to git-fetch and git-merge.
36
37   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
42           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
46       --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
51           With --no-ff Generate a merge commit even if the merge resolved as
52           a fast-forward.
53
54       --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
58           With --no-log do not list one-line descriptions from the actual
59           commits being merged.
60
61       --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
65           With -n or --no-stat do not show a diffstat at the end of the
66           merge.
67
68       --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
77           With --no-squash perform the merge and commit the result. This
78           option can be used to override --squash.
79
80       --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
85       -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
92       -X <option>, --strategy-option=<option>
93           Pass merge strategy specific option through to the merge strategy.
94
95       --summary, --no-summary
96           Synonyms to --stat and --no-stat; these are deprecated and will be
97           removed in the future.
98
99       -q, --quiet
100           Operate quietly.
101
102       -v, --verbose
103           Be verbose.
104
105       --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
112               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
118       --no-rebase
119           Override earlier --rebase.
120
121   Options related to fetching
122       --all
123           Fetch all remotes.
124
125       -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
130       --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
135       -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
141       -k, --keep
142           Keep downloaded pack.
143
144       --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
149       -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
156       -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
163       --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
168       --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
174       <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
180       <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
185           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
190               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
202               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
215               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
231           ·    tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>;
232               it requests fetching everything up to the given tag.
233
234           ·   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

GIT URLS

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
243       Git natively supports ssh, git, http, https, ftp, ftps, and rsync
244       protocols. The following syntaxes may be used with them:
245
246       ·   ssh://[user@]host.xz[:port]/path/to/repo.git/
247
248       ·   git://host.xz[:port]/path/to/repo.git/
249
250       ·   http[s]://host.xz[:port]/path/to/repo.git/
251
252       ·   ftp[s]://host.xz[:port]/path/to/repo.git/
253
254       ·   rsync://host.xz/path/to/repo.git/
255
256       An alternative scp-like syntax may also be used with the ssh protocol:
257
258       ·   [user@]host.xz:path/to/repo.git/
259
260       The ssh and git protocols additionally support ~username expansion:
261
262       ·   ssh://[user@]host.xz[:port]/~[user]/path/to/repo.git/
263
264       ·   git://host.xz[:port]/~[user]/path/to/repo.git/
265
266       ·   [user@]host.xz:/~[user]/path/to/repo.git/
267
268       For local respositories, also supported by git natively, the following
269       syntaxes may be used:
270
271       ·   /path/to/repo.git/
272
273       ·    file:///path/to/repo.git/
274
275       These two syntaxes are mostly equivalent, except when cloning, when the
276       former implies --local option. See git-clone(1) for details.
277
278       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
282       ·   <transport>::<address>
283
284       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
288       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
293                   [url "<actual url base>"]
294                           insteadOf = <other url base>
295
296
297       For example, with this:
298
299                   [url "git://git.host.xz/"]
300                           insteadOf = host.xz:/path/to/
301                           insteadOf = work:
302
303
304       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
308       If you want to rewrite URLs for push only, you can create a
309       configuration section of the form:
310
311                   [url "<actual url base>"]
312                           pushInsteadOf = <other url base>
313
314
315       For example, with this:
316
317                   [url "ssh://example.org/"]
318                           pushInsteadOf = git://example.org/
319
320
321       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

REMOTES

326       The name of one of the following can be used instead of a URL as
327       <repository> argument:
328
329       ·   a remote in the git configuration file: $GIT_DIR/config,
330
331       ·   a file in the $GIT_DIR/remotes directory, or
332
333       ·   a file in the $GIT_DIR/branches directory.
334
335       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
338   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
346                   [remote "<name>"]
347                           url = <url>
348                           pushurl = <pushurl>
349                           push = <refspec>
350                           fetch = <refspec>
351
352
353       The <pushurl> is used for pushes only. It is optional and defaults to
354       <url>.
355
356   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
362                   URL: one of the above URL format
363                   Push: <refspec>
364                   Pull: <refspec>
365
366
367       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
371   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
376                   <url>#<head>
377
378
379       <url> is required; #<head> is optional.
380
381       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
385       git fetch uses:
386
387                   refs/heads/<head>:refs/heads/<branch>
388
389
390       git push uses:
391
392                   HEAD:refs/heads/<head>
393
394

MERGE STRATEGIES

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
401       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
407       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
418           The recursive strategy can take the following options:
419
420           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
426               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
431           theirs
432               This is opposite of ours.
433
434           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
441       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
448       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
456       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

DEFAULT BEHAVIOUR

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
468       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
473       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
481           refs/heads/*:refs/remotes/origin/*
482
483
484       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
489       The rule to determine which remote branch to merge after fetching is a
490       bit involved, in order not to break backward compatibility.
491
492       If explicit refspecs were given on the command line of git pull, they
493       are all merged.
494
495       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
499        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
503        2. If the refspec is a globbing one, nothing is merged.
504
505        3. Otherwise the remote branch of the first refspec is merged.
506

EXAMPLES

508       ·   Update the remote-tracking branches for the repository you cloned
509           from, then merge one of them into your current branch:
510
511               $ git pull, git pull origin
512
513           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
517       ·   Merge into the current branch the remote branch next:
518
519               $ git pull origin next
520
521           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
525               $ git fetch origin
526               $ git merge origin/next
527
528
529       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

SEE ALSO

533       git-fetch(1), git-merge(1), git-config(1)
534

AUTHOR

536       Written by Linus Torvalds <torvalds@osdl.org[1]> and Junio C Hamano
537       <gitster@pobox.com[2]>
538

DOCUMENTATION

540       Documentation by Jon Loeliger, David Greaves, Junio C Hamano and the
541       git-list <git@vger.kernel.org[3]>.
542

GIT

544       Part of the git(1) suite
545

NOTES

547        1. torvalds@osdl.org
548           mailto:torvalds@osdl.org
549
550        2. gitster@pobox.com
551           mailto:gitster@pobox.com
552
553        3. git@vger.kernel.org
554           mailto:git@vger.kernel.org
555
556
557
558Git 1.7.1                         08/16/2017                       GIT-PULL(1)
Impressum