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