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           By default, the pre-merge and commit-msg hooks are run. When
194           --no-verify is given, these are bypassed. See also githooks(5).
195           Only useful when merging.
196
197       -s <strategy>, --strategy=<strategy>
198           Use the given merge strategy; can be supplied more than once to
199           specify them in the order they should be tried. If there is no -s
200           option, a built-in list of strategies is used instead (ort when
201           merging a single head, octopus otherwise).
202
203       -X <option>, --strategy-option=<option>
204           Pass merge strategy specific option through to the merge strategy.
205
206       --verify-signatures, --no-verify-signatures
207           Verify that the tip commit of the side branch being merged is
208           signed with a valid key, i.e. a key that has a valid uid: in the
209           default trust model, this means the signing key has been signed by
210           a trusted key. If the tip commit of the side branch is not signed
211           with a valid key, the merge is aborted.
212
213           Only useful when merging.
214
215       --summary, --no-summary
216           Synonyms to --stat and --no-stat; these are deprecated and will be
217           removed in the future.
218
219       --autostash, --no-autostash
220           Automatically create a temporary stash entry before the operation
221           begins, record it in the special ref MERGE_AUTOSTASH and apply it
222           after the operation ends. This means that you can run the operation
223           on a dirty worktree. However, use with care: the final stash
224           application after a successful merge might result in non-trivial
225           conflicts.
226
227       --allow-unrelated-histories
228           By default, git merge command refuses to merge histories that do
229           not share a common ancestor. This option can be used to override
230           this safety when merging histories of two projects that started
231           their lives independently. As that is a very rare occasion, no
232           configuration variable to enable this by default exists and will
233           not be added.
234
235           Only useful when merging.
236
237       -r, --rebase[=false|true|merges|interactive]
238           When true, rebase the current branch on top of the upstream branch
239           after fetching. If there is a remote-tracking branch corresponding
240           to the upstream branch and the upstream branch was rebased since
241           last fetched, the rebase uses that information to avoid rebasing
242           non-local changes.
243
244           When set to merges, rebase using git rebase --rebase-merges so that
245           the local merge commits are included in the rebase (see git-
246           rebase(1) for details).
247
248           When false, merge the upstream branch into the current branch.
249
250           When interactive, enable the interactive mode of rebase.
251
252           See pull.rebase, branch.<name>.rebase and branch.autoSetupRebase in
253           git-config(1) if you want to make git pull always use --rebase
254           instead of merging.
255
256               Note
257               This is a potentially dangerous mode of operation. It rewrites
258               history, which does not bode well when you published that
259               history already. Do not use this option unless you have read
260               git-rebase(1) carefully.
261
262       --no-rebase
263           This is shorthand for --rebase=false.
264
265   Options related to fetching
266       --all
267           Fetch all remotes.
268
269       -a, --append
270           Append ref names and object names of fetched refs to the existing
271           contents of .git/FETCH_HEAD. Without this option old data in
272           .git/FETCH_HEAD will be overwritten.
273
274       --atomic
275           Use an atomic transaction to update local refs. Either all refs are
276           updated, or on error, no refs are updated.
277
278       --depth=<depth>
279           Limit fetching to the specified number of commits from the tip of
280           each remote branch history. If fetching to a shallow repository
281           created by git clone with --depth=<depth> option (see git-
282           clone(1)), deepen or shorten the history to the specified number of
283           commits. Tags for the deepened commits are not fetched.
284
285       --deepen=<depth>
286           Similar to --depth, except it specifies the number of commits from
287           the current shallow boundary instead of from the tip of each remote
288           branch history.
289
290       --shallow-since=<date>
291           Deepen or shorten the history of a shallow repository to include
292           all reachable commits after <date>.
293
294       --shallow-exclude=<revision>
295           Deepen or shorten the history of a shallow repository to exclude
296           commits reachable from a specified remote branch or tag. This
297           option can be specified multiple times.
298
299       --unshallow
300           If the source repository is complete, convert a shallow repository
301           to a complete one, removing all the limitations imposed by shallow
302           repositories.
303
304           If the source repository is shallow, fetch as much as possible so
305           that the current repository has the same history as the source
306           repository.
307
308       --update-shallow
309           By default when fetching from a shallow repository, git fetch
310           refuses refs that require updating .git/shallow. This option
311           updates .git/shallow and accept such refs.
312
313       --negotiation-tip=<commit|glob>
314           By default, Git will report, to the server, commits reachable from
315           all local refs to find common commits in an attempt to reduce the
316           size of the to-be-received packfile. If specified, Git will only
317           report commits reachable from the given tips. This is useful to
318           speed up fetches when the user knows which local ref is likely to
319           have commits in common with the upstream ref being fetched.
320
321           This option may be specified more than once; if so, Git will report
322           commits reachable from any of the given commits.
323
324           The argument to this option may be a glob on ref names, a ref, or
325           the (possibly abbreviated) SHA-1 of a commit. Specifying a glob is
326           equivalent to specifying this option multiple times, one for each
327           matching ref name.
328
329           See also the fetch.negotiationAlgorithm and push.negotiate
330           configuration variables documented in git-config(1), and the
331           --negotiate-only option below.
332
333       --negotiate-only
334           Do not fetch anything from the server, and instead print the
335           ancestors of the provided --negotiation-tip=* arguments, which we
336           have in common with the server.
337
338           This is incompatible with --recurse-submodules=[yes|on-demand].
339           Internally this is used to implement the push.negotiate option, see
340           git-config(1).
341
342       --dry-run
343           Show what would be done, without making any changes.
344
345       -f, --force
346           When git fetch is used with <src>:<dst> refspec it may refuse to
347           update the local branch as discussed in the <refspec> part of the
348           git-fetch(1) documentation. This option overrides that check.
349
350       -k, --keep
351           Keep downloaded pack.
352
353       --prefetch
354           Modify the configured refspec to place all refs into the
355           refs/prefetch/ namespace. See the prefetch task in git-
356           maintenance(1).
357
358       -p, --prune
359           Before fetching, remove any remote-tracking references that no
360           longer exist on the remote. Tags are not subject to pruning if they
361           are fetched only because of the default tag auto-following or due
362           to a --tags option. However, if tags are fetched due to an explicit
363           refspec (either on the command line or in the remote configuration,
364           for example if the remote was cloned with the --mirror option),
365           then they are also subject to pruning. Supplying --prune-tags is a
366           shorthand for providing the tag refspec.
367
368       --no-tags
369           By default, tags that point at objects that are downloaded from the
370           remote repository are fetched and stored locally. This option
371           disables this automatic tag following. The default behavior for a
372           remote may be specified with the remote.<name>.tagOpt setting. See
373           git-config(1).
374
375       --refmap=<refspec>
376           When fetching refs listed on the command line, use the specified
377           refspec (can be given more than once) to map the refs to
378           remote-tracking branches, instead of the values of remote.*.fetch
379           configuration variables for the remote repository. Providing an
380           empty <refspec> to the --refmap option causes Git to ignore the
381           configured refspecs and rely entirely on the refspecs supplied as
382           command-line arguments. See section on "Configured Remote-tracking
383           Branches" for details.
384
385       -t, --tags
386           Fetch all tags from the remote (i.e., fetch remote tags refs/tags/*
387           into local tags with the same name), in addition to whatever else
388           would otherwise be fetched. Using this option alone does not
389           subject tags to pruning, even if --prune is used (though tags may
390           be pruned anyway if they are also the destination of an explicit
391           refspec; see --prune).
392
393       -j, --jobs=<n>
394           Number of parallel children to be used for all forms of fetching.
395
396           If the --multiple option was specified, the different remotes will
397           be fetched in parallel. If multiple submodules are fetched, they
398           will be fetched in parallel. To control them independently, use the
399           config settings fetch.parallel and submodule.fetchJobs (see git-
400           config(1)).
401
402           Typically, parallel recursive and multi-remote fetches will be
403           faster. By default fetches are performed sequentially, not in
404           parallel.
405
406       --set-upstream
407           If the remote is fetched successfully, add upstream (tracking)
408           reference, used by argument-less git-pull(1) and other commands.
409           For more information, see branch.<name>.merge and
410           branch.<name>.remote in git-config(1).
411
412       --upload-pack <upload-pack>
413           When given, and the repository to fetch from is handled by git
414           fetch-pack, --exec=<upload-pack> is passed to the command to
415           specify non-default path for the command run on the other end.
416
417       --progress
418           Progress status is reported on the standard error stream by default
419           when it is attached to a terminal, unless -q is specified. This
420           flag forces progress status even if the standard error stream is
421           not directed to a terminal.
422
423       -o <option>, --server-option=<option>
424           Transmit the given string to the server when communicating using
425           protocol version 2. The given string must not contain a NUL or LF
426           character. The server’s handling of server options, including
427           unknown ones, is server-specific. When multiple
428           --server-option=<option> are given, they are all sent to the other
429           side in the order listed on the command line.
430
431       --show-forced-updates
432           By default, git checks if a branch is force-updated during fetch.
433           This can be disabled through fetch.showForcedUpdates, but the
434           --show-forced-updates option guarantees this check occurs. See git-
435           config(1).
436
437       --no-show-forced-updates
438           By default, git checks if a branch is force-updated during fetch.
439           Pass --no-show-forced-updates or set fetch.showForcedUpdates to
440           false to skip this check for performance reasons. If used during
441           git-pull the --ff-only option will still check for forced updates
442           before attempting a fast-forward update. See git-config(1).
443
444       -4, --ipv4
445           Use IPv4 addresses only, ignoring IPv6 addresses.
446
447       -6, --ipv6
448           Use IPv6 addresses only, ignoring IPv4 addresses.
449
450       <repository>
451           The "remote" repository that is the source of a fetch or pull
452           operation. This parameter can be either a URL (see the section GIT
453           URLS below) or the name of a remote (see the section REMOTES
454           below).
455
456       <refspec>
457           Specifies which refs to fetch and which local refs to update. When
458           no <refspec>s appear on the command line, the refs to fetch are
459           read from remote.<repository>.fetch variables instead (see the
460           section "CONFIGURED REMOTE-TRACKING BRANCHES" in git-fetch(1)).
461
462           The format of a <refspec> parameter is an optional plus +, followed
463           by the source <src>, followed by a colon :, followed by the
464           destination ref <dst>. The colon can be omitted when <dst> is
465           empty. <src> is typically a ref, but it can also be a fully spelled
466           hex object name.
467
468           A <refspec> may contain a * in its <src> to indicate a simple
469           pattern match. Such a refspec functions like a glob that matches
470           any ref with the same prefix. A pattern <refspec> must have a * in
471           both the <src> and <dst>. It will map refs to the destination by
472           replacing the * with the contents matched from the source.
473
474           If a refspec is prefixed by ^, it will be interpreted as a negative
475           refspec. Rather than specifying which refs to fetch or which local
476           refs to update, such a refspec will instead specify refs to
477           exclude. A ref will be considered to match if it matches at least
478           one positive refspec, and does not match any negative refspec.
479           Negative refspecs can be useful to restrict the scope of a pattern
480           refspec so that it will not include specific refs. Negative
481           refspecs can themselves be pattern refspecs. However, they may only
482           contain a <src> and do not specify a <dst>. Fully spelled out hex
483           object names are also not supported.
484
485           tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; it
486           requests fetching everything up to the given tag.
487
488           The remote ref that matches <src> is fetched, and if <dst> is not
489           an empty string, an attempt is made to update the local ref that
490           matches it.
491
492           Whether that update is allowed without --force depends on the ref
493           namespace it’s being fetched to, the type of object being fetched,
494           and whether the update is considered to be a fast-forward.
495           Generally, the same rules apply for fetching as when pushing, see
496           the <refspec>...  section of git-push(1) for what those are.
497           Exceptions to those rules particular to git fetch are noted below.
498
499           Until Git version 2.20, and unlike when pushing with git-push(1),
500           any updates to refs/tags/* would be accepted without + in the
501           refspec (or --force). When fetching, we promiscuously considered
502           all tag updates from a remote to be forced fetches. Since Git
503           version 2.20, fetching to update refs/tags/* works the same way as
504           when pushing. I.e. any updates will be rejected without + in the
505           refspec (or --force).
506
507           Unlike when pushing with git-push(1), any updates outside of
508           refs/{tags,heads}/* will be accepted without + in the refspec (or
509           --force), whether that’s swapping e.g. a tree object for a blob, or
510           a commit for another commit that’s doesn’t have the previous commit
511           as an ancestor etc.
512
513           Unlike when pushing with git-push(1), there is no configuration
514           which’ll amend these rules, and nothing like a pre-fetch hook
515           analogous to the pre-receive hook.
516
517           As with pushing with git-push(1), all of the rules described above
518           about what’s not allowed as an update can be overridden by adding
519           an the optional leading + to a refspec (or using --force command
520           line option). The only exception to this is that no amount of
521           forcing will make the refs/heads/* namespace accept a non-commit
522           object.
523
524               Note
525               When the remote branch you want to fetch is known to be rewound
526               and rebased regularly, it is expected that its new tip will not
527               be descendant of its previous tip (as stored in your
528               remote-tracking branch the last time you fetched). You would
529               want to use the + sign to indicate non-fast-forward updates
530               will be needed for such branches. There is no way to determine
531               or declare that a branch will be made available in a repository
532               with this behavior; the pulling user simply must know this is
533               the expected usage pattern for a branch.
534
535               Note
536               There is a difference between listing multiple <refspec>
537               directly on git pull command line and having multiple
538               remote.<repository>.fetch entries in your configuration for a
539               <repository> and running a git pull command without any
540               explicit <refspec> parameters. <refspec>s listed explicitly on
541               the command line are always merged into the current branch
542               after fetching. In other words, if you list more than one
543               remote ref, git pull will create an Octopus merge. On the other
544               hand, if you do not list any explicit <refspec> parameter on
545               the command line, git pull will fetch all the <refspec>s it
546               finds in the remote.<repository>.fetch configuration and merge
547               only the first <refspec> found into the current branch. This is
548               because making an Octopus from remote refs is rarely done,
549               while keeping track of multiple remote heads in one-go by
550               fetching more than one is often useful.
551

GIT URLS

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

REMOTES

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

MERGE STRATEGIES

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

DEFAULT BEHAVIOUR

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

EXAMPLES

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

SECURITY

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

BUGS

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

SEE ALSO

973       git-fetch(1), git-merge(1), git-config(1)
974

GIT

976       Part of the git(1) suite
977
978
979
980Git 2.39.1                        2023-01-13                       GIT-PULL(1)
Impressum