1GIT-FETCH(1) Git Manual GIT-FETCH(1)
2
6 git-fetch - Download objects and refs from another repository
7
9 git fetch [<options>] [<repository> [<refspec>...]]
10 git fetch [<options>] <group>
11 git fetch --multiple [<options>] [(<repository> | <group>)...]
12 git fetch --all [<options>]
13
16 Fetches named heads or tags from one or more other repositories, along
17 with the objects necessary to complete them.
18 The ref names and their object names of fetched refs are stored in
20 .git/FETCH_HEAD. This information is left for a later merge operation
21 done by git merge.
22 When <refspec> stores the fetched result in remote-tracking branches,
24 the tags that point at these branches are automatically followed. This
25 is done by first fetching from the remote using the given <refspec>s,
26 and if the repository has objects that are pointed by remote tags that
27 it does not yet have, then fetch those missing tags. If the other end
28 has tags that point at branches you are not interested in, you will not
29 get them.
30 git fetch can fetch from either a single named repository, or from
32 several repositories at once if <group> is given and there is a
33 remotes.<group> entry in the configuration file. (See git-config(1)).
34
36 --all
37 Fetch all remotes.
38 -a, --append
40 Append ref names and object names of fetched refs to the existing
41 contents of .git/FETCH_HEAD. Without this option old data in
42 .git/FETCH_HEAD will be overwritten.
43 --depth=<depth>
45 Deepen or shorten the history of a shallow repository created by
46 git clone with --depth=<depth> option (see git-clone(1)) to the
47 specified number of commits from the tip of each remote branch
48 history. Tags for the deepened commits are not fetched.
49 --unshallow
51 Convert a shallow repository to a complete one, removing all the
52 limitations imposed by shallow repositories.
53 --dry-run
55 Show what would be done, without making any changes.
56 -f, --force
58 When git fetch is used with <rbranch>:<lbranch> refspec, it refuses
59 to update the local branch <lbranch> unless the remote branch
60 <rbranch> it fetches is a descendant of <lbranch>. This option
61 overrides that check.
62 -k, --keep
64 Keep downloaded pack.
65 --multiple
67 Allow several <repository> and <group> arguments to be specified.
68 No <refspec>s may be specified.
69 -p, --prune
71 After fetching, remove any remote-tracking branches which no longer
72 exist on the remote.
73 -n, --no-tags
75 By default, tags that point at objects that are downloaded from the
76 remote repository are fetched and stored locally. This option
77 disables this automatic tag following. The default behavior for a
78 remote may be specified with the remote.<name>.tagopt setting. See
79 git-config(1).
80 -t, --tags
82 This is a short-hand for giving "refs/tags/:refs/tags/" refspec
83 from the command line, to ask all tags to be fetched and stored
84 locally. Because this acts as an explicit refspec, the default
85 refspecs (configured with the remote.$name.fetch variable) are
86 overridden and not used.
87 --recurse-submodules[=yes|on-demand|no]
89 This option controls if and under what conditions new commits of
90 populated submodules should be fetched too. It can be used as a
91 boolean option to completely disable recursion when set to no or to
92 unconditionally recurse into all populated submodules when set to
93 yes, which is the default when this option is used without any
94 value. Use on-demand to only recurse into a populated submodule
95 when the superproject retrieves a commit that updates the
96 submodule’s reference to a commit that isn’t already in the local
97 submodule clone.
98 --no-recurse-submodules
100 Disable recursive fetching of submodules (this has the same effect
101 as using the --recurse-submodules=no option).
102 --submodule-prefix=<path>
104 Prepend <path> to paths printed in informative messages such as
105 "Fetching submodule foo". This option is used internally when
106 recursing over submodules.
107 --recurse-submodules-default=[yes|on-demand]
109 This option is used internally to temporarily provide a
110 non-negative default value for the --recurse-submodules option. All
111 other methods of configuring fetch’s submodule recursion (such as
112 settings in gitmodules(5) and git-config(1)) override this option,
113 as does specifying --[no-]recurse-submodules directly.
114 -u, --update-head-ok
116 By default git fetch refuses to update the head which corresponds
117 to the current branch. This flag disables the check. This is purely
118 for the internal use for git pull to communicate with git fetch,
119 and unless you are implementing your own Porcelain you are not
120 supposed to use it.
121 --upload-pack <upload-pack>
123 When given, and the repository to fetch from is handled by git
124 fetch-pack, --exec=<upload-pack> is passed to the command to
125 specify non-default path for the command run on the other end.
126 -q, --quiet
128 Pass --quiet to git-fetch-pack and silence any other internally
129 used git commands. Progress is not reported to the standard error
130 stream.
131 -v, --verbose
133 Be verbose.
134 --progress
136 Progress status is reported on the standard error stream by default
137 when it is attached to a terminal, unless -q is specified. This
138 flag forces progress status even if the standard error stream is
139 not directed to a terminal.
140 <repository>
142 The "remote" repository that is the source of a fetch or pull
143 operation. This parameter can be either a URL (see the section GIT
144 URLS below) or the name of a remote (see the section REMOTES
145 below).
146 <group>
148 A name referring to a list of repositories as the value of
149 remotes.<group> in the configuration file. (See git-config(1)).
150 <refspec>
152 The format of a <refspec> parameter is an optional plus +, followed
153 by the source ref <src>, followed by a colon :, followed by the
154 destination ref <dst>.
155 The remote ref that matches <src> is fetched, and if <dst> is not
157 empty string, the local ref that matches it is fast-forwarded using
158 <src>. If the optional plus + is used, the local ref is updated
159 even if it does not result in a fast-forward update.
160 Note
162 If the remote branch from which you want to pull is modified in
163 non-linear ways such as being rewound and rebased frequently,
164 then a pull will attempt a merge with an older version of
165 itself, likely conflict, and fail. It is under these conditions
166 that you would want to use the + sign to indicate
167 non-fast-forward updates will be needed. There is currently no
168 easy way to determine or declare that a branch will be made
169 available in a repository with this behavior; the pulling user
170 simply must know this is the expected usage pattern for a
171 branch.
172 Note
174 You never do your own development on branches that appear on
175 the right hand side of a <refspec> colon on Pull: lines; they
176 are to be updated by git fetch. If you intend to do development
177 derived from a remote branch B, have a Pull: line to track it
178 (i.e. Pull: B:remote-B), and have a separate branch my-B to do
179 your development on top of it. The latter is created by git
180 branch my-B remote-B (or its equivalent git checkout -b my-B
181 remote-B). Run git fetch to keep track of the progress of the
182 remote side, and when you see something new on the remote
183 branch, merge it into your development branch with git pull .
184 remote-B, while you are on my-B branch.
185 Note
187 There is a difference between listing multiple <refspec>
188 directly on git pull command line and having multiple Pull:
189 <refspec> lines for a <repository> and running git pull command
190 without any explicit <refspec> parameters. <refspec> listed
191 explicitly on the command line are always merged into the
192 current branch after fetching. In other words, if you list more
193 than one remote refs, you would be making an Octopus. While git
194 pull run without any explicit <refspec> parameter takes default
195 <refspec>s from Pull: lines, it merges only the first <refspec>
196 found into the current branch, after fetching all the remote
197 refs. This is because making an Octopus from remote refs is
198 rarely done, while keeping track of multiple remote heads in
199 one-go by fetching more than one is often useful.
200 Some short-cut notations are also supported.
201 · tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; it
203 requests fetching everything up to the given tag.
204 · A parameter <ref> without a colon is equivalent to <ref>: when
206 pulling/fetching, so it merges <ref> into the current branch
207 without storing the remote branch anywhere locally
208
210 In general, URLs contain information about the transport protocol, the
211 address of the remote server, and the path to the repository. Depending
212 on the transport protocol, some of this information may be absent.
213 Git supports ssh, git, http, and https protocols (in addition, ftp, and
215 ftps can be used for fetching and rsync can be used for fetching and
216 pushing, but these are inefficient and deprecated; do not use them).
217 The following syntaxes may be used with them:
219 · ssh://[user@]host.xz[:port]/path/to/repo.git/
221 · git://host.xz[:port]/path/to/repo.git/
223 · http[s]://host.xz[:port]/path/to/repo.git/
225 · ftp[s]://host.xz[:port]/path/to/repo.git/
227 · rsync://host.xz/path/to/repo.git/
229 An alternative scp-like syntax may also be used with the ssh protocol:
231 · [user@]host.xz:path/to/repo.git/
233 The ssh and git protocols additionally support ~username expansion:
235 · ssh://[user@]host.xz[:port]/~[user]/path/to/repo.git/
237 · git://host.xz[:port]/~[user]/path/to/repo.git/
239 · [user@]host.xz:/~[user]/path/to/repo.git/
241 For local repositories, also supported by Git natively, the following
243 syntaxes may be used:
244 · /path/to/repo.git/
246 · file:///path/to/repo.git/
248 These two syntaxes are mostly equivalent, except when cloning, when the
250 former implies --local option. See git-clone(1) for details.
251 When Git doesn’t know how to handle a certain transport protocol, it
253 attempts to use the remote-<transport> remote helper, if one exists. To
254 explicitly request a remote helper, the following syntax may be used:
255 · <transport>::<address>
257 where <address> may be a path, a server and path, or an arbitrary
259 URL-like string recognized by the specific remote helper being invoked.
260 See gitremote-helpers(1) for details.
261 If there are a large number of similarly-named remote repositories and
263 you want to use a different format for them (such that the URLs you use
264 will be rewritten into URLs that work), you can create a configuration
265 section of the form:
266 [url "<actual url base>"]
268 insteadOf = <other url base>
269 For example, with this:
272 [url "git://git.host.xz/"]
274 insteadOf = host.xz:/path/to/
275 insteadOf = work:
276 a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
279 rewritten in any context that takes a URL to be
280 "git://git.host.xz/repo.git".
281 If you want to rewrite URLs for push only, you can create a
283 configuration section of the form:
284 [url "<actual url base>"]
286 pushInsteadOf = <other url base>
287 For example, with this:
290 [url "ssh://example.org/"]
292 pushInsteadOf = git://example.org/
293 a URL like "git://example.org/path/to/repo.git" will be rewritten to
296 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still
297 use the original URL.
298
300 The name of one of the following can be used instead of a URL as
301 <repository> argument:
302 · a remote in the Git configuration file: $GIT_DIR/config,
304 · a file in the $GIT_DIR/remotes directory, or
306 · a file in the $GIT_DIR/branches directory.
308 All of these also allow you to omit the refspec from the command line
310 because they each contain a refspec which git will use by default.
311 Named remote in configuration file
313 You can choose to provide the name of a remote which you had previously
314 configured using git-remote(1), git-config(1) or even by a manual edit
315 to the $GIT_DIR/config file. The URL of this remote will be used to
316 access the repository. The refspec of this remote will be used by
317 default when you do not provide a refspec on the command line. The
318 entry in the config file would appear like this:
319 [remote "<name>"]
321 url = <url>
322 pushurl = <pushurl>
323 push = <refspec>
324 fetch = <refspec>
325 The <pushurl> is used for pushes only. It is optional and defaults to
328 <url>.
329 Named file in $GIT_DIR/remotes
331 You can choose to provide the name of a file in $GIT_DIR/remotes. The
332 URL in this file will be used to access the repository. The refspec in
333 this file will be used as default when you do not provide a refspec on
334 the command line. This file should have the following format:
335 URL: one of the above URL format
337 Push: <refspec>
338 Pull: <refspec>
339 Push: lines are used by git push and Pull: lines are used by git pull
342 and git fetch. Multiple Push: and Pull: lines may be specified for
343 additional branch mappings.
344 Named file in $GIT_DIR/branches
346 You can choose to provide the name of a file in $GIT_DIR/branches. The
347 URL in this file will be used to access the repository. This file
348 should have the following format:
349 <url>#<head>
351 <url> is required; #<head> is optional.
354 Depending on the operation, git will use one of the following refspecs,
356 if you don’t provide one on the command line. <branch> is the name of
357 this file in $GIT_DIR/branches and <head> defaults to master.
358 git fetch uses:
360 refs/heads/<head>:refs/heads/<branch>
362 git push uses:
365 HEAD:refs/heads/<head>
367
370 · Update the remote-tracking branches:
371 $ git fetch origin
373 The above command copies all branches from the remote refs/heads/
375 namespace and stores them to the local refs/remotes/origin/
376 namespace, unless the branch.<name>.fetch option is used to specify
377 a non-default refspec.
378 · Using refspecs explicitly:
380 $ git fetch origin +pu:pu maint:tmp
382 This updates (or creates, as necessary) branches pu and tmp in the
384 local repository by fetching from the branches (respectively) pu
385 and maint from the remote repository.
386 The pu branch will be updated even if it is does not fast-forward,
388 because it is prefixed with a plus sign; tmp will not be.
389
391 Using --recurse-submodules can only fetch new commits in already
392 checked out submodules right now. When e.g. upstream added a new
393 submodule in the just fetched commits of the superproject the submodule
394 itself can not be fetched, making it impossible to check out that
395 submodule later without having to do a fetch again. This is expected to
396 be fixed in a future Git version.
397
399 git-pull(1)
400
402 Part of the git(1) suite
403Git 1.8.3.1 11/19/2018 GIT-FETCH(1)