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

NAME

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

SYNOPSIS

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

DESCRIPTION

13       Incorporates changes from a remote repository into the current branch.
14       If the current branch is behind the remote, then by default it will
15       fast-forward the current branch to match the remote. If the current
16       branch and the remote have diverged, the user needs to specify how to
17       reconcile the divergent branches with --rebase or --no-rebase (or the
18       corresponding configuration option in pull.rebase).
19
20       More precisely, git pull runs git fetch with the given parameters and
21       then depending on configuration options or command line flags, will
22       call either git rebase or git merge to reconcile diverging branches.
23
24       <repository> should be the name of a remote repository as passed to
25       git-fetch(1). <refspec> can name an arbitrary remote ref (for example,
26       the name of a tag) or even a collection of refs with corresponding
27       remote-tracking branches (e.g., refs/heads/*:refs/remotes/origin/*),
28       but usually it is the name of a branch in the remote repository.
29
30       Default values for <repository> and <branch> are read from the "remote"
31       and "merge" configuration for the current branch as set by git-
32       branch(1) --track.
33
34       Assume the following history exists and the current branch is "master":
35
36                     A---B---C master on origin
37                    /
38               D---E---F---G master
39                   ^
40                   origin/master in your repository
41
42       Then "git pull" will fetch and replay the changes from the remote
43       master branch since it diverged from the local master (i.e., E) until
44       its current commit (C) on top of master and record the result in a new
45       commit along with the names of the two parent commits and a log message
46       from the user describing the changes.
47
48                     A---B---C origin/master
49                    /         \
50               D---E---F---G---H master
51
52       See git-merge(1) for details, including how conflicts are presented and
53       handled.
54
55       In Git 1.7.0 or later, to cancel a conflicting merge, use git reset
56       --merge. Warning: In older versions of Git, running git pull with
57       uncommitted changes is discouraged: while possible, it leaves you in a
58       state that may be hard to back out of in the case of a conflict.
59
60       If any of the remote changes overlap with local uncommitted changes,
61       the merge will be automatically canceled and the work tree untouched.
62       It is generally best to get any local changes in working order before
63       pulling or stash them away with git-stash(1).
64

OPTIONS

66       -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
71       -v, --verbose
72           Pass --verbose to git-fetch and git-merge.
73
74       --[no-]recurse-submodules[=yes|on-demand|no]
75           This option controls if new commits of populated submodules should
76           be fetched, and if the working trees of active submodules should be
77           updated, too (see git-fetch(1), git-config(1) and gitmodules(5)).
78
79           If the checkout is done via rebase, local submodule commits are
80           rebased as well.
81
82           If the update is done via merge, the submodule conflicts are
83           resolved and checked out.
84
85   Options related to merging
86       --commit, --no-commit
87           Perform the merge and commit the result. This option can be used to
88           override --no-commit. Only useful when merging.
89
90           With --no-commit perform the merge and stop just before creating a
91           merge commit, to give the user a chance to inspect and further
92           tweak the merge result before committing.
93
94           Note that fast-forward updates do not create a merge commit and
95           therefore there is no way to stop those merges with --no-commit.
96           Thus, if you want to ensure your branch is not changed or updated
97           by the merge command, use --no-ff with --no-commit.
98
99       --edit, -e, --no-edit
100           Invoke an editor before committing successful mechanical merge to
101           further edit the auto-generated merge message, so that the user can
102           explain and justify the merge. The --no-edit option can be used to
103           accept the auto-generated message (this is generally discouraged).
104
105           Older scripts may depend on the historical behaviour of not
106           allowing the user to edit the merge log message. They will see an
107           editor opened when they run git merge. To make it easier to adjust
108           such scripts to the updated behaviour, the environment variable
109           GIT_MERGE_AUTOEDIT can be set to no at the beginning of them.
110
111       --cleanup=<mode>
112           This option determines how the merge message will be cleaned up
113           before committing. See git-commit(1) for more details. In addition,
114           if the <mode> is given a value of scissors, scissors will be
115           appended to MERGE_MSG before being passed on to the commit
116           machinery in the case of a merge conflict.
117
118       --ff-only
119           Only update to the new history if there is no divergent local
120           history. This is the default when no method for reconciling
121           divergent histories is provided (via the --rebase=* flags).
122
123       --ff, --no-ff
124           When merging rather than rebasing, specifies how a merge is handled
125           when the merged-in history is already a descendant of the current
126           history. If merging is requested, --ff is the default unless
127           merging an annotated (and possibly signed) tag that is not stored
128           in its natural place in the refs/tags/ hierarchy, in which case
129           --no-ff is assumed.
130
131           With --ff, when possible resolve the merge as a fast-forward (only
132           update the branch pointer to match the merged branch; do not create
133           a merge commit). When not possible (when the merged-in history is
134           not a descendant of the current history), create a merge commit.
135
136           With --no-ff, create a merge commit in all cases, even when the
137           merge could instead be resolved as a fast-forward.
138
139       -S[<keyid>], --gpg-sign[=<keyid>], --no-gpg-sign
140           GPG-sign the resulting merge commit. The keyid argument is optional
141           and defaults to the committer identity; if specified, it must be
142           stuck to the option without a space.  --no-gpg-sign is useful to
143           countermand both commit.gpgSign configuration variable, and earlier
144           --gpg-sign.
145
146       --log[=<n>], --no-log
147           In addition to branch names, populate the log message with one-line
148           descriptions from at most <n> actual commits that are being merged.
149           See also git-fmt-merge-msg(1). Only useful when merging.
150
151           With --no-log do not list one-line descriptions from the actual
152           commits being merged.
153
154       --signoff, --no-signoff
155           Add a Signed-off-by trailer by the committer at the end of the
156           commit log message. The meaning of a signoff depends on the project
157           to which you’re committing. For example, it may certify that the
158           committer has the rights to submit the work under the project’s
159           license or agrees to some contributor representation, such as a
160           Developer Certificate of Origin. (See
161           http://developercertificate.org for the one used by the Linux
162           kernel and Git projects.) Consult the documentation or leadership
163           of the project to which you’re contributing to understand how the
164           signoffs are used in that project.
165
166           The --no-signoff option can be used to countermand an earlier
167           --signoff option on the command line.
168
169       --stat, -n, --no-stat
170           Show a diffstat at the end of the merge. The diffstat is also
171           controlled by the configuration option merge.stat.
172
173           With -n or --no-stat do not show a diffstat at the end of the
174           merge.
175
176       --squash, --no-squash
177           Produce the working tree and index state as if a real merge
178           happened (except for the merge information), but do not actually
179           make a commit, move the HEAD, or record $GIT_DIR/MERGE_HEAD (to
180           cause the next git commit command to create a merge commit). This
181           allows you to create a single commit on top of the current branch
182           whose effect is the same as merging another branch (or more in case
183           of an octopus).
184
185           With --no-squash perform the merge and commit the result. This
186           option can be used to override --squash.
187
188           With --squash, --commit is not allowed, and will fail.
189
190           Only useful when merging.
191
192       --no-verify
193           This option bypasses the pre-merge and commit-msg hooks. See also
194           githooks(5). Only useful when merging.
195
196       -s <strategy>, --strategy=<strategy>
197           Use the given merge strategy; can be supplied more than once to
198           specify them in the order they should be tried. If there is no -s
199           option, a built-in list of strategies is used instead (recursive
200           when merging a single head, octopus otherwise).
201
202       -X <option>, --strategy-option=<option>
203           Pass merge strategy specific option through to the merge strategy.
204
205       --verify-signatures, --no-verify-signatures
206           Verify that the tip commit of the side branch being merged is
207           signed with a valid key, i.e. a key that has a valid uid: in the
208           default trust model, this means the signing key has been signed by
209           a trusted key. If the tip commit of the side branch is not signed
210           with a valid key, the merge is aborted.
211
212           Only useful when merging.
213
214       --summary, --no-summary
215           Synonyms to --stat and --no-stat; these are deprecated and will be
216           removed in the future.
217
218       --autostash, --no-autostash
219           Automatically create a temporary stash entry before the operation
220           begins, record it in the special ref MERGE_AUTOSTASH and apply it
221           after the operation ends. This means that you can run the operation
222           on a dirty worktree. However, use with care: the final stash
223           application after a successful merge might result in non-trivial
224           conflicts.
225
226       --allow-unrelated-histories
227           By default, git merge command refuses to merge histories that do
228           not share a common ancestor. This option can be used to override
229           this safety when merging histories of two projects that started
230           their lives independently. As that is a very rare occasion, no
231           configuration variable to enable this by default exists and will
232           not be added.
233
234           Only useful when merging.
235
236       -r, --rebase[=false|true|merges|preserve|interactive]
237           When true, rebase the current branch on top of the upstream branch
238           after fetching. If there is a remote-tracking branch corresponding
239           to the upstream branch and the upstream branch was rebased since
240           last fetched, the rebase uses that information to avoid rebasing
241           non-local changes.
242
243           When set to merges, rebase using git rebase --rebase-merges so that
244           the local merge commits are included in the rebase (see git-
245           rebase(1) for details).
246
247           When set to preserve (deprecated in favor of merges), rebase with
248           the --preserve-merges option passed to git rebase so that locally
249           created merge commits will not be flattened.
250
251           When false, merge the upstream branch into the current branch.
252
253           When interactive, enable the interactive mode of rebase.
254
255           See pull.rebase, branch.<name>.rebase and branch.autoSetupRebase in
256           git-config(1) if you want to make git pull always use --rebase
257           instead of merging.
258
259               Note
260               This is a potentially dangerous mode of operation. It rewrites
261               history, which does not bode well when you published that
262               history already. Do not use this option unless you have read
263               git-rebase(1) carefully.
264
265       --no-rebase
266           This is shorthand for --rebase=false.
267
268   Options related to fetching
269       --all
270           Fetch all remotes.
271
272       -a, --append
273           Append ref names and object names of fetched refs to the existing
274           contents of .git/FETCH_HEAD. Without this option old data in
275           .git/FETCH_HEAD will be overwritten.
276
277       --atomic
278           Use an atomic transaction to update local refs. Either all refs are
279           updated, or on error, no refs are updated.
280
281       --depth=<depth>
282           Limit fetching to the specified number of commits from the tip of
283           each remote branch history. If fetching to a shallow repository
284           created by git clone with --depth=<depth> option (see git-
285           clone(1)), deepen or shorten the history to the specified number of
286           commits. Tags for the deepened commits are not fetched.
287
288       --deepen=<depth>
289           Similar to --depth, except it specifies the number of commits from
290           the current shallow boundary instead of from the tip of each remote
291           branch history.
292
293       --shallow-since=<date>
294           Deepen or shorten the history of a shallow repository to include
295           all reachable commits after <date>.
296
297       --shallow-exclude=<revision>
298           Deepen or shorten the history of a shallow repository to exclude
299           commits reachable from a specified remote branch or tag. This
300           option can be specified multiple times.
301
302       --unshallow
303           If the source repository is complete, convert a shallow repository
304           to a complete one, removing all the limitations imposed by shallow
305           repositories.
306
307           If the source repository is shallow, fetch as much as possible so
308           that the current repository has the same history as the source
309           repository.
310
311       --update-shallow
312           By default when fetching from a shallow repository, git fetch
313           refuses refs that require updating .git/shallow. This option
314           updates .git/shallow and accept such refs.
315
316       --negotiation-tip=<commit|glob>
317           By default, Git will report, to the server, commits reachable from
318           all local refs to find common commits in an attempt to reduce the
319           size of the to-be-received packfile. If specified, Git will only
320           report commits reachable from the given tips. This is useful to
321           speed up fetches when the user knows which local ref is likely to
322           have commits in common with the upstream ref being fetched.
323
324           This option may be specified more than once; if so, Git will report
325           commits reachable from any of the given commits.
326
327           The argument to this option may be a glob on ref names, a ref, or
328           the (possibly abbreviated) SHA-1 of a commit. Specifying a glob is
329           equivalent to specifying this option multiple times, one for each
330           matching ref name.
331
332           See also the fetch.negotiationAlgorithm and push.negotiate
333           configuration variables documented in git-config(1), and the
334           --negotiate-only option below.
335
336       --negotiate-only
337           Do not fetch anything from the server, and instead print the
338           ancestors of the provided --negotiation-tip=* arguments, which we
339           have in common with the server.
340
341           Internally this is used to implement the push.negotiate option, see
342           git-config(1).
343
344       --dry-run
345           Show what would be done, without making any changes.
346
347       -f, --force
348           When git fetch is used with <src>:<dst> refspec it may refuse to
349           update the local branch as discussed in the <refspec> part of the
350           git-fetch(1) documentation. This option overrides that check.
351
352       -k, --keep
353           Keep downloaded pack.
354
355       --prefetch
356           Modify the configured refspec to place all refs into the
357           refs/prefetch/ namespace. See the prefetch task in git-
358           maintenance(1).
359
360       -p, --prune
361           Before fetching, remove any remote-tracking references that no
362           longer exist on the remote. Tags are not subject to pruning if they
363           are fetched only because of the default tag auto-following or due
364           to a --tags option. However, if tags are fetched due to an explicit
365           refspec (either on the command line or in the remote configuration,
366           for example if the remote was cloned with the --mirror option),
367           then they are also subject to pruning. Supplying --prune-tags is a
368           shorthand for providing the tag refspec.
369
370       --no-tags
371           By default, tags that point at objects that are downloaded from the
372           remote repository are fetched and stored locally. This option
373           disables this automatic tag following. The default behavior for a
374           remote may be specified with the remote.<name>.tagOpt setting. See
375           git-config(1).
376
377       --refmap=<refspec>
378           When fetching refs listed on the command line, use the specified
379           refspec (can be given more than once) to map the refs to
380           remote-tracking branches, instead of the values of remote.*.fetch
381           configuration variables for the remote repository. Providing an
382           empty <refspec> to the --refmap option causes Git to ignore the
383           configured refspecs and rely entirely on the refspecs supplied as
384           command-line arguments. See section on "Configured Remote-tracking
385           Branches" for details.
386
387       -t, --tags
388           Fetch all tags from the remote (i.e., fetch remote tags refs/tags/*
389           into local tags with the same name), in addition to whatever else
390           would otherwise be fetched. Using this option alone does not
391           subject tags to pruning, even if --prune is used (though tags may
392           be pruned anyway if they are also the destination of an explicit
393           refspec; see --prune).
394
395       -j, --jobs=<n>
396           Number of parallel children to be used for all forms of fetching.
397
398           If the --multiple option was specified, the different remotes will
399           be fetched in parallel. If multiple submodules are fetched, they
400           will be fetched in parallel. To control them independently, use the
401           config settings fetch.parallel and submodule.fetchJobs (see git-
402           config(1)).
403
404           Typically, parallel recursive and multi-remote fetches will be
405           faster. By default fetches are performed sequentially, not in
406           parallel.
407
408       --set-upstream
409           If the remote is fetched successfully, add upstream (tracking)
410           reference, used by argument-less git-pull(1) and other commands.
411           For more information, see branch.<name>.merge and
412           branch.<name>.remote in git-config(1).
413
414       --upload-pack <upload-pack>
415           When given, and the repository to fetch from is handled by git
416           fetch-pack, --exec=<upload-pack> is passed to the command to
417           specify non-default path for the command run on the other end.
418
419       --progress
420           Progress status is reported on the standard error stream by default
421           when it is attached to a terminal, unless -q is specified. This
422           flag forces progress status even if the standard error stream is
423           not directed to a terminal.
424
425       -o <option>, --server-option=<option>
426           Transmit the given string to the server when communicating using
427           protocol version 2. The given string must not contain a NUL or LF
428           character. The server’s handling of server options, including
429           unknown ones, is server-specific. When multiple
430           --server-option=<option> are given, they are all sent to the other
431           side in the order listed on the command line.
432
433       --show-forced-updates
434           By default, git checks if a branch is force-updated during fetch.
435           This can be disabled through fetch.showForcedUpdates, but the
436           --show-forced-updates option guarantees this check occurs. See git-
437           config(1).
438
439       --no-show-forced-updates
440           By default, git checks if a branch is force-updated during fetch.
441           Pass --no-show-forced-updates or set fetch.showForcedUpdates to
442           false to skip this check for performance reasons. If used during
443           git-pull the --ff-only option will still check for forced updates
444           before attempting a fast-forward update. See git-config(1).
445
446       -4, --ipv4
447           Use IPv4 addresses only, ignoring IPv6 addresses.
448
449       -6, --ipv6
450           Use IPv6 addresses only, ignoring IPv4 addresses.
451
452       <repository>
453           The "remote" repository that is the source of a fetch or pull
454           operation. This parameter can be either a URL (see the section GIT
455           URLS below) or the name of a remote (see the section REMOTES
456           below).
457
458       <refspec>
459           Specifies which refs to fetch and which local refs to update. When
460           no <refspec>s appear on the command line, the refs to fetch are
461           read from remote.<repository>.fetch variables instead (see the
462           section "CONFIGURED REMOTE-TRACKING BRANCHES" in git-fetch(1)).
463
464           The format of a <refspec> parameter is an optional plus +, followed
465           by the source <src>, followed by a colon :, followed by the
466           destination ref <dst>. The colon can be omitted when <dst> is
467           empty. <src> is typically a ref, but it can also be a fully spelled
468           hex object name.
469
470           A <refspec> may contain a * in its <src> to indicate a simple
471           pattern match. Such a refspec functions like a glob that matches
472           any ref with the same prefix. A pattern <refspec> must have a * in
473           both the <src> and <dst>. It will map refs to the destination by
474           replacing the * with the contents matched from the source.
475
476           If a refspec is prefixed by ^, it will be interpreted as a negative
477           refspec. Rather than specifying which refs to fetch or which local
478           refs to update, such a refspec will instead specify refs to
479           exclude. A ref will be considered to match if it matches at least
480           one positive refspec, and does not match any negative refspec.
481           Negative refspecs can be useful to restrict the scope of a pattern
482           refspec so that it will not include specific refs. Negative
483           refspecs can themselves be pattern refspecs. However, they may only
484           contain a <src> and do not specify a <dst>. Fully spelled out hex
485           object names are also not supported.
486
487           tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; it
488           requests fetching everything up to the given tag.
489
490           The remote ref that matches <src> is fetched, and if <dst> is not
491           an empty string, an attempt is made to update the local ref that
492           matches it.
493
494           Whether that update is allowed without --force depends on the ref
495           namespace it’s being fetched to, the type of object being fetched,
496           and whether the update is considered to be a fast-forward.
497           Generally, the same rules apply for fetching as when pushing, see
498           the <refspec>...  section of git-push(1) for what those are.
499           Exceptions to those rules particular to git fetch are noted below.
500
501           Until Git version 2.20, and unlike when pushing with git-push(1),
502           any updates to refs/tags/* would be accepted without + in the
503           refspec (or --force). When fetching, we promiscuously considered
504           all tag updates from a remote to be forced fetches. Since Git
505           version 2.20, fetching to update refs/tags/* works the same way as
506           when pushing. I.e. any updates will be rejected without + in the
507           refspec (or --force).
508
509           Unlike when pushing with git-push(1), any updates outside of
510           refs/{tags,heads}/* will be accepted without + in the refspec (or
511           --force), whether that’s swapping e.g. a tree object for a blob, or
512           a commit for another commit that’s doesn’t have the previous commit
513           as an ancestor etc.
514
515           Unlike when pushing with git-push(1), there is no configuration
516           which’ll amend these rules, and nothing like a pre-fetch hook
517           analogous to the pre-receive hook.
518
519           As with pushing with git-push(1), all of the rules described above
520           about what’s not allowed as an update can be overridden by adding
521           an the optional leading + to a refspec (or using --force command
522           line option). The only exception to this is that no amount of
523           forcing will make the refs/heads/* namespace accept a non-commit
524           object.
525
526               Note
527               When the remote branch you want to fetch is known to be rewound
528               and rebased regularly, it is expected that its new tip will not
529               be descendant of its previous tip (as stored in your
530               remote-tracking branch the last time you fetched). You would
531               want to use the + sign to indicate non-fast-forward updates
532               will be needed for such branches. There is no way to determine
533               or declare that a branch will be made available in a repository
534               with this behavior; the pulling user simply must know this is
535               the expected usage pattern for a branch.
536
537               Note
538               There is a difference between listing multiple <refspec>
539               directly on git pull command line and having multiple
540               remote.<repository>.fetch entries in your configuration for a
541               <repository> and running a git pull command without any
542               explicit <refspec> parameters. <refspec>s listed explicitly on
543               the command line are always merged into the current branch
544               after fetching. In other words, if you list more than one
545               remote ref, git pull will create an Octopus merge. On the other
546               hand, if you do not list any explicit <refspec> parameter on
547               the command line, git pull will fetch all the <refspec>s it
548               finds in the remote.<repository>.fetch configuration and merge
549               only the first <refspec> found into the current branch. This is
550               because making an Octopus from remote refs is rarely done,
551               while keeping track of multiple remote heads in one-go by
552               fetching more than one is often useful.
553

GIT URLS

555       In general, URLs contain information about the transport protocol, the
556       address of the remote server, and the path to the repository. Depending
557       on the transport protocol, some of this information may be absent.
558
559       Git supports ssh, git, http, and https protocols (in addition, ftp, and
560       ftps can be used for fetching, but this is inefficient and deprecated;
561       do not use it).
562
563       The native transport (i.e. git:// URL) does no authentication and
564       should be used with caution on unsecured networks.
565
566       The following syntaxes may be used with them:
567
568       •   ssh://[user@]host.xz[:port]/path/to/repo.git/
569
570       •   git://host.xz[:port]/path/to/repo.git/
571
572       •   http[s]://host.xz[:port]/path/to/repo.git/
573
574       •   ftp[s]://host.xz[:port]/path/to/repo.git/
575
576       An alternative scp-like syntax may also be used with the ssh protocol:
577
578       •   [user@]host.xz:path/to/repo.git/
579
580       This syntax is only recognized if there are no slashes before the first
581       colon. This helps differentiate a local path that contains a colon. For
582       example the local path foo:bar could be specified as an absolute path
583       or ./foo:bar to avoid being misinterpreted as an ssh url.
584
585       The ssh and git protocols additionally support ~username expansion:
586
587       •   ssh://[user@]host.xz[:port]/~[user]/path/to/repo.git/
588
589       •   git://host.xz[:port]/~[user]/path/to/repo.git/
590
591       •   [user@]host.xz:/~[user]/path/to/repo.git/
592
593       For local repositories, also supported by Git natively, the following
594       syntaxes may be used:
595
596       •   /path/to/repo.git/
597
598       •   file:///path/to/repo.git/
599
600       These two syntaxes are mostly equivalent, except when cloning, when the
601       former implies --local option. See git-clone(1) for details.
602
603       git clone, git fetch and git pull, but not git push, will also accept a
604       suitable bundle file. See git-bundle(1).
605
606       When Git doesn’t know how to handle a certain transport protocol, it
607       attempts to use the remote-<transport> remote helper, if one exists. To
608       explicitly request a remote helper, the following syntax may be used:
609
610       •   <transport>::<address>
611
612       where <address> may be a path, a server and path, or an arbitrary
613       URL-like string recognized by the specific remote helper being invoked.
614       See gitremote-helpers(7) for details.
615
616       If there are a large number of similarly-named remote repositories and
617       you want to use a different format for them (such that the URLs you use
618       will be rewritten into URLs that work), you can create a configuration
619       section of the form:
620
621                   [url "<actual url base>"]
622                           insteadOf = <other url base>
623
624       For example, with this:
625
626                   [url "git://git.host.xz/"]
627                           insteadOf = host.xz:/path/to/
628                           insteadOf = work:
629
630       a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
631       rewritten in any context that takes a URL to be
632       "git://git.host.xz/repo.git".
633
634       If you want to rewrite URLs for push only, you can create a
635       configuration section of the form:
636
637                   [url "<actual url base>"]
638                           pushInsteadOf = <other url base>
639
640       For example, with this:
641
642                   [url "ssh://example.org/"]
643                           pushInsteadOf = git://example.org/
644
645       a URL like "git://example.org/path/to/repo.git" will be rewritten to
646       "ssh://example.org/path/to/repo.git" for pushes, but pulls will still
647       use the original URL.
648

REMOTES

650       The name of one of the following can be used instead of a URL as
651       <repository> argument:
652
653       •   a remote in the Git configuration file: $GIT_DIR/config,
654
655       •   a file in the $GIT_DIR/remotes directory, or
656
657       •   a file in the $GIT_DIR/branches directory.
658
659       All of these also allow you to omit the refspec from the command line
660       because they each contain a refspec which git will use by default.
661
662   Named remote in configuration file
663       You can choose to provide the name of a remote which you had previously
664       configured using git-remote(1), git-config(1) or even by a manual edit
665       to the $GIT_DIR/config file. The URL of this remote will be used to
666       access the repository. The refspec of this remote will be used by
667       default when you do not provide a refspec on the command line. The
668       entry in the config file would appear like this:
669
670                   [remote "<name>"]
671                           url = <url>
672                           pushurl = <pushurl>
673                           push = <refspec>
674                           fetch = <refspec>
675
676       The <pushurl> is used for pushes only. It is optional and defaults to
677       <url>.
678
679   Named file in $GIT_DIR/remotes
680       You can choose to provide the name of a file in $GIT_DIR/remotes. The
681       URL in this file will be used to access the repository. The refspec in
682       this file will be used as default when you do not provide a refspec on
683       the command line. This file should have the following format:
684
685                   URL: one of the above URL format
686                   Push: <refspec>
687                   Pull: <refspec>
688
689       Push: lines are used by git push and Pull: lines are used by git pull
690       and git fetch. Multiple Push: and Pull: lines may be specified for
691       additional branch mappings.
692
693   Named file in $GIT_DIR/branches
694       You can choose to provide the name of a file in $GIT_DIR/branches. The
695       URL in this file will be used to access the repository. This file
696       should have the following format:
697
698                   <url>#<head>
699
700       <url> is required; #<head> is optional.
701
702       Depending on the operation, git will use one of the following refspecs,
703       if you don’t provide one on the command line. <branch> is the name of
704       this file in $GIT_DIR/branches and <head> defaults to master.
705
706       git fetch uses:
707
708                   refs/heads/<head>:refs/heads/<branch>
709
710       git push uses:
711
712                   HEAD:refs/heads/<head>
713

MERGE STRATEGIES

715       The merge mechanism (git merge and git pull commands) allows the
716       backend merge strategies to be chosen with -s option. Some strategies
717       can also take their own options, which can be passed by giving
718       -X<option> arguments to git merge and/or git pull.
719
720       recursive
721           This can only resolve two heads using a 3-way merge algorithm. When
722           there is more than one common ancestor that can be used for 3-way
723           merge, it creates a merged tree of the common ancestors and uses
724           that as the reference tree for the 3-way merge. This has been
725           reported to result in fewer merge conflicts without causing
726           mismerges by tests done on actual merge commits taken from Linux
727           2.6 kernel development history. Additionally this can detect and
728           handle merges involving renames. It does not make use of detected
729           copies. This is the default merge strategy when pulling or merging
730           one branch.
731
732           The recursive strategy can take the following options:
733
734           ours
735               This option forces conflicting hunks to be auto-resolved
736               cleanly by favoring our version. Changes from the other tree
737               that do not conflict with our side are reflected in the merge
738               result. For a binary file, the entire contents are taken from
739               our side.
740
741               This should not be confused with the ours merge strategy, which
742               does not even look at what the other tree contains at all. It
743               discards everything the other tree did, declaring our history
744               contains all that happened in it.
745
746           theirs
747               This is the opposite of ours; note that, unlike ours, there is
748               no theirs merge strategy to confuse this merge option with.
749
750           patience
751               Deprecated synonym for diff-algorithm=patience.
752
753           diff-algorithm=[patience|minimal|histogram|myers]
754               Use a different diff algorithm while merging, which can help
755               avoid mismerges that occur due to unimportant matching lines
756               (such as braces from distinct functions). See also git-diff(1)
757               --diff-algorithm. Defaults to the diff.algorithm config
758               setting.
759
760           ignore-space-change, ignore-all-space, ignore-space-at-eol,
761           ignore-cr-at-eol
762               Treats lines with the indicated type of whitespace change as
763               unchanged for the sake of a three-way merge. Whitespace changes
764               mixed with other changes to a line are not ignored. See also
765               git-diff(1) -b, -w, --ignore-space-at-eol, and
766               --ignore-cr-at-eol.
767
768               •   If their version only introduces whitespace changes to a
769                   line, our version is used;
770
771               •   If our version introduces whitespace changes but their
772                   version includes a substantial change, their version is
773                   used;
774
775               •   Otherwise, the merge proceeds in the usual way.
776
777           renormalize
778               This runs a virtual check-out and check-in of all three stages
779               of a file when resolving a three-way merge. This option is
780               meant to be used when merging branches with different clean
781               filters or end-of-line normalization rules. See "Merging
782               branches with differing checkin/checkout attributes" in
783               gitattributes(5) for details.
784
785           no-renormalize
786               Disables the renormalize option. This overrides the
787               merge.renormalize configuration variable.
788
789           no-renames
790               Turn off rename detection. This overrides the merge.renames
791               configuration variable. See also git-diff(1) --no-renames.
792
793           find-renames[=<n>]
794               Turn on rename detection, optionally setting the similarity
795               threshold. This is the default. This overrides the
796               merge.renames configuration variable. See also git-diff(1)
797               --find-renames.
798
799           rename-threshold=<n>
800               Deprecated synonym for find-renames=<n>.
801
802           subtree[=<path>]
803               This option is a more advanced form of subtree strategy, where
804               the strategy makes a guess on how two trees must be shifted to
805               match with each other when merging. Instead, the specified path
806               is prefixed (or stripped from the beginning) to make the shape
807               of two trees to match.
808
809       ort
810           This is meant as a drop-in replacement for the recursive algorithm
811           (as reflected in its acronym — "Ostensibly Recursive’s Twin"), and
812           will likely replace it in the future. It fixes corner cases that
813           the recursive strategy handles suboptimally, and is significantly
814           faster in large repositories — especially when many renames are
815           involved.
816
817           The ort strategy takes all the same options as recursive. However,
818           it ignores three of those options: no-renames, patience and
819           diff-algorithm. It always runs with rename detection (it handles it
820           much faster than recursive does), and it specifically uses
821           diff-algorithm=histogram.
822
823       resolve
824           This can only resolve two heads (i.e. the current branch and
825           another branch you pulled from) using a 3-way merge algorithm. It
826           tries to carefully detect criss-cross merge ambiguities. It does
827           not handle renames.
828
829       octopus
830           This resolves cases with more than two heads, but refuses to do a
831           complex merge that needs manual resolution. It is primarily meant
832           to be used for bundling topic branch heads together. This is the
833           default merge strategy when pulling or merging more than one
834           branch.
835
836       ours
837           This resolves any number of heads, but the resulting tree of the
838           merge is always that of the current branch head, effectively
839           ignoring all changes from all other branches. It is meant to be
840           used to supersede old development history of side branches. Note
841           that this is different from the -Xours option to the recursive
842           merge strategy.
843
844       subtree
845           This is a modified recursive strategy. When merging trees A and B,
846           if B corresponds to a subtree of A, B is first adjusted to match
847           the tree structure of A, instead of reading the trees at the same
848           level. This adjustment is also done to the common ancestor tree.
849
850       With the strategies that use 3-way merge (including the default,
851       recursive), if a change is made on both branches, but later reverted on
852       one of the branches, that change will be present in the merged result;
853       some people find this behavior confusing. It occurs because only the
854       heads and the merge base are considered when performing a merge, not
855       the individual commits. The merge algorithm therefore considers the
856       reverted change as no change at all, and substitutes the changed
857       version instead.
858

DEFAULT BEHAVIOUR

860       Often people use git pull without giving any parameter. Traditionally,
861       this has been equivalent to saying git pull origin. However, when
862       configuration branch.<name>.remote is present while on branch <name>,
863       that value is used instead of origin.
864
865       In order to determine what URL to use to fetch from, the value of the
866       configuration remote.<origin>.url is consulted and if there is not any
867       such variable, the value on the URL: line in $GIT_DIR/remotes/<origin>
868       is used.
869
870       In order to determine what remote branches to fetch (and optionally
871       store in the remote-tracking branches) when the command is run without
872       any refspec parameters on the command line, values of the configuration
873       variable remote.<origin>.fetch are consulted, and if there aren’t any,
874       $GIT_DIR/remotes/<origin> is consulted and its Pull: lines are used. In
875       addition to the refspec formats described in the OPTIONS section, you
876       can have a globbing refspec that looks like this:
877
878           refs/heads/*:refs/remotes/origin/*
879
880       A globbing refspec must have a non-empty RHS (i.e. must store what were
881       fetched in remote-tracking branches), and its LHS and RHS must end with
882       /*. The above specifies that all remote branches are tracked using
883       remote-tracking branches in refs/remotes/origin/ hierarchy under the
884       same name.
885
886       The rule to determine which remote branch to merge after fetching is a
887       bit involved, in order not to break backward compatibility.
888
889       If explicit refspecs were given on the command line of git pull, they
890       are all merged.
891
892       When no refspec was given on the command line, then git pull uses the
893       refspec from the configuration or $GIT_DIR/remotes/<origin>. In such
894       cases, the following rules apply:
895
896        1. If branch.<name>.merge configuration for the current branch <name>
897           exists, that is the name of the branch at the remote site that is
898           merged.
899
900        2. If the refspec is a globbing one, nothing is merged.
901
902        3. Otherwise the remote branch of the first refspec is merged.
903

EXAMPLES

905       •   Update the remote-tracking branches for the repository you cloned
906           from, then merge one of them into your current branch:
907
908               $ git pull
909               $ git pull origin
910
911           Normally the branch merged in is the HEAD of the remote repository,
912           but the choice is determined by the branch.<name>.remote and
913           branch.<name>.merge options; see git-config(1) for details.
914
915       •   Merge into the current branch the remote branch next:
916
917               $ git pull origin next
918
919           This leaves a copy of next temporarily in FETCH_HEAD, and updates
920           the remote-tracking branch origin/next. The same can be done by
921           invoking fetch and merge:
922
923               $ git fetch origin
924               $ git merge origin/next
925
926       If you tried a pull which resulted in complex conflicts and would want
927       to start over, you can recover with git reset.
928

SECURITY

930       The fetch and push protocols are not designed to prevent one side from
931       stealing data from the other repository that was not intended to be
932       shared. If you have private data that you need to protect from a
933       malicious peer, your best option is to store it in another repository.
934       This applies to both clients and servers. In particular, namespaces on
935       a server are not effective for read access control; you should only
936       grant read access to a namespace to clients that you would trust with
937       read access to the entire repository.
938
939       The known attack vectors are as follows:
940
941        1. The victim sends "have" lines advertising the IDs of objects it has
942           that are not explicitly intended to be shared but can be used to
943           optimize the transfer if the peer also has them. The attacker
944           chooses an object ID X to steal and sends a ref to X, but isn’t
945           required to send the content of X because the victim already has
946           it. Now the victim believes that the attacker has X, and it sends
947           the content of X back to the attacker later. (This attack is most
948           straightforward for a client to perform on a server, by creating a
949           ref to X in the namespace the client has access to and then
950           fetching it. The most likely way for a server to perform it on a
951           client is to "merge" X into a public branch and hope that the user
952           does additional work on this branch and pushes it back to the
953           server without noticing the merge.)
954
955        2. As in #1, the attacker chooses an object ID X to steal. The victim
956           sends an object Y that the attacker already has, and the attacker
957           falsely claims to have X and not Y, so the victim sends Y as a
958           delta against X. The delta reveals regions of X that are similar to
959           Y to the attacker.
960

BUGS

962       Using --recurse-submodules can only fetch new commits in already
963       checked out submodules right now. When e.g. upstream added a new
964       submodule in the just fetched commits of the superproject the submodule
965       itself cannot be fetched, making it impossible to check out that
966       submodule later without having to do a fetch again. This is expected to
967       be fixed in a future Git version.
968

SEE ALSO

970       git-fetch(1), git-merge(1), git-config(1)
971

GIT

973       Part of the git(1) suite
974
975
976
977Git 2.33.1                        2021-10-12                       GIT-PULL(1)
Impressum