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