Documentation/git-fetch.txt

   1 git-fetch(1)
   2 ============
   3
   4 NAME
   5 ----
   6 git-fetch - Download objects and refs from another repository
   7
   8
   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>]
  16
  17
  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).
  24
  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.
  32
  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]).
  37
  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
  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
  45 OPTIONS
  46 -------
  47 include::fetch-options.txt[]
  48
  49 include::pull-fetch-param.txt[]
  50
  51 include::urls-remotes.txt[]
  52
  53
  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
  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 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
 102 OUTPUT
 103 ------
 104
 105 The output of "git fetch" depends on the transport method used; this
 106 section describes the output when fetching over the Git protocol
 107 (either locally or via ssh) and Smart HTTP protocol.
 108
 109 The status of the fetch is output in tabular form, with each line
 110 representing the status of a single ref. Each line is of the form:
 111
 112 -------------------------------
 113  <flag> <summary> <from> -> <to> [<reason>]
 114 -------------------------------
 115
 116 The status of up-to-date refs is shown only if the --verbose option is
 117 used.
 118
 119 In compact output mode, specified with configuration variable
 120 fetch.output, if either entire `<from>` or `<to>` is found in the
 121 other string, it will be substituted with `*` in the other string. For
 122 example, `master -> origin/master` becomes `master -> origin/*`.
 123
 124 flag::
 125         A single character indicating the status of the ref:
 126 (space);; for a successfully fetched fast-forward;
 127 `+`;; for a successful forced update;
 128 `-`;; for a successfully pruned ref;
 129 `t`;; for a successful tag update;
 130 `*`;; for a successfully fetched new ref;
 131 `!`;; for a ref that was rejected or failed to update; and
 132 `=`;; for a ref that was up to date and did not need fetching.
 133
 134 summary::
 135         For a successfully fetched ref, the summary shows the old and new
 136         values of the ref in a form suitable for using as an argument to
 137         `git log` (this is `<old>..<new>` in most cases, and
 138         `<old>...<new>` for forced non-fast-forward updates).
 139
 140 from::
 141         The name of the remote ref being fetched from, minus its
 142         `refs/<type>/` prefix. In the case of deletion, the name of
 143         the remote ref is "(none)".
 144
 145 to::
 146         The name of the local ref being updated, minus its
 147         `refs/<type>/` prefix.
 148
 149 reason::
 150         A human-readable explanation. In the case of successfully fetched
 151         refs, no explanation is needed. For a failed ref, the reason for
 152         failure is described.
 153
 154 EXAMPLES
 155 --------
 156
 157 * Update the remote-tracking branches:
 158 +
 159 ------------------------------------------------
 160 $ git fetch origin
 161 ------------------------------------------------
 162 +
 163 The above command copies all branches from the remote refs/heads/
 164 namespace and stores them to the local refs/remotes/origin/ namespace,
 165 unless the branch.<name>.fetch option is used to specify a non-default
 166 refspec.
 167
 168 * Using refspecs explicitly:
 169 +
 170 ------------------------------------------------
 171 $ git fetch origin +pu:pu maint:tmp
 172 ------------------------------------------------
 173 +
 174 This updates (or creates, as necessary) branches `pu` and `tmp` in
 175 the local repository by fetching from the branches (respectively)
 176 `pu` and `maint` from the remote repository.
 177 +
 178 The `pu` branch will be updated even if it is does not fast-forward,
 179 because it is prefixed with a plus sign; `tmp` will not be.
 180
 181 * Peek at a remote's branch, without configuring the remote in your local
 182 repository:
 183 +
 184 ------------------------------------------------
 185 $ git fetch git://git.kernel.org/pub/scm/git/git.git maint
 186 $ git log FETCH_HEAD
 187 ------------------------------------------------
 188 +
 189 The first command fetches the `maint` branch from the repository at
 190 `git://git.kernel.org/pub/scm/git/git.git` and the second command uses
 191 `FETCH_HEAD` to examine the branch with linkgit:git-log[1].  The fetched
 192 objects will eventually be removed by git's built-in housekeeping (see
 193 linkgit:git-gc[1]).
 194
 195 BUGS
 196 ----
 197 Using --recurse-submodules can only fetch new commits in already checked
 198 out submodules right now. When e.g. upstream added a new submodule in the
 199 just fetched commits of the superproject the submodule itself can not be
 200 fetched, making it impossible to check out that submodule later without
 201 having to do a fetch again. This is expected to be fixed in a future Git
 202 version.
 203
 204 SEE ALSO
 205 --------
 206 linkgit:git-pull[1]
 207
 208 GIT
 209 ---
 210 Part of the linkgit:git[1] suite