freshlybakedca.ke
Git fork
Merge branch 'jn/doc-pull' into maint
* jn/doc-pull:
Documentation: flesh out “git pull” description
+54
-11
+54
-11
Documentation/git-pull.txt
+54
-11
Documentation/git-pull.txt
···
8
8
9
9
SYNOPSIS
10
10
--------
11
-
'git pull' <options> <repository> <refspec>...
11
+
'git pull' [options] [<repository> [<refspec>...]]
12
12
13
13
14
14
DESCRIPTION
15
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
+
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
+
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
+
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.
19
51
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.
52
+
------------
53
+
A---B---C remotes/origin/master
54
+
/ \
55
+
D---E---F---G---H master
56
+
------------
23
57
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'.
58
+
See linkgit:git-merge[1] for details, including how conflicts
59
+
are presented and handled.
26
60
27
-
*Warning*: Running 'git pull' (actually, the underlying 'git merge')
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'
28
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].
30
70
31
71
OPTIONS
32
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'.
33
76
34
77
-q::
35
78
--quiet::