8
9
SYNOPSIS
10
--------
11
-'git pull' <options> <repository> <refspec>...
11
+'git pull' [options] [<repository> [<refspec>...]]
12
13
14
DESCRIPTION
15
-----------
16
-Runs 'git fetch' with the given parameters, and calls 'git merge'
17
-to merge the retrieved head(s) into the current branch.
18
-With `--rebase`, calls 'git rebase' instead of 'git merge'.
16
20
-Note that you can use `.` (current directory) as the
21
-<repository> to pull from the local repository -- this is useful
22
-when merging local branches into the current branch.
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`.
20
24
-Also note that options meant for 'git pull' itself and underlying
25
-'git merge' must be given before the options meant for 'git fetch'.
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'.
25
27
-*Warning*: Running 'git pull' (actually, the underlying 'git merge')
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
30
+(e.g., refs/heads/*:refs/remotes/origin/*), but usually it is
31
+the name of a branch in the remote repository.
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'
63
with uncommitted changes is discouraged: while possible, it leaves you
29
-in a state that is hard to back out of in the case of a conflict.
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].
70
71
OPTIONS
72
-------
73
74
+Options meant for 'git pull' itself and the underlying 'git merge'
75
+must be given before the options meant for 'git fetch'.
76
+
77
-q::
78
--quiet::
79
This is passed to both underlying git-fetch to squelch reporting of