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