]>
Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-fetch(1) |
2 | ============ | |
0c04094b JH |
3 | |
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-fetch - Download objects and refs from another repository |
0c04094b JH |
7 | |
8 | ||
9 | SYNOPSIS | |
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 | |
18 | DESCRIPTION | |
19 | ----------- | |
53284560 | 20 | Fetch branches and/or tags (collectively, "refs") from one or more |
366a0184 MB |
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). | |
0c04094b | 24 | |
53284560 JH |
25 | By default, any tag that points into the histories being fetched is |
26 | also fetched; the effect is to fetch tags that | |
37f0dcbd | 27 | point at branches that you are interested in. This default behavior |
53284560 | 28 | can be changed by using the --tags or --no-tags options or by |
da0005b8 | 29 | configuring remote.<name>.tagOpt. By using a refspec that fetches tags |
53284560 JH |
30 | explicitly, you can fetch tags that do not point into branches you |
31 | are interested in as well. | |
02f571c7 | 32 | |
366a0184 | 33 | 'git fetch' can fetch from either a single named repository or URL, |
9c4a036b BG |
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]). | |
0c04094b | 37 | |
379484b5 FC |
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 | ||
366a0184 MB |
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 | ||
0c04094b JH |
45 | OPTIONS |
46 | ------- | |
93d69d86 | 47 | include::fetch-options.txt[] |
0c04094b | 48 | |
93d69d86 | 49 | include::pull-fetch-param.txt[] |
d6a73596 | 50 | |
37ba0561 | 51 | include::urls-remotes.txt[] |
0c04094b | 52 | |
d504f697 | 53 | |
db4e4113 MB |
54 | CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]] |
55 | ------------------------------------------- | |
fcb14b0c JH |
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 | |
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 |
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 | ||
2c72ed74 ÆAB |
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 | ||
97716d21 ÆAB |
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 | ||
6317972c ÆAB |
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: | |
97716d21 ÆAB |
181 | |
182 | ------------------------------------------------ | |
183 | $ git fetch origin --prune --prune-tags | |
6317972c ÆAB |
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/*' | |
97716d21 ÆAB |
187 | ------------------------------------------------ |
188 | ||
a52397cc NTND |
189 | OUTPUT |
190 | ------ | |
191 | ||
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. | |
195 | ||
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: | |
198 | ||
199 | ------------------------------- | |
200 | <flag> <summary> <from> -> <to> [<reason>] | |
201 | ------------------------------- | |
202 | ||
203 | The status of up-to-date refs is shown only if the --verbose option is | |
204 | used. | |
205 | ||
bc437d10 NTND |
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/*`. | |
210 | ||
a52397cc NTND |
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; | |
2cb040ba NTND |
215 | `-`;; for a successfully pruned ref; |
216 | `t`;; for a successful tag update; | |
a52397cc NTND |
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. | |
220 | ||
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). | |
226 | ||
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)". | |
231 | ||
232 | to:: | |
233 | The name of the local ref being updated, minus its | |
234 | `refs/<type>/` prefix. | |
235 | ||
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. | |
fcb14b0c | 240 | |
d504f697 CB |
241 | EXAMPLES |
242 | -------- | |
243 | ||
244 | * Update the remote-tracking branches: | |
245 | + | |
246 | ------------------------------------------------ | |
247 | $ git fetch origin | |
248 | ------------------------------------------------ | |
249 | + | |
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. | |
254 | ||
255 | * Using refspecs explicitly: | |
256 | + | |
257 | ------------------------------------------------ | |
258 | $ git fetch origin +pu:pu maint:tmp | |
259 | ------------------------------------------------ | |
260 | + | |
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. | |
264 | + | |
6d169227 | 265 | The `pu` branch will be updated even if it does not fast-forward, |
d504f697 CB |
266 | because it is prefixed with a plus sign; `tmp` will not be. |
267 | ||
366a0184 | 268 | * Peek at a remote's branch, without configuring the remote in your local |
ba170517 | 269 | repository: |
366a0184 MB |
270 | + |
271 | ------------------------------------------------ | |
272 | $ git fetch git://git.kernel.org/pub/scm/git/git.git maint | |
273 | $ git log FETCH_HEAD | |
274 | ------------------------------------------------ | |
275 | + | |
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]). | |
d504f697 | 281 | |
235ec243 MM |
282 | include::transfer-data-leaks.txt[] |
283 | ||
794a3592 JL |
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 | |
6d169227 | 288 | just fetched commits of the superproject the submodule itself cannot be |
794a3592 | 289 | fetched, making it impossible to check out that submodule later without |
2de9b711 | 290 | having to do a fetch again. This is expected to be fixed in a future Git |
794a3592 JL |
291 | version. |
292 | ||
fdd08979 JH |
293 | SEE ALSO |
294 | -------- | |
5162e697 | 295 | linkgit:git-pull[1] |
fdd08979 | 296 | |
0c04094b JH |
297 | GIT |
298 | --- | |
9e1f0a85 | 299 | Part of the linkgit:git[1] suite |