1git-fetch(1) 2============ 3 4NAME 5---- 6git-fetch - Download objects and refs from another repository 7 8 9SYNOPSIS 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 18DESCRIPTION 19----------- 20Fetch branches and/or tags (collectively, "refs") from one or more 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). 24 25By default, any tag that points into the histories being fetched is 26also fetched; the effect is to fetch tags that 27point at branches that you are interested in. This default behavior 28can be changed by using the --tags or --no-tags options or by 29configuring remote.<name>.tagopt. By using a refspec that fetches tags 30explicitly, you can fetch tags that do not point into branches you 31are interested in as well. 32 33'git fetch' can fetch from either a single named repository or URL, 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]). 37 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 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 45OPTIONS 46------- 47include::fetch-options.txt[] 48 49include::pull-fetch-param.txt[] 50 51include::urls-remotes.txt[] 52 53 54CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]] 55------------------------------------------- 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 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 98The latter use of the `remote.<repository>.fetch` values can be 99overridden by giving the `--refmap=<refspec>` parameter(s) on the 100command line. 101 102 103EXAMPLES 104-------- 105 106* Update the remote-tracking branches: 107+ 108------------------------------------------------ 109$ git fetch origin 110------------------------------------------------ 111+ 112The above command copies all branches from the remote refs/heads/ 113namespace and stores them to the local refs/remotes/origin/ namespace, 114unless the branch.<name>.fetch option is used to specify a non-default 115refspec. 116 117* Using refspecs explicitly: 118+ 119------------------------------------------------ 120$ git fetch origin +pu:pu maint:tmp 121------------------------------------------------ 122+ 123This updates (or creates, as necessary) branches `pu` and `tmp` in 124the local repository by fetching from the branches (respectively) 125`pu` and `maint` from the remote repository. 126+ 127The `pu` branch will be updated even if it is does not fast-forward, 128because it is prefixed with a plus sign; `tmp` will not be. 129 130* Peek at a remote's branch, without configuring the remote in your local 131repository: 132+ 133------------------------------------------------ 134$ git fetch git://git.kernel.org/pub/scm/git/git.git maint 135$ git log FETCH_HEAD 136------------------------------------------------ 137+ 138The first command fetches the `maint` branch from the repository at 139`git://git.kernel.org/pub/scm/git/git.git` and the second command uses 140`FETCH_HEAD` to examine the branch with linkgit:git-log[1]. The fetched 141objects will eventually be removed by git's built-in housekeeping (see 142linkgit:git-gc[1]). 143 144BUGS 145---- 146Using --recurse-submodules can only fetch new commits in already checked 147out submodules right now. When e.g. upstream added a new submodule in the 148just fetched commits of the superproject the submodule itself can not be 149fetched, making it impossible to check out that submodule later without 150having to do a fetch again. This is expected to be fixed in a future Git 151version. 152 153SEE ALSO 154-------- 155linkgit:git-pull[1] 156 157GIT 158--- 159Part of the linkgit:git[1] suite