mirror of
https://github.com/git/git
synced 2024-08-25 10:45:59 +00:00
![Junio C Hamano](/assets/img/avatar_default.png)
AsciiDoc markup fixes. * jc/em-dash-in-doc: Documentation: AsciiDoc spells em-dash as double-dashes, not triple
160 lines
5.6 KiB
Plaintext
160 lines
5.6 KiB
Plaintext
git-fetch(1)
|
|
============
|
|
|
|
NAME
|
|
----
|
|
git-fetch - Download objects and refs from another repository
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'git fetch' [<options>] [<repository> [<refspec>...]]
|
|
'git fetch' [<options>] <group>
|
|
'git fetch' --multiple [<options>] [(<repository> | <group>)...]
|
|
'git fetch' --all [<options>]
|
|
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
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).
|
|
|
|
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 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 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::pull-fetch-param.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
|
|
--------
|
|
|
|
* Update the remote-tracking branches:
|
|
+
|
|
------------------------------------------------
|
|
$ git fetch origin
|
|
------------------------------------------------
|
|
+
|
|
The above command copies all branches from the remote refs/heads/
|
|
namespace and stores them to the local refs/remotes/origin/ namespace,
|
|
unless the branch.<name>.fetch option is used to specify a non-default
|
|
refspec.
|
|
|
|
* Using refspecs explicitly:
|
|
+
|
|
------------------------------------------------
|
|
$ git fetch origin +pu:pu maint:tmp
|
|
------------------------------------------------
|
|
+
|
|
This updates (or creates, as necessary) branches `pu` and `tmp` in
|
|
the local repository by fetching from the branches (respectively)
|
|
`pu` and `maint` from the remote repository.
|
|
+
|
|
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
|
|
----
|
|
Using --recurse-submodules can only fetch new commits in already checked
|
|
out submodules right now. When e.g. upstream added a new submodule in the
|
|
just fetched commits of the superproject the submodule itself can not be
|
|
fetched, making it impossible to check out that submodule later without
|
|
having to do a fetch again. This is expected to be fixed in a future Git
|
|
version.
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkgit:git-pull[1]
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|