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 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 98 99EXAMPLES 100-------- 101 102* Update the remote-tracking branches: 103+ 104------------------------------------------------ 105$ git fetch origin 106------------------------------------------------ 107+ 108The above command copies all branches from the remote refs/heads/ 109namespace and stores them to the local refs/remotes/origin/ namespace, 110unless the branch.<name>.fetch option is used to specify a non-default 111refspec. 112 113* Using refspecs explicitly: 114+ 115------------------------------------------------ 116$ git fetch origin +pu:pu maint:tmp 117------------------------------------------------ 118+ 119This updates (or creates, as necessary) branches `pu` and `tmp` in 120the local repository by fetching from the branches (respectively) 121`pu` and `maint` from the remote repository. 122+ 123The `pu` branch will be updated even if it is does not fast-forward, 124because it is prefixed with a plus sign; `tmp` will not be. 125 126* Peek at a remote's branch, without configuring the remote in your local 127repository: 128+ 129------------------------------------------------ 130$ git fetch git://git.kernel.org/pub/scm/git/git.git maint 131$ git log FETCH_HEAD 132------------------------------------------------ 133+ 134The first command fetches the `maint` branch from the repository at 135`git://git.kernel.org/pub/scm/git/git.git` and the second command uses 136`FETCH_HEAD` to examine the branch with linkgit:git-log[1]. The fetched 137objects will eventually be removed by git's built-in housekeeping (see 138linkgit:git-gc[1]). 139 140BUGS 141---- 142Using --recurse-submodules can only fetch new commits in already checked 143out submodules right now. When e.g. upstream added a new submodule in the 144just fetched commits of the superproject the submodule itself can not be 145fetched, making it impossible to check out that submodule later without 146having to do a fetch again. This is expected to be fixed in a future Git 147version. 148 149SEE ALSO 150-------- 151linkgit:git-pull[1] 152 153GIT 154--- 155Part of the linkgit:git[1] suite