GIT 1.6.1.1
[git/git.git] / Documentation / pull-fetch-param.txt
CommitLineData
0c04094b 1<repository>::
bccf5956 2 The "remote" repository that is the source of a fetch
58124733
JF
3 or pull operation. This parameter can be either a URL
4 (see the section <<URLS,GIT URLS>> below) or the name
5 of a remote (see the section <<REMOTES,REMOTES>> below).
ab9b3138
JH
6
7<refspec>::
8 The canonical format of a <refspec> parameter is
0f4f4d15 9 `+?<src>:<dst>`; that is, an optional plus `{plus}`, followed
bccf5956 10 by the source ref, followed by a colon `:`, followed by
ab9b3138 11 the destination ref.
df8baa42 12+
3598a308 13The remote ref that matches <src>
df8baa42
JF
14is fetched, and if <dst> is not empty string, the local
15ref that matches it is fast forwarded using <src>.
bccf5956 16Again, if the optional plus `+` is used, the local ref
df8baa42
JF
17is updated even if it does not result in a fast forward
18update.
19+
bccf5956
JL
20[NOTE]
21If the remote branch from which you want to pull is
22modified in non-linear ways such as being rewound and
23rebased frequently, then a pull will attempt a merge with
24an older version of itself, likely conflict, and fail.
25It is under these conditions that you would want to use
26the `+` sign to indicate non-fast-forward updates will
27be needed. There is currently no easy way to determine
28or declare that a branch will be made available in a
29repository with this behavior; the pulling user simply
30must know this is the expected usage pattern for a branch.
31+
32[NOTE]
33You never do your own development on branches that appear
34on the right hand side of a <refspec> colon on `Pull:` lines;
ba020ef5 35they are to be updated by 'git-fetch'. If you intend to do
4607166d
JH
36development derived from a remote branch `B`, have a `Pull:`
37line to track it (i.e. `Pull: B:remote-B`), and have a separate
38branch `my-B` to do your development on top of it. The latter
39is created by `git branch my-B remote-B` (or its equivalent `git
40checkout -b my-B remote-B`). Run `git fetch` to keep track of
41the progress of the remote side, and when you see something new
42on the remote branch, merge it into your development branch with
43`git pull . remote-B`, while you are on `my-B` branch.
bccf5956 44+
fdd08979
JH
45[NOTE]
46There is a difference between listing multiple <refspec>
ba020ef5 47directly on 'git-pull' command line and having multiple
fdd08979 48`Pull:` <refspec> lines for a <repository> and running
ba020ef5 49'git-pull' command without any explicit <refspec> parameters.
fdd08979
JH
50<refspec> listed explicitly on the command line are always
51merged into the current branch after fetching. In other words,
52if you list more than one remote refs, you would be making
ba020ef5 53an Octopus. While 'git-pull' run without any explicit <refspec>
fdd08979
JH
54parameter takes default <refspec>s from `Pull:` lines, it
55merges only the first <refspec> found into the current branch,
56after fetching all the remote refs. This is because making an
57Octopus from remote refs is rarely done, while keeping track
58of multiple remote heads in one-go by fetching more than one
59is often useful.
60+
df8baa42
JF
61Some short-cut notations are also supported.
62+
a6080a0a 63* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`;
3598a308 64 it requests fetching everything up to the given tag.
df8baa42 65* A parameter <ref> without a colon is equivalent to
3598a308
BF
66 <ref>: when pulling/fetching, so it merges <ref> into the current
67 branch without storing the remote branch anywhere locally