builtin/branch.c: remove useless branch_get
[git/debian.git] / Documentation / git-fetch.txt
blobe3199355978880b21668bc1aff0e42f610c02bd6
1 git-fetch(1)
2 ============
4 NAME
5 ----
6 git-fetch - Download objects and refs from another repository
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>]
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).
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.
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]).
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.
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].
45 OPTIONS
46 -------
47 include::fetch-options.txt[]
49 include::pull-fetch-param.txt[]
51 include::urls-remotes.txt[]
54 CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
55 -------------------------------------------
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.
62 Typically such a variable may look like this:
64 ------------------------------------------------
65 [remote "origin"]
66         fetch = +refs/heads/*:refs/remotes/origin/*
67 ------------------------------------------------
69 This configuration is used in two ways:
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.
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.
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.
102 PRUNING
103 -------
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.
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.
115 These remote-tracking references can be deleted as a one-off with
116 either of:
118 ------------------------------------------------
119 # While fetching
120 $ git fetch --prune <name>
122 # Only prune, don't fetch
123 $ git remote prune <name>
124 ------------------------------------------------
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].
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).
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.
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.
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.
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].
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:
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 ------------------------------------------------
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.
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.
178 Pruning tags with `--prune-tags` also works when fetching a URL
179 instead of a named remote. These will all prune tags not found on
180 origin:
182 ------------------------------------------------
183 $ git fetch origin --prune --prune-tags
184 $ git fetch origin --prune 'refs/tags/*:refs/tags/*'
185 $ git fetch <url of origin> --prune --prune-tags
186 $ git fetch <url of origin> --prune 'refs/tags/*:refs/tags/*'
187 ------------------------------------------------
189 OUTPUT
190 ------
192 The output of "git fetch" depends on the transport method used; this
193 section describes the output when fetching over the Git protocol
194 (either locally or via ssh) and Smart HTTP protocol.
196 The status of the fetch is output in tabular form, with each line
197 representing the status of a single ref. Each line is of the form:
199 -------------------------------
200  <flag> <summary> <from> -> <to> [<reason>]
201 -------------------------------
203 The status of up-to-date refs is shown only if the --verbose option is
204 used.
206 In compact output mode, specified with configuration variable
207 fetch.output, if either entire `<from>` or `<to>` is found in the
208 other string, it will be substituted with `*` in the other string. For
209 example, `master -> origin/master` becomes `master -> origin/*`.
211 flag::
212         A single character indicating the status of the ref:
213 (space);; for a successfully fetched fast-forward;
214 `+`;; for a successful forced update;
215 `-`;; for a successfully pruned ref;
216 `t`;; for a successful tag update;
217 `*`;; for a successfully fetched new ref;
218 `!`;; for a ref that was rejected or failed to update; and
219 `=`;; for a ref that was up to date and did not need fetching.
221 summary::
222         For a successfully fetched ref, the summary shows the old and new
223         values of the ref in a form suitable for using as an argument to
224         `git log` (this is `<old>..<new>` in most cases, and
225         `<old>...<new>` for forced non-fast-forward updates).
227 from::
228         The name of the remote ref being fetched from, minus its
229         `refs/<type>/` prefix. In the case of deletion, the name of
230         the remote ref is "(none)".
232 to::
233         The name of the local ref being updated, minus its
234         `refs/<type>/` prefix.
236 reason::
237         A human-readable explanation. In the case of successfully fetched
238         refs, no explanation is needed. For a failed ref, the reason for
239         failure is described.
241 EXAMPLES
242 --------
244 * Update the remote-tracking branches:
246 ------------------------------------------------
247 $ git fetch origin
248 ------------------------------------------------
250 The above command copies all branches from the remote refs/heads/
251 namespace and stores them to the local refs/remotes/origin/ namespace,
252 unless the branch.<name>.fetch option is used to specify a non-default
253 refspec.
255 * Using refspecs explicitly:
257 ------------------------------------------------
258 $ git fetch origin +pu:pu maint:tmp
259 ------------------------------------------------
261 This updates (or creates, as necessary) branches `pu` and `tmp` in
262 the local repository by fetching from the branches (respectively)
263 `pu` and `maint` from the remote repository.
265 The `pu` branch will be updated even if it is does not fast-forward,
266 because it is prefixed with a plus sign; `tmp` will not be.
268 * Peek at a remote's branch, without configuring the remote in your local
269 repository:
271 ------------------------------------------------
272 $ git fetch git://git.kernel.org/pub/scm/git/git.git maint
273 $ git log FETCH_HEAD
274 ------------------------------------------------
276 The first command fetches the `maint` branch from the repository at
277 `git://git.kernel.org/pub/scm/git/git.git` and the second command uses
278 `FETCH_HEAD` to examine the branch with linkgit:git-log[1].  The fetched
279 objects will eventually be removed by git's built-in housekeeping (see
280 linkgit:git-gc[1]).
282 include::transfer-data-leaks.txt[]
284 BUGS
285 ----
286 Using --recurse-submodules can only fetch new commits in already checked
287 out submodules right now. When e.g. upstream added a new submodule in the
288 just fetched commits of the superproject the submodule itself can not be
289 fetched, making it impossible to check out that submodule later without
290 having to do a fetch again. This is expected to be fixed in a future Git
291 version.
293 SEE ALSO
294 --------
295 linkgit:git-pull[1]
299 Part of the linkgit:git[1] suite