dir.h: move struct exclude declaration to top level
[git.git] / Documentation / git-fetch.txt
blob8deb61469d9cbd8786c27567851158c90c31aa8a
1 git-fetch(1)
2 ============
4 NAME
5 ----
6 git-fetch - Download objects and refs from another repository
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>]
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).
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.
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]).
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.
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].
45 OPTIONS
46 -------
47 include::fetch-options.txt[]
49 include::pull-fetch-param.txt[]
51 include::urls-remotes.txt[]
54 CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
55 -------------------------------------------
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.
62 Typically such a variable may look like this:
64 ------------------------------------------------
65 [remote "origin"]
66         fetch = +refs/heads/*:refs/remotes/origin/*
67 ------------------------------------------------
69 This configuration is used in two ways:
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.
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.
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.
103 EXAMPLES
104 --------
106 * Update the remote-tracking branches:
108 ------------------------------------------------
109 $ git fetch origin
110 ------------------------------------------------
112 The above command copies all branches from the remote refs/heads/
113 namespace and stores them to the local refs/remotes/origin/ namespace,
114 unless the branch.<name>.fetch option is used to specify a non-default
115 refspec.
117 * Using refspecs explicitly:
119 ------------------------------------------------
120 $ git fetch origin +pu:pu maint:tmp
121 ------------------------------------------------
123 This updates (or creates, as necessary) branches `pu` and `tmp` in
124 the local repository by fetching from the branches (respectively)
125 `pu` and `maint` from the remote repository.
127 The `pu` branch will be updated even if it is does not fast-forward,
128 because it is prefixed with a plus sign; `tmp` will not be.
130 * Peek at a remote's branch, without configuring the remote in your local
131 repository:
133 ------------------------------------------------
134 $ git fetch git://git.kernel.org/pub/scm/git/git.git maint
135 $ git log FETCH_HEAD
136 ------------------------------------------------
138 The first command fetches the `maint` branch from the repository at
139 `git://git.kernel.org/pub/scm/git/git.git` and the second command uses
140 `FETCH_HEAD` to examine the branch with linkgit:git-log[1].  The fetched
141 objects will eventually be removed by git's built-in housekeeping (see
142 linkgit:git-gc[1]).
144 BUGS
145 ----
146 Using --recurse-submodules can only fetch new commits in already checked
147 out submodules right now. When e.g. upstream added a new submodule in the
148 just fetched commits of the superproject the submodule itself can not be
149 fetched, making it impossible to check out that submodule later without
150 having to do a fetch again. This is expected to be fixed in a future Git
151 version.
153 SEE ALSO
154 --------
155 linkgit:git-pull[1]
159 Part of the linkgit:git[1] suite