fetch: add a --prune-tags option and fetch.pruneTags config
[git/git.git] / Documentation / git-fetch.txt
CommitLineData
215a7ad1
JH
1git-fetch(1)
2============
0c04094b
JH
3
4NAME
5----
c3f0baac 6git-fetch - Download objects and refs from another repository
0c04094b
JH
7
8
9SYNOPSIS
10--------
7791a1d9 11[verse]
e3163c75 12'git fetch' [<options>] [<repository> [<refspec>...]]
e3163c75 13'git fetch' [<options>] <group>
0adda936 14'git fetch' --multiple [<options>] [(<repository> | <group>)...]
e3163c75 15'git fetch' --all [<options>]
9c4a036b 16
0c04094b
JH
17
18DESCRIPTION
19-----------
53284560 20Fetch branches and/or tags (collectively, "refs") from one or more
366a0184
MB
21other repositories, along with the objects necessary to complete their
22histories. Remote-tracking branches are updated (see the description
23of <refspec> below for ways to control this behavior).
0c04094b 24
53284560
JH
25By default, any tag that points into the histories being fetched is
26also fetched; the effect is to fetch tags that
37f0dcbd 27point at branches that you are interested in. This default behavior
53284560 28can be changed by using the --tags or --no-tags options or by
da0005b8 29configuring remote.<name>.tagOpt. By using a refspec that fetches tags
53284560
JH
30explicitly, you can fetch tags that do not point into branches you
31are interested in as well.
02f571c7 32
366a0184 33'git fetch' can fetch from either a single named repository or URL,
9c4a036b
BG
34or from several repositories at once if <group> is given and
35there is a remotes.<group> entry in the configuration file.
36(See linkgit:git-config[1]).
0c04094b 37
379484b5
FC
38When no remote is specified, by default the `origin` remote will be used,
39unless there's an upstream branch configured for the current branch.
40
366a0184
MB
41The names of refs that are fetched, together with the object names
42they point at, are written to `.git/FETCH_HEAD`. This information
43may be used by scripts or other git commands, such as linkgit:git-pull[1].
44
0c04094b
JH
45OPTIONS
46-------
93d69d86 47include::fetch-options.txt[]
0c04094b 48
93d69d86 49include::pull-fetch-param.txt[]
d6a73596 50
37ba0561 51include::urls-remotes.txt[]
0c04094b 52
d504f697 53
db4e4113
MB
54CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
55-------------------------------------------
fcb14b0c
JH
56
57You often interact with the same remote repository by
58regularly and repeatedly fetching from it. In order to keep track
59of the progress of such a remote repository, `git fetch` allows you
60to configure `remote.<repository>.fetch` configuration variables.
61
62Typically such a variable may look like this:
63
64------------------------------------------------
65[remote "origin"]
66 fetch = +refs/heads/*:refs/remotes/origin/*
67------------------------------------------------
68
69This 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
3b19dba7 74 the refspecs--they specify which refs to fetch and which local refs
fcb14b0c
JH
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
c5558f80
JH
98The latter use of the `remote.<repository>.fetch` values can be
99overridden by giving the `--refmap=<refspec>` parameter(s) on the
100command line.
101
2c72ed74
ÆAB
102PRUNING
103-------
104
105Git has a default disposition of keeping data unless it's explicitly
106thrown away; this extends to holding onto local references to branches
107on remotes that have themselves deleted those branches.
108
109If left to accumulate, these stale references might make performance
110worse on big and busy repos that have a lot of branch churn, and
111e.g. make the output of commands like `git branch -a --contains
112<commit>` needlessly verbose, as well as impacting anything else
113that'll work with the complete set of known references.
114
115These remote-tracking references can be deleted as a one-off with
116either 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
126To prune references as part of your normal workflow without needing to
127remember to run that, set `fetch.prune` globally, or
128`remote.<name>.prune` per-remote in the config. See
129linkgit:git-config[1].
130
131Here's where things get tricky and more specific. The pruning feature
132doesn't actually care about branches, instead it'll prune local <->
133remote-references as a function of the refspec of the remote (see
134`<refspec>` and <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> above).
135
136Therefore if the refspec for the remote includes
137e.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
139tracking branches that are deleted, but any local tag that doesn't
140exist on the remote.
141
142This 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
144from it you delete all your local tags, most of which may not have
145come from the `<name>` remote in the first place.
146
147So be careful when using this with a refspec like
148`refs/tags/*:refs/tags/*`, or any other refspec which might map
149references from multiple remotes to the same local namespace.
150
97716d21
ÆAB
151Since keeping up-to-date with both branches and tags on the remote is
152a 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
154force-update those tags that differ. Tag pruning can also be enabled
155with `fetch.pruneTags` or `remote.<name>.pruneTags` in the config. See
156linkgit:git-config[1].
157
158The `--prune-tags` option is equivalent to having
159`refs/tags/*:refs/tags/*` declared in the refspecs of the remote. This
160can 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
168The reason it doesn't error out when provided without `--prune` or its
169config versions is for flexibility of the configured versions, and to
170maintain a 1=1 mapping between what the command line flags do, and
171what the configuration versions do.
172
173It's reasonable to e.g. configure `fetch.pruneTags=true` in
174`~/.gitconfig` to have tags pruned whenever `git fetch --prune` is
175run, without making every invocation of `git fetch` without `--prune`
176an error.
177
178Another special case of `--prune-tags` is that
179`refs/tags/*:refs/tags/*` will not be implicitly provided if an URL is
180being fetched. I.e.:
181
182------------------------------------------------
183$ git fetch <url> --prune --prune-tags
184------------------------------------------------
185
186Will prune no tags, as opposed to:
187
188------------------------------------------------
189$ git fetch origin --prune --prune-tags
190------------------------------------------------
191
192To prune tags given a URL supply the refspec explicitly:
193
194------------------------------------------------
195$ git fetch <url> --prune 'refs/tags/*:refs/tags/*'
196------------------------------------------------
197
a52397cc
NTND
198OUTPUT
199------
200
201The output of "git fetch" depends on the transport method used; this
202section describes the output when fetching over the Git protocol
203(either locally or via ssh) and Smart HTTP protocol.
204
205The status of the fetch is output in tabular form, with each line
206representing the status of a single ref. Each line is of the form:
207
208-------------------------------
209 <flag> <summary> <from> -> <to> [<reason>]
210-------------------------------
211
212The status of up-to-date refs is shown only if the --verbose option is
213used.
214
bc437d10
NTND
215In compact output mode, specified with configuration variable
216fetch.output, if either entire `<from>` or `<to>` is found in the
217other string, it will be substituted with `*` in the other string. For
218example, `master -> origin/master` becomes `master -> origin/*`.
219
a52397cc
NTND
220flag::
221 A single character indicating the status of the ref:
222(space);; for a successfully fetched fast-forward;
223`+`;; for a successful forced update;
2cb040ba
NTND
224`-`;; for a successfully pruned ref;
225`t`;; for a successful tag update;
a52397cc
NTND
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
230summary::
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
236from::
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
241to::
242 The name of the local ref being updated, minus its
243 `refs/<type>/` prefix.
244
245reason::
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.
fcb14b0c 249
d504f697
CB
250EXAMPLES
251--------
252
253* Update the remote-tracking branches:
254+
255------------------------------------------------
256$ git fetch origin
257------------------------------------------------
258+
259The above command copies all branches from the remote refs/heads/
260namespace and stores them to the local refs/remotes/origin/ namespace,
261unless the branch.<name>.fetch option is used to specify a non-default
262refspec.
263
264* Using refspecs explicitly:
265+
266------------------------------------------------
267$ git fetch origin +pu:pu maint:tmp
268------------------------------------------------
269+
270This updates (or creates, as necessary) branches `pu` and `tmp` in
271the local repository by fetching from the branches (respectively)
272`pu` and `maint` from the remote repository.
273+
274The `pu` branch will be updated even if it is does not fast-forward,
275because it is prefixed with a plus sign; `tmp` will not be.
276
366a0184
MB
277* Peek at a remote's branch, without configuring the remote in your local
278repository:
279+
280------------------------------------------------
281$ git fetch git://git.kernel.org/pub/scm/git/git.git maint
282$ git log FETCH_HEAD
283------------------------------------------------
284+
285The 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
288objects will eventually be removed by git's built-in housekeeping (see
289linkgit:git-gc[1]).
d504f697 290
235ec243
MM
291include::transfer-data-leaks.txt[]
292
794a3592
JL
293BUGS
294----
295Using --recurse-submodules can only fetch new commits in already checked
296out submodules right now. When e.g. upstream added a new submodule in the
297just fetched commits of the superproject the submodule itself can not be
298fetched, making it impossible to check out that submodule later without
2de9b711 299having to do a fetch again. This is expected to be fixed in a future Git
794a3592
JL
300version.
301
fdd08979
JH
302SEE ALSO
303--------
5162e697 304linkgit:git-pull[1]
fdd08979 305
0c04094b
JH
306GIT
307---
9e1f0a85 308Part of the linkgit:git[1] suite