]> git.ipfire.org Git - thirdparty/git.git/blob - Documentation/git-fetch.txt
clone: allow "--bare" with "-o"
[thirdparty/git.git] / Documentation / git-fetch.txt
1 git-fetch(1)
2 ============
3
4 NAME
5 ----
6 git-fetch - Download objects and refs from another repository
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git fetch' [<options>] [<repository> [<refspec>...]]
13 'git fetch' [<options>] <group>
14 'git fetch' --multiple [<options>] [(<repository> | <group>)...]
15 'git fetch' --all [<options>]
16
17
18 DESCRIPTION
19 -----------
20 Fetch branches and/or tags (collectively, "refs") from one or more
21 other repositories, along with the objects necessary to complete their
22 histories. Remote-tracking branches are updated (see the description
23 of <refspec> below for ways to control this behavior).
24
25 By default, any tag that points into the histories being fetched is
26 also fetched; the effect is to fetch tags that
27 point at branches that you are interested in. This default behavior
28 can be changed by using the --tags or --no-tags options or by
29 configuring remote.<name>.tagOpt. By using a refspec that fetches tags
30 explicitly, you can fetch tags that do not point into branches you
31 are interested in as well.
32
33 'git fetch' can fetch from either a single named repository or URL,
34 or from several repositories at once if <group> is given and
35 there is a remotes.<group> entry in the configuration file.
36 (See linkgit:git-config[1]).
37
38 When no remote is specified, by default the `origin` remote will be used,
39 unless there's an upstream branch configured for the current branch.
40
41 The names of refs that are fetched, together with the object names
42 they point at, are written to `.git/FETCH_HEAD`. This information
43 may be used by scripts or other git commands, such as linkgit:git-pull[1].
44
45 OPTIONS
46 -------
47 include::fetch-options.txt[]
48
49 include::pull-fetch-param.txt[]
50
51 --stdin::
52 Read refspecs, one per line, from stdin in addition to those provided
53 as arguments. The "tag <name>" format is not supported.
54
55 include::urls-remotes.txt[]
56
57
58 CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
59 -------------------------------------------
60
61 You often interact with the same remote repository by
62 regularly and repeatedly fetching from it. In order to keep track
63 of the progress of such a remote repository, `git fetch` allows you
64 to configure `remote.<repository>.fetch` configuration variables.
65
66 Typically such a variable may look like this:
67
68 ------------------------------------------------
69 [remote "origin"]
70 fetch = +refs/heads/*:refs/remotes/origin/*
71 ------------------------------------------------
72
73 This configuration is used in two ways:
74
75 * When `git fetch` is run without specifying what branches
76 and/or tags to fetch on the command line, e.g. `git fetch origin`
77 or `git fetch`, `remote.<repository>.fetch` values are used as
78 the refspecs--they specify which refs to fetch and which local refs
79 to update. The example above will fetch
80 all branches that exist in the `origin` (i.e. any ref that matches
81 the left-hand side of the value, `refs/heads/*`) and update the
82 corresponding remote-tracking branches in the `refs/remotes/origin/*`
83 hierarchy.
84
85 * When `git fetch` is run with explicit branches and/or tags
86 to fetch on the command line, e.g. `git fetch origin master`, the
87 <refspec>s given on the command line determine what are to be
88 fetched (e.g. `master` in the example,
89 which is a short-hand for `master:`, which in turn means
90 "fetch the 'master' branch but I do not explicitly say what
91 remote-tracking branch to update with it from the command line"),
92 and the example command will
93 fetch _only_ the 'master' branch. The `remote.<repository>.fetch`
94 values determine which
95 remote-tracking branch, if any, is updated. When used in this
96 way, the `remote.<repository>.fetch` values do not have any
97 effect in deciding _what_ gets fetched (i.e. the values are not
98 used as refspecs when the command-line lists refspecs); they are
99 only used to decide _where_ the refs that are fetched are stored
100 by acting as a mapping.
101
102 The latter use of the `remote.<repository>.fetch` values can be
103 overridden by giving the `--refmap=<refspec>` parameter(s) on the
104 command line.
105
106 PRUNING
107 -------
108
109 Git has a default disposition of keeping data unless it's explicitly
110 thrown away; this extends to holding onto local references to branches
111 on remotes that have themselves deleted those branches.
112
113 If left to accumulate, these stale references might make performance
114 worse on big and busy repos that have a lot of branch churn, and
115 e.g. make the output of commands like `git branch -a --contains
116 <commit>` needlessly verbose, as well as impacting anything else
117 that'll work with the complete set of known references.
118
119 These remote-tracking references can be deleted as a one-off with
120 either of:
121
122 ------------------------------------------------
123 # While fetching
124 $ git fetch --prune <name>
125
126 # Only prune, don't fetch
127 $ git remote prune <name>
128 ------------------------------------------------
129
130 To prune references as part of your normal workflow without needing to
131 remember to run that, set `fetch.prune` globally, or
132 `remote.<name>.prune` per-remote in the config. See
133 linkgit:git-config[1].
134
135 Here's where things get tricky and more specific. The pruning feature
136 doesn't actually care about branches, instead it'll prune local <-->
137 remote-references as a function of the refspec of the remote (see
138 `<refspec>` and <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> above).
139
140 Therefore if the refspec for the remote includes
141 e.g. `refs/tags/*:refs/tags/*`, or you manually run e.g. `git fetch
142 --prune <name> "refs/tags/*:refs/tags/*"` it won't be stale remote
143 tracking branches that are deleted, but any local tag that doesn't
144 exist on the remote.
145
146 This might not be what you expect, i.e. you want to prune remote
147 `<name>`, but also explicitly fetch tags from it, so when you fetch
148 from it you delete all your local tags, most of which may not have
149 come from the `<name>` remote in the first place.
150
151 So be careful when using this with a refspec like
152 `refs/tags/*:refs/tags/*`, or any other refspec which might map
153 references from multiple remotes to the same local namespace.
154
155 Since keeping up-to-date with both branches and tags on the remote is
156 a common use-case the `--prune-tags` option can be supplied along with
157 `--prune` to prune local tags that don't exist on the remote, and
158 force-update those tags that differ. Tag pruning can also be enabled
159 with `fetch.pruneTags` or `remote.<name>.pruneTags` in the config. See
160 linkgit:git-config[1].
161
162 The `--prune-tags` option is equivalent to having
163 `refs/tags/*:refs/tags/*` declared in the refspecs of the remote. This
164 can lead to some seemingly strange interactions:
165
166 ------------------------------------------------
167 # These both fetch tags
168 $ git fetch --no-tags origin 'refs/tags/*:refs/tags/*'
169 $ git fetch --no-tags --prune-tags origin
170 ------------------------------------------------
171
172 The reason it doesn't error out when provided without `--prune` or its
173 config versions is for flexibility of the configured versions, and to
174 maintain a 1=1 mapping between what the command line flags do, and
175 what the configuration versions do.
176
177 It's reasonable to e.g. configure `fetch.pruneTags=true` in
178 `~/.gitconfig` to have tags pruned whenever `git fetch --prune` is
179 run, without making every invocation of `git fetch` without `--prune`
180 an error.
181
182 Pruning tags with `--prune-tags` also works when fetching a URL
183 instead of a named remote. These will all prune tags not found on
184 origin:
185
186 ------------------------------------------------
187 $ git fetch origin --prune --prune-tags
188 $ git fetch origin --prune 'refs/tags/*:refs/tags/*'
189 $ git fetch <url of origin> --prune --prune-tags
190 $ git fetch <url of origin> --prune 'refs/tags/*:refs/tags/*'
191 ------------------------------------------------
192
193 OUTPUT
194 ------
195
196 The output of "git fetch" depends on the transport method used; this
197 section describes the output when fetching over the Git protocol
198 (either locally or via ssh) and Smart HTTP protocol.
199
200 The status of the fetch is output in tabular form, with each line
201 representing the status of a single ref. Each line is of the form:
202
203 -------------------------------
204 <flag> <summary> <from> -> <to> [<reason>]
205 -------------------------------
206
207 The status of up-to-date refs is shown only if the --verbose option is
208 used.
209
210 In compact output mode, specified with configuration variable
211 fetch.output, if either entire `<from>` or `<to>` is found in the
212 other string, it will be substituted with `*` in the other string. For
213 example, `master -> origin/master` becomes `master -> origin/*`.
214
215 flag::
216 A single character indicating the status of the ref:
217 (space);; for a successfully fetched fast-forward;
218 `+`;; for a successful forced update;
219 `-`;; for a successfully pruned ref;
220 `t`;; for a successful tag update;
221 `*`;; for a successfully fetched new ref;
222 `!`;; for a ref that was rejected or failed to update; and
223 `=`;; for a ref that was up to date and did not need fetching.
224
225 summary::
226 For a successfully fetched ref, the summary shows the old and new
227 values of the ref in a form suitable for using as an argument to
228 `git log` (this is `<old>..<new>` in most cases, and
229 `<old>...<new>` for forced non-fast-forward updates).
230
231 from::
232 The name of the remote ref being fetched from, minus its
233 `refs/<type>/` prefix. In the case of deletion, the name of
234 the remote ref is "(none)".
235
236 to::
237 The name of the local ref being updated, minus its
238 `refs/<type>/` prefix.
239
240 reason::
241 A human-readable explanation. In the case of successfully fetched
242 refs, no explanation is needed. For a failed ref, the reason for
243 failure is described.
244
245 EXAMPLES
246 --------
247
248 * Update the remote-tracking branches:
249 +
250 ------------------------------------------------
251 $ git fetch origin
252 ------------------------------------------------
253 +
254 The above command copies all branches from the remote refs/heads/
255 namespace and stores them to the local refs/remotes/origin/ namespace,
256 unless the branch.<name>.fetch option is used to specify a non-default
257 refspec.
258
259 * Using refspecs explicitly:
260 +
261 ------------------------------------------------
262 $ git fetch origin +seen:seen maint:tmp
263 ------------------------------------------------
264 +
265 This updates (or creates, as necessary) branches `seen` and `tmp` in
266 the local repository by fetching from the branches (respectively)
267 `seen` and `maint` from the remote repository.
268 +
269 The `seen` branch will be updated even if it does not fast-forward,
270 because it is prefixed with a plus sign; `tmp` will not be.
271
272 * Peek at a remote's branch, without configuring the remote in your local
273 repository:
274 +
275 ------------------------------------------------
276 $ git fetch git://git.kernel.org/pub/scm/git/git.git maint
277 $ git log FETCH_HEAD
278 ------------------------------------------------
279 +
280 The first command fetches the `maint` branch from the repository at
281 `git://git.kernel.org/pub/scm/git/git.git` and the second command uses
282 `FETCH_HEAD` to examine the branch with linkgit:git-log[1]. The fetched
283 objects will eventually be removed by git's built-in housekeeping (see
284 linkgit:git-gc[1]).
285
286 include::transfer-data-leaks.txt[]
287
288 BUGS
289 ----
290 Using --recurse-submodules can only fetch new commits in submodules that are
291 present locally e.g. in `$GIT_DIR/modules/`. If the upstream adds a new
292 submodule, that submodule cannot be fetched until it is cloned e.g. by `git
293 submodule update`. This is expected to be fixed in a future Git version.
294
295 SEE ALSO
296 --------
297 linkgit:git-pull[1]
298
299 GIT
300 ---
301 Part of the linkgit:git[1] suite