DESCRIPTION
-----------
-Fetches named heads or tags from one or more other repositories,
-along with the objects necessary to complete them.
+Fetch branches and/or tags (collectively, "refs") from one or more
+other repositories, along with the objects necessary to complete their
+histories. Remote-tracking branches are updated (see the description
+of <refspec> below for ways to control this behavior).
-The ref names and their object names of fetched refs are stored
-in `.git/FETCH_HEAD`. This information is left for a later merge
-operation done by 'git merge'.
-
-By default, tags are auto-followed. This means that when fetching
-from a remote, any tags on the remote that point to objects that exist
-in the local repository are fetched. The effect is to fetch tags that
+By default, any tag that points into the histories being fetched is
+also fetched; the effect is to fetch tags that
point at branches that you are interested in. This default behavior
-can be changed by using the --tags or --no-tags options, by
-configuring remote.<name>.tagopt, or by using a refspec that fetches
-tags explicitly.
+can be changed by using the --tags or --no-tags options or by
+configuring remote.<name>.tagopt. By using a refspec that fetches tags
+explicitly, you can fetch tags that do not point into branches you
+are interested in as well.
-'git fetch' can fetch from either a single named repository,
+'git fetch' can fetch from either a single named repository or URL,
or from several repositories at once if <group> is given and
there is a remotes.<group> entry in the configuration file.
(See linkgit:git-config[1]).
When no remote is specified, by default the `origin` remote will be used,
unless there's an upstream branch configured for the current branch.
+The names of refs that are fetched, together with the object names
+they point at, are written to `.git/FETCH_HEAD`. This information
+may be used by scripts or other git commands, such as linkgit:git-pull[1].
+
OPTIONS
-------
include::fetch-options.txt[]
include::urls-remotes.txt[]
+CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
+-------------------------------------------
+
+You often interact with the same remote repository by
+regularly and repeatedly fetching from it. In order to keep track
+of the progress of such a remote repository, `git fetch` allows you
+to configure `remote.<repository>.fetch` configuration variables.
+
+Typically such a variable may look like this:
+
+------------------------------------------------
+[remote "origin"]
+ fetch = +refs/heads/*:refs/remotes/origin/*
+------------------------------------------------
+
+This configuration is used in two ways:
+
+* When `git fetch` is run without specifying what branches
+ and/or tags to fetch on the command line, e.g. `git fetch origin`
+ or `git fetch`, `remote.<repository>.fetch` values are used as
+ the refspecs---they specify which refs to fetch and which local refs
+ to update. The example above will fetch
+ all branches that exist in the `origin` (i.e. any ref that matches
+ the left-hand side of the value, `refs/heads/*`) and update the
+ corresponding remote-tracking branches in the `refs/remotes/origin/*`
+ hierarchy.
+
+* When `git fetch` is run with explicit branches and/or tags
+ to fetch on the command line, e.g. `git fetch origin master`, the
+ <refspec>s given on the command line determine what are to be
+ fetched (e.g. `master` in the example,
+ which is a short-hand for `master:`, which in turn means
+ "fetch the 'master' branch but I do not explicitly say what
+ remote-tracking branch to update with it from the command line"),
+ and the example command will
+ fetch _only_ the 'master' branch. The `remote.<repository>.fetch`
+ values determine which
+ remote-tracking branch, if any, is updated. When used in this
+ way, the `remote.<repository>.fetch` values do not have any
+ effect in deciding _what_ gets fetched (i.e. the values are not
+ used as refspecs when the command-line lists refspecs); they are
+ only used to decide _where_ the refs that are fetched are stored
+ by acting as a mapping.
+
+The latter use of the `remote.<repository>.fetch` values can be
+overridden by giving the `--refmap=<refspec>` parameter(s) on the
+command line.
+
+
EXAMPLES
--------
The `pu` branch will be updated even if it is does not fast-forward,
because it is prefixed with a plus sign; `tmp` will not be.
+* Peek at a remote's branch, without configuring the remote in your local
+repository:
++
+------------------------------------------------
+$ git fetch git://git.kernel.org/pub/scm/git/git.git maint
+$ git log FETCH_HEAD
+------------------------------------------------
++
+The first command fetches the `maint` branch from the repository at
+`git://git.kernel.org/pub/scm/git/git.git` and the second command uses
+`FETCH_HEAD` to examine the branch with linkgit:git-log[1]. The fetched
+objects will eventually be removed by git's built-in housekeeping (see
+linkgit:git-gc[1]).
BUGS
----