]>
Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-pull(1) |
2 | =========== | |
2cf565c5 DG |
3 | |
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-pull - Fetch from and merge with another repository or a local branch |
2cf565c5 DG |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
3f8fc184 | 11 | 'git pull' [options] [<repository> [<refspec>...]] |
0c04094b | 12 | |
2cf565c5 DG |
13 | |
14 | DESCRIPTION | |
15 | ----------- | |
ab9b3138 | 16 | |
3f8fc184 JN |
17 | Incorporates changes from a remote repository into the current |
18 | branch. In its default mode, `git pull` is shorthand for | |
19 | `git fetch` followed by `git merge FETCH_HEAD`. | |
0c04094b | 20 | |
3f8fc184 JN |
21 | More precisely, 'git pull' runs 'git fetch' with the given |
22 | parameters and calls 'git merge' to merge the retrieved branch | |
23 | heads into the current branch. | |
24 | With `--rebase`, it runs 'git rebase' instead of 'git merge'. | |
93d69d86 | 25 | |
3f8fc184 JN |
26 | <repository> should be the name of a remote repository as |
27 | passed to linkgit:git-fetch[1]. <refspec> can name an | |
28 | arbitrary remote ref (for example, the name of a tag) or even | |
29 | a collection of refs with corresponding remote tracking branches | |
3bae8d4d JN |
30 | (e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}), |
31 | but usually it is the name of a branch in the remote repository. | |
3f8fc184 JN |
32 | |
33 | Default values for <repository> and <branch> are read from the | |
34 | "remote" and "merge" configuration for the current branch | |
35 | as set by linkgit:git-branch[1] `--track`. | |
36 | ||
37 | Assume the following history exists and the current branch is | |
38 | "`master`": | |
39 | ||
40 | ------------ | |
41 | A---B---C master on origin | |
42 | / | |
43 | D---E---F---G master | |
44 | ------------ | |
45 | ||
46 | Then "`git pull`" will fetch and replay the changes from the remote | |
47 | `master` branch since it diverged from the local `master` (i.e., `E`) | |
48 | until its current commit (`C`) on top of `master` and record the | |
49 | result in a new commit along with the names of the two parent commits | |
50 | and a log message from the user describing the changes. | |
51 | ||
52 | ------------ | |
53 | A---B---C remotes/origin/master | |
54 | / \ | |
55 | D---E---F---G---H master | |
56 | ------------ | |
57 | ||
58 | See linkgit:git-merge[1] for details, including how conflicts | |
59 | are presented and handled. | |
60 | ||
61 | In git 1.7.0 or later, to cancel a conflicting merge, use | |
62 | `git reset --merge`. *Warning*: In older versions of git, running 'git pull' | |
e330d8ca | 63 | with uncommitted changes is discouraged: while possible, it leaves you |
3f8fc184 JN |
64 | in a state that may be hard to back out of in the case of a conflict. |
65 | ||
66 | If any of the remote changes overlap with local uncommitted changes, | |
67 | the merge will be automatically cancelled and the work tree untouched. | |
68 | It is generally best to get any local changes in working order before | |
69 | pulling or stash them away with linkgit:git-stash[1]. | |
e330d8ca | 70 | |
0c04094b JH |
71 | OPTIONS |
72 | ------- | |
3f7a9b5a | 73 | |
3f8fc184 JN |
74 | Options meant for 'git pull' itself and the underlying 'git merge' |
75 | must be given before the options meant for 'git fetch'. | |
76 | ||
409b8d82 TRC |
77 | -q:: |
78 | --quiet:: | |
9839018e TRC |
79 | This is passed to both underlying git-fetch to squelch reporting of |
80 | during transfer, and underlying git-merge to squelch output during | |
81 | merging. | |
409b8d82 TRC |
82 | |
83 | -v:: | |
84 | --verbose:: | |
85 | Pass --verbose to git-fetch and git-merge. | |
86 | ||
3f7a9b5a JA |
87 | Options related to merging |
88 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
89 | ||
93d69d86 | 90 | include::merge-options.txt[] |
2cf565c5 | 91 | |
10eb64f5 | 92 | :git-pull: 1 |
37465016 | 93 | |
3240240f | 94 | --rebase:: |
11fe3f73 MZ |
95 | Rebase the current branch on top of the upstream branch after |
96 | fetching. If there is a remote-tracking branch corresponding to | |
97 | the upstream branch and the upstream branch was rebased since last | |
98 | fetched, the rebase uses that information to avoid rebasing | |
99 | non-local changes. | |
100 | + | |
101 | See `branch.<name>.rebase` in linkgit:git-config[1] if you want to make | |
102 | `git pull` always use `{litdd}rebase` instead of merging. | |
473d3316 | 103 | + |
6bfa3c99 JH |
104 | [NOTE] |
105 | This is a potentially _dangerous_ mode of operation. | |
473d3316 JH |
106 | It rewrites history, which does not bode well when you |
107 | published that history already. Do *not* use this option | |
108 | unless you have read linkgit:git-rebase[1] carefully. | |
cd67e4d4 | 109 | |
3240240f SB |
110 | --no-rebase:: |
111 | Override earlier --rebase. | |
cd67e4d4 | 112 | |
3f7a9b5a JA |
113 | Options related to fetching |
114 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
115 | ||
a288394e JS |
116 | include::fetch-options.txt[] |
117 | ||
118 | include::pull-fetch-param.txt[] | |
119 | ||
120 | include::urls-remotes.txt[] | |
121 | ||
122 | include::merge-strategies.txt[] | |
123 | ||
9e2586ff JH |
124 | DEFAULT BEHAVIOUR |
125 | ----------------- | |
126 | ||
127 | Often people use `git pull` without giving any parameter. | |
128 | Traditionally, this has been equivalent to saying `git pull | |
129 | origin`. However, when configuration `branch.<name>.remote` is | |
130 | present while on branch `<name>`, that value is used instead of | |
131 | `origin`. | |
132 | ||
133 | In order to determine what URL to use to fetch from, the value | |
134 | of the configuration `remote.<origin>.url` is consulted | |
135 | and if there is not any such variable, the value on `URL: ` line | |
136 | in `$GIT_DIR/remotes/<origin>` file is used. | |
137 | ||
138 | In order to determine what remote branches to fetch (and | |
139 | optionally store in the tracking branches) when the command is | |
140 | run without any refspec parameters on the command line, values | |
141 | of the configuration variable `remote.<origin>.fetch` are | |
142 | consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>` | |
143 | file is consulted and its `Pull: ` lines are used. | |
144 | In addition to the refspec formats described in the OPTIONS | |
145 | section, you can have a globbing refspec that looks like this: | |
146 | ||
147 | ------------ | |
148 | refs/heads/*:refs/remotes/origin/* | |
149 | ------------ | |
150 | ||
151 | A globbing refspec must have a non-empty RHS (i.e. must store | |
152 | what were fetched in tracking branches), and its LHS and RHS | |
153 | must end with `/*`. The above specifies that all remote | |
154 | branches are tracked using tracking branches in | |
155 | `refs/remotes/origin/` hierarchy under the same name. | |
156 | ||
157 | The rule to determine which remote branch to merge after | |
158 | fetching is a bit involved, in order not to break backward | |
159 | compatibility. | |
160 | ||
161 | If explicit refspecs were given on the command | |
162 | line of `git pull`, they are all merged. | |
163 | ||
164 | When no refspec was given on the command line, then `git pull` | |
165 | uses the refspec from the configuration or | |
166 | `$GIT_DIR/remotes/<origin>`. In such cases, the following | |
167 | rules apply: | |
168 | ||
169 | . If `branch.<name>.merge` configuration for the current | |
170 | branch `<name>` exists, that is the name of the branch at the | |
171 | remote site that is merged. | |
172 | ||
173 | . If the refspec is a globbing one, nothing is merged. | |
174 | ||
175 | . Otherwise the remote branch of the first refspec is merged. | |
176 | ||
177 | ||
37465016 JH |
178 | EXAMPLES |
179 | -------- | |
180 | ||
921177f5 CC |
181 | * Update the remote-tracking branches for the repository |
182 | you cloned from, then merge one of them into your | |
183 | current branch: | |
184 | + | |
185 | ------------------------------------------------ | |
186 | $ git pull, git pull origin | |
187 | ------------------------------------------------ | |
188 | + | |
189 | Normally the branch merged in is the HEAD of the remote repository, | |
190 | but the choice is determined by the branch.<name>.remote and | |
191 | branch.<name>.merge options; see linkgit:git-config[1] for details. | |
192 | ||
193 | * Merge into the current branch the remote branch `next`: | |
194 | + | |
195 | ------------------------------------------------ | |
196 | $ git pull origin next | |
197 | ------------------------------------------------ | |
198 | + | |
199 | This leaves a copy of `next` temporarily in FETCH_HEAD, but | |
d504f697 CB |
200 | does not update any remote-tracking branches. Using remote-tracking |
201 | branches, the same can be done by invoking fetch and merge: | |
921177f5 CC |
202 | + |
203 | ------------------------------------------------ | |
d504f697 CB |
204 | $ git fetch origin |
205 | $ git merge origin/next | |
921177f5 | 206 | ------------------------------------------------ |
bccf5956 | 207 | |
37465016 | 208 | |
3ae854c3 | 209 | If you tried a pull which resulted in a complex conflicts and |
0b444cdb | 210 | would want to start over, you can recover with 'git reset'. |
3ae854c3 JH |
211 | |
212 | ||
fdd08979 JH |
213 | SEE ALSO |
214 | -------- | |
5162e697 | 215 | linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1] |
fdd08979 JH |
216 | |
217 | ||
2cf565c5 DG |
218 | Author |
219 | ------ | |
3f971fc4 | 220 | Written by Linus Torvalds <torvalds@osdl.org> |
59eb68aa | 221 | and Junio C Hamano <gitster@pobox.com> |
2cf565c5 DG |
222 | |
223 | Documentation | |
224 | -------------- | |
bccf5956 JL |
225 | Documentation by Jon Loeliger, |
226 | David Greaves, | |
227 | Junio C Hamano and the git-list <git@vger.kernel.org>. | |
2cf565c5 DG |
228 | |
229 | GIT | |
230 | --- | |
9e1f0a85 | 231 | Part of the linkgit:git[1] suite |