git.oblomov.eu Git - git/blob - 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. This can
  40 be configured with `fetch.default`.
  41
  42 The names of refs that are fetched, together with the object names
  43 they point at, are written to `.git/FETCH_HEAD`.  This information
  44 may be used by scripts or other git commands, such as linkgit:git-pull[1].
  45
  46 OPTIONS
  47 -------
  48 include::fetch-options.txt[]
  49
  50 include::pull-fetch-param.txt[]
  51
  52 include::urls-remotes.txt[]
  53
  54
  55 CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
  56 -------------------------------------------
  57
  58 You often interact with the same remote repository by
  59 regularly and repeatedly fetching from it.  In order to keep track
  60 of the progress of such a remote repository, `git fetch` allows you
  61 to configure `remote.<repository>.fetch` configuration variables.
  62
  63 Typically such a variable may look like this:
  64
  65 ------------------------------------------------
  66 [remote "origin"]
  67         fetch = +refs/heads/*:refs/remotes/origin/*
  68 ------------------------------------------------
  69
  70 This configuration is used in two ways:
  71
  72 * When `git fetch` is run without specifying what branches
  73   and/or tags to fetch on the command line, e.g. `git fetch origin`
  74   or `git fetch`, `remote.<repository>.fetch` values are used as
  75   the refspecs--they specify which refs to fetch and which local refs
  76   to update.  The example above will fetch
  77   all branches that exist in the `origin` (i.e. any ref that matches
  78   the left-hand side of the value, `refs/heads/*`) and update the
  79   corresponding remote-tracking branches in the `refs/remotes/origin/*`
  80   hierarchy.
  81
  82 * When `git fetch` is run with explicit branches and/or tags
  83   to fetch on the command line, e.g. `git fetch origin master`, the
  84   <refspec>s given on the command line determine what are to be
  85   fetched (e.g. `master` in the example,
  86   which is a short-hand for `master:`, which in turn means
  87   "fetch the 'master' branch but I do not explicitly say what
  88   remote-tracking branch to update with it from the command line"),
  89   and the example command will
  90   fetch _only_ the 'master' branch.  The `remote.<repository>.fetch`
  91   values determine which
  92   remote-tracking branch, if any, is updated.  When used in this
  93   way, the `remote.<repository>.fetch` values do not have any
  94   effect in deciding _what_ gets fetched (i.e. the values are not
  95   used as refspecs when the command-line lists refspecs); they are
  96   only used to decide _where_ the refs that are fetched are stored
  97   by acting as a mapping.
  98
  99 The latter use of the `remote.<repository>.fetch` values can be
 100 overridden by giving the `--refmap=<refspec>` parameter(s) on the
 101 command line.
 102
 103
 104 EXAMPLES
 105 --------
 106
 107 * Update the remote-tracking branches:
 108 +
 109 ------------------------------------------------
 110 $ git fetch origin
 111 ------------------------------------------------
 112 +
 113 The above command copies all branches from the remote refs/heads/
 114 namespace and stores them to the local refs/remotes/origin/ namespace,
 115 unless the branch.<name>.fetch option is used to specify a non-default
 116 refspec.
 117
 118 * Using refspecs explicitly:
 119 +
 120 ------------------------------------------------
 121 $ git fetch origin +pu:pu maint:tmp
 122 ------------------------------------------------
 123 +
 124 This updates (or creates, as necessary) branches `pu` and `tmp` in
 125 the local repository by fetching from the branches (respectively)
 126 `pu` and `maint` from the remote repository.
 127 +
 128 The `pu` branch will be updated even if it is does not fast-forward,
 129 because it is prefixed with a plus sign; `tmp` will not be.
 130
 131 * Peek at a remote's branch, without configuring the remote in your local
 132 repository:
 133 +
 134 ------------------------------------------------
 135 $ git fetch git://git.kernel.org/pub/scm/git/git.git maint
 136 $ git log FETCH_HEAD
 137 ------------------------------------------------
 138 +
 139 The first command fetches the `maint` branch from the repository at
 140 `git://git.kernel.org/pub/scm/git/git.git` and the second command uses
 141 `FETCH_HEAD` to examine the branch with linkgit:git-log[1].  The fetched
 142 objects will eventually be removed by git's built-in housekeeping (see
 143 linkgit:git-gc[1]).
 144
 145 BUGS
 146 ----
 147 Using --recurse-submodules can only fetch new commits in already checked
 148 out submodules right now. When e.g. upstream added a new submodule in the
 149 just fetched commits of the superproject the submodule itself can not be
 150 fetched, making it impossible to check out that submodule later without
 151 having to do a fetch again. This is expected to be fixed in a future Git
 152 version.
 153
 154 SEE ALSO
 155 --------
 156 linkgit:git-pull[1]
 157
 158 GIT
 159 ---
 160 Part of the linkgit:git[1] suite