1GIT-PULL(1) Git Manual GIT-PULL(1)
2
6 git-pull - Fetch from and merge with another repository or a local
7 branch
8
10 git-pull <options> <repository> <refspec>...
11
13 Runs git-fetch with the given parameters, and calls git-merge to merge
14 the retrieved head(s) into the current branch.
15 Note that you can use . (current directory) as the <repository> to pull
17 from the local repository — this is useful when merging local branches
18 into the current branch.
19
21 --summary
22 Show a diffstat at the end of the merge. The diffstat is also
23 controlled by the configuration option merge.diffstat.
24 -n, --no-summary
26 Do not show diffstat at the end of the merge.
27 --no-commit
29 Perform the merge but pretend the merge failed and do not
30 autocommit, to give the user a chance to inspect and further tweak
31 the merge result before committing.
32 --squash
34 Produce the working tree and index state as if a real merge
35 happened, but do not actually make a commit or move the HEAD, nor
36 record $GIT_DIR/MERGE_HEAD to cause the next git commit command to
37 create a merge commit. This allows you to create a single commit on
38 top of the current branch whose effect is the same as merging
39 another branch (or more in case of an octopus).
40 -s <strategy>, --strategy=<strategy>
42 Use the given merge strategy; can be supplied more than once to
43 specify them in the order they should be tried. If there is no -s
44 option, a built-in list of strategies is used instead
45 (git-merge-recursive when merging a single head, git-merge-octopus
46 otherwise).
47 -q, --quiet
49 Pass --quiet to git-fetch-pack and silence any other internally
50 used programs.
51 -v, --verbose
53 Be verbose.
54 -a, --append
56 Append ref names and object names of fetched refs to the existing
57 contents of .git/FETCH_HEAD. Without this option old data in
58 .git/FETCH_HEAD will be overwritten.
59 --upload-pack <upload-pack>
61 When given, and the repository to fetch from is handled by
62 git-fetch-pack, --exec=<upload-pack> is passed to the command to
63 specify non-default path for the command run on the other end.
64 -f, --force
66 When git-fetch is used with <rbranch>:<lbranch> refspec, it refuses
67 to update the local branch <lbranch> unless the remote branch
68 <rbranch> it fetches is a descendant of <lbranch>. This option
69 overrides that check.
70 -n, --no-tags
72 By default, git-fetch fetches tags that point at objects that are
73 downloaded from the remote repository and stores them locally. This
74 option disables this automatic tag following.
75 -t, --tags
77 Most of the tags are fetched automatically as branch heads are
78 downloaded, but tags that do not point at objects reachable from
79 the branch heads that are being tracked will not be fetched by this
80 mechanism. This flag lets all tags and their associated objects be
81 downloaded.
82 -k, --keep
84 Keep downloaded pack.
85 -u, --update-head-ok
87 By default git-fetch refuses to update the head which corresponds
88 to the current branch. This flag disables the check. This is purely
89 for the internal use for git-pull to communicate with git-fetch,
90 and unless you are implementing your own Porcelain you are not
91 supposed to use it.
92 --depth=<depth>
94 Deepen the history of a shallow repository created by git clone
95 with --depth=<depth> option (see git-clone(1)) by the specified
96 number of commits.
97 <repository>
99 The "remote" repository that is the source of a fetch or pull
100 operation. See the section GIT URLS below.
101 <refspec>
103 The canonical format of a <refspec> parameter is ?<src>:<dst>; that
104 is, an optional plus , followed by the source ref, followed by a
105 colon :, followed by the destination ref.
106 The remote ref that matches <src> is fetched, and if <dst> is not
108 empty string, the local ref that matches it is fast forwarded using
109 <src>. Again, if the optional plus + is used, the local ref is
110 updated even if it does not result in a fast forward update.
111 Note
113 If the remote branch from which you want to pull is modified in
114 non-linear ways such as being rewound and rebased frequently, then
115 a pull will attempt a merge with an older version of itself, likely
116 conflict, and fail. It is under these conditions that you would
117 want to use the + sign to indicate non-fast-forward updates will be
118 needed. There is currently no easy way to determine or declare that
119 a branch will be made available in a repository with this behavior;
120 the pulling user simply must know this is the expected usage
121 pattern for a branch.
122 Note
125 You never do your own development on branches that appear on the
126 right hand side of a <refspec> colon on Pull: lines; they are to be
127 updated by git-fetch. If you intend to do development derived from
128 a remote branch B, have a Pull: line to track it (i.e. Pull:
129 B:remote-B), and have a separate branch my-B to do your development
130 on top of it. The latter is created by git branch my-B remote-B (or
131 its equivalent git checkout -b my-B remote-B). Run git fetch to
132 keep track of the progress of the remote side, and when you see
133 something new on the remote branch, merge it into your development
134 branch with git pull . remote-B, while you are on my-B branch.
135 Note
138 There is a difference between listing multiple <refspec> directly
139 on git-pull command line and having multiple Pull: <refspec> lines
140 for a <repository> and running git-pull command without any
141 explicit <refspec> parameters. <refspec> listed explicitly on the
142 command line are always merged into the current branch after
143 fetching. In other words, if you list more than one remote refs,
144 you would be making an Octopus. While git-pull run without any
145 explicit <refspec> parameter takes default <refspec>s from Pull:
146 lines, it merges only the first <refspec> found into the current
147 branch, after fetching all the remote refs. This is because making
148 an Octopus from remote refs is rarely done, while keeping track of
149 multiple remote heads in one-go by fetching more than one is often
150 useful.
151 Some short-cut notations are also supported.
154 · tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; it
157 requests fetching everything up to the given tag.
158 · A parameter <ref> without a colon is equivalent to <ref>: when
160 pulling/fetching, so it merges <ref> into the current branch
161 without storing the remote branch anywhere locally
162
164 One of the following notations can be used to name the remote
165 repository:
166 · rsync://host.xz/path/to/repo.git/
169 · http://host.xz/path/to/repo.git/
171 · https://host.xz/path/to/repo.git/
173 · git://host.xz/path/to/repo.git/
175 · git://host.xz/~user/path/to/repo.git/
177 · ssh://[user@]host.xz[:port]/path/to/repo.git/
179 · ssh://[user@]host.xz/path/to/repo.git/
181 · ssh://[user@]host.xz/~user/path/to/repo.git/
183 · ssh://[user@]host.xz/~/path/to/repo.git
185 SSH is the default transport protocol over the network. You can
186 optionally specify which user to log-in as, and an alternate, scp-like
187 syntax is also supported. Both syntaxes support username expansion, as
188 does the native git protocol, but only the former supports port
189 specification. The following three are identical to the last three
190 above, respectively:
191 · [user@]host.xz:/path/to/repo.git/
194 · [user@]host.xz:~user/path/to/repo.git/
196 · [user@]host.xz:path/to/repo.git
198 To sync with a local directory, you can use:
199 · /path/to/repo.git/
202 · file:///path/to/repo.git/
204 They are mostly equivalent, except when cloning. See git-clone(1) for
205 details.
206
208 In addition to the above, as a short-hand, the name of a file in
209 $GIT_DIR/remotes directory can be given; the named file should be in
210 the following format:
211 URL: one of the above URL format
215 Push: <refspec>
216 Pull: <refspec>
217 Then such a short-hand is specified in place of <repository> without
220 <refspec> parameters on the command line, <refspec> specified on Push:
221 lines or Pull: lines are used for git-push and git-fetch/git-pull,
222 respectively. Multiple Push: and Pull: lines may be specified for
223 additional branch mappings.
224 Or, equivalently, in the $GIT_DIR/config (note the use of fetch instead
226 of Pull:):
227 [remote "<remote>"]
231 url = <url>
232 push = <refspec>
233 fetch = <refspec>
234 The name of a file in $GIT_DIR/branches directory can be specified as
237 an older notation short-hand; the named file should contain a single
238 line, a URL in one of the above formats, optionally followed by a hash
239 # and the name of remote head (URL fragment notation).
240 $GIT_DIR/branches/<remote> file that stores a <url> without the
241 fragment is equivalent to have this in the corresponding file in the
242 $GIT_DIR/remotes/ directory.
243 URL: <url>
247 Pull: refs/heads/master:<remote>
248 while having <url>#<head> is equivalent to
251 URL: <url>
255 Pull: refs/heads/<head>:<remote>
256
259 resolve
260 This can only resolve two heads (i.e. the current branch and
261 another branch you pulled from) using 3-way merge algorithm. It
262 tries to carefully detect criss-cross merge ambiguities and is
263 considered generally safe and fast.
264 recursive
266 This can only resolve two heads using 3-way merge algorithm. When
267 there are more than one common ancestors that can be used for 3-way
268 merge, it creates a merged tree of the common ancestors and uses
269 that as the reference tree for the 3-way merge. This has been
270 reported to result in fewer merge conflicts without causing
271 mis-merges by tests done on actual merge commits taken from Linux
272 2.6 kernel development history. Additionally this can detect and
273 handle merges involving renames. This is the default merge strategy
274 when pulling or merging one branch.
275 octopus
277 This resolves more than two-head case, but refuses to do complex
278 merge that needs manual resolution. It is primarily meant to be
279 used for bundling topic branch heads together. This is the default
280 merge strategy when pulling or merging more than one branches.
281 ours
283 This resolves any number of heads, but the result of the merge is
284 always the current branch head. It is meant to be used to supersede
285 old development history of side branches.
286
288 Often people use git pull without giving any parameter. Traditionally,
289 this has been equivalent to saying git pull origin. However, when
290 configuration branch.<name>.remote is present while on branch <name>,
291 that value is used instead of origin.
292 In order to determine what URL to use to fetch from, the value of the
294 configuration remote.<origin>.url is consulted and if there is not any
295 such variable, the value on URL: line in $GIT_DIR/remotes/<origin> file
296 is used.
297 In order to determine what remote branches to fetch (and optionally
299 store in the tracking branches) when the command is run without any
300 refspec parameters on the command line, values of the configuration
301 variable remote.<origin>.fetch are consulted, and if there aren´t any,
302 $GIT_DIR/remotes/<origin> file is consulted and its Pull: lines are
303 used. In addition to the refspec formats described in the OPTIONS
304 section, you can have a globbing refspec that looks like this:
305 refs/heads/*:refs/remotes/origin/*
309 A globbing refspec must have a non-empty RHS (i.e. must store what were
311 fetched in tracking branches), and its LHS and RHS must end with /*.
312 The above specifies that all remote branches are tracked using tracking
313 branches in refs/remotes/origin/ hierarchy under the same name.
314 The rule to determine which remote branch to merge after fetching is a
316 bit involved, in order not to break backward compatibility.
317 If explicit refspecs were given on the command line of git pull, they
319 are all merged.
320 When no refspec was given on the command line, then git pull uses the
322 refspec from the configuration or $GIT_DIR/remotes/<origin>. In such
323 cases, the following rules apply:
324 1. If branch.<name>.merge configuration for the current branch <name>
327 exists, that is the name of the branch at the remote site that is
328 merged.
329 2. If the refspec is a globbing one, nothing is merged.
331 3. Otherwise the remote branch of the first refspec is merged.
333
335 git pull, git pull origin
336 Update the remote-tracking branches for the repository you cloned
337 from, then merge one of them into your current branch. Normally the
338 branch merged in is the HEAD of the remote repository, but the
339 choice is determined by the branch.<name>.remote and
340 branch.<name>.merge options; see git-config(1) for details.
341 git pull origin next
343 Merge into the current branch the remote branch next; leaves a copy
344 of next temporarily in FETCH_HEAD, but does not update any
345 remote-tracking branches.
346 git pull . fixes enhancements
348 Bundle local branch fixes and enhancements on top of the current
349 branch, making an Octopus merge. This git pull . syntax is
350 equivalent to git merge.
351 git pull -s ours . obsolete
353 Merge local branch obsolete into the current branch, using ours
354 merge strategy.
355 git pull --no-commit . maint
357 Merge local branch maint into the current branch, but do not make a
358 commit automatically. This can be used when you want to include
359 further changes to the merge, or want to write your own merge
360 commit message.
361 You should refrain from abusing this option to sneak substantial
363 changes into a merge commit. Small fixups like bumping
364 release/version name would be acceptable.
365 Command line pull of multiple branches from one repository
367 $ git checkout master
370 $ git fetch origin +pu:pu maint:tmp
371 $ git pull . tmp
372 This updates (or creates, as necessary) branches pu and tmp in the
374 local repository by fetching from the branches (respectively) pu
375 and maint from the remote repository.
376 The pu branch will be updated even if it is does not fast-forward;
378 the others will not be.
379 The final command then merges the newly fetched tmp into master.
381 If you tried a pull which resulted in a complex conflicts and would
382 want to start over, you can recover with git-reset(1).
383
385 git-fetch(1), git-merge(1), git-config(1)
386
388 Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano
389 <junkio@cox.net>
390
392 Documentation by Jon Loeliger, David Greaves, Junio C Hamano and the
393 git-list <git@vger.kernel.org>.
394
396 Part of the git(7) suite
397Git 1.5.3.3 10/09/2007 GIT-PULL(1)