Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 1 | git-fetch(1) |
| 2 | ============ |
| 3 | |
| 4 | NAME |
| 5 | ---- |
Junio C Hamano | 7c73c66 | 2007-01-19 00:37:50 | [diff] [blame] | 6 | git-fetch - Download objects and refs from another repository |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
Junio C Hamano | 15567bc | 2011-07-23 00:51:59 | [diff] [blame] | 11 | [verse] |
Junio C Hamano | 3a869c1 | 2010-04-10 07:53:42 | [diff] [blame] | 12 | 'git fetch' [<options>] [<repository> [<refspec>...]] |
Junio C Hamano | 3a869c1 | 2010-04-10 07:53:42 | [diff] [blame] | 13 | 'git fetch' [<options>] <group> |
Junio C Hamano | d2179ef | 2010-10-22 04:12:17 | [diff] [blame] | 14 | 'git fetch' --multiple [<options>] [(<repository> | <group>)...] |
Junio C Hamano | 3a869c1 | 2010-04-10 07:53:42 | [diff] [blame] | 15 | 'git fetch' --all [<options>] |
Junio C Hamano | 9df0c66 | 2009-11-23 11:09:27 | [diff] [blame] | 16 | |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 17 | |
| 18 | DESCRIPTION |
| 19 | ----------- |
Junio C Hamano | 45f804f | 2014-06-20 22:24:49 | [diff] [blame] | 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). |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 24 | |
Junio C Hamano | 45f804f | 2014-06-20 22:24:49 | [diff] [blame] | 25 | By default, any tag that points into the histories being fetched is |
| 26 | also fetched; the effect is to fetch tags that |
Junio C Hamano | 4c8f2d9 | 2013-12-13 00:55:42 | [diff] [blame] | 27 | point at branches that you are interested in. This default behavior |
Junio C Hamano | 45f804f | 2014-06-20 22:24:49 | [diff] [blame] | 28 | can be changed by using the --tags or --no-tags options or by |
Junio C Hamano | 322c624 | 2015-03-23 21:32:46 | [diff] [blame] | 29 | configuring remote.<name>.tagOpt. By using a refspec that fetches tags |
Junio C Hamano | 45f804f | 2014-06-20 22:24:49 | [diff] [blame] | 30 | explicitly, you can fetch tags that do not point into branches you |
| 31 | are interested in as well. |
Junio C Hamano | 8be7073 | 2007-02-10 01:28:40 | [diff] [blame] | 32 | |
Junio C Hamano | 45f804f | 2014-06-20 22:24:49 | [diff] [blame] | 33 | 'git fetch' can fetch from either a single named repository or URL, |
Junio C Hamano | 9df0c66 | 2009-11-23 11:09:27 | [diff] [blame] | 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]). |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 37 | |
Junio C Hamano | cf77b04 | 2013-12-17 23:54:21 | [diff] [blame] | 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 | |
Junio C Hamano | 45f804f | 2014-06-20 22:24:49 | [diff] [blame] | 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 | |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 45 | OPTIONS |
| 46 | ------- |
| 47 | include::fetch-options.txt[] |
| 48 | |
| 49 | include::pull-fetch-param.txt[] |
| 50 | |
Junio C Hamano | 330aae6 | 2007-07-06 17:01:58 | [diff] [blame] | 51 | include::urls-remotes.txt[] |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 52 | |
Junio C Hamano | c21ab05 | 2009-10-31 04:03:55 | [diff] [blame] | 53 | |
Junio C Hamano | 45f804f | 2014-06-20 22:24:49 | [diff] [blame] | 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 |
Junio C Hamano | ee61580 | 2015-10-29 21:45:26 | [diff] [blame] | 74 | the refspecs--they specify which refs to fetch and which local refs |
Junio C Hamano | 45f804f | 2014-06-20 22:24:49 | [diff] [blame] | 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 | |
Junio C Hamano | 664750f | 2018-03-06 23:25:44 | [diff] [blame] | 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 | 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: |
| 181 | |
| 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 | ------------------------------------------------ |
| 188 | |
Junio C Hamano | 1a1b847 | 2016-07-19 21:37:13 | [diff] [blame] | 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 | |
| 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 | |
| 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. |
| 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. |
Junio C Hamano | 45f804f | 2014-06-20 22:24:49 | [diff] [blame] | 240 | |
Junio C Hamano | c21ab05 | 2009-10-31 04:03:55 | [diff] [blame] | 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 | + |
| 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. |
| 267 | |
Junio C Hamano | 45f804f | 2014-06-20 22:24:49 | [diff] [blame] | 268 | * Peek at a remote's branch, without configuring the remote in your local |
| 269 | repository: |
| 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]). |
Junio C Hamano | c21ab05 | 2009-10-31 04:03:55 | [diff] [blame] | 281 | |
Junio C Hamano | 56ace3d | 2017-01-10 23:43:41 | [diff] [blame] | 282 | include::transfer-data-leaks.txt[] |
| 283 | |
Junio C Hamano | 5cd1518 | 2011-04-05 00:21:10 | [diff] [blame] | 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 |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 290 | having to do a fetch again. This is expected to be fixed in a future Git |
Junio C Hamano | 5cd1518 | 2011-04-05 00:21:10 | [diff] [blame] | 291 | version. |
| 292 | |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 293 | SEE ALSO |
| 294 | -------- |
Junio C Hamano | 35738e8 | 2008-01-07 07:55:46 | [diff] [blame] | 295 | linkgit:git-pull[1] |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 296 | |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 297 | GIT |
| 298 | --- |
Junio C Hamano | f7c042d | 2008-06-06 22:50:53 | [diff] [blame] | 299 | Part of the linkgit:git[1] suite |