freshlybakedca.ke
Git fork
Merge branch 'je/doc-pull'
Documentation updates.
* je/doc-pull:
doc: git-pull: clarify how to exit a conflicted merge
doc: git-pull: delete the example
doc: git-pull: clarify options for integrating remote branch
doc: git-pull: move <repository> and <refspec> params
+40
-53
Documentation/git-pull.adoc
+40
-53
Documentation/git-pull.adoc
···
15
15
DESCRIPTION
16
16
-----------
17
17
18
-
Incorporates changes from a remote repository into the current branch.
19
-
If the current branch is behind the remote, then by default it will
20
-
fast-forward the current branch to match the remote. If the current
21
-
branch and the remote have diverged, the user needs to specify how to
22
-
reconcile the divergent branches with `--rebase` or `--no-rebase` (or
23
-
the corresponding configuration option in `pull.rebase`).
24
-
25
-
More precisely, `git pull` runs `git fetch` with the given parameters
26
-
and then depending on configuration options or command line flags,
27
-
will call either `git rebase` or `git merge` to reconcile diverging
28
-
branches.
29
-
30
-
<repository> should be the name of a remote repository as
31
-
passed to linkgit:git-fetch[1]. <refspec> can name an
32
-
arbitrary remote ref (for example, the name of a tag) or even
33
-
a collection of refs with corresponding remote-tracking branches
34
-
(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),
35
-
but usually it is the name of a branch in the remote repository.
36
-
37
-
Default values for <repository> and <branch> are read from the
38
-
"remote" and "merge" configuration for the current branch
39
-
as set by linkgit:git-branch[1] `--track`.
40
-
41
-
Assume the following history exists and the current branch is
42
-
"`master`":
18
+
Integrate changes from a remote repository into the current branch.
43
19
44
-
------------
45
-
A---B---C master on origin
46
-
/
47
-
D---E---F---G master
48
-
^
49
-
origin/master in your repository
50
-
------------
20
+
First, `git pull` runs `git fetch` with the same arguments
21
+
(excluding merge options) to fetch remote branch(es).
22
+
Then it decides which remote branch to integrate: if you run `git pull`
23
+
with no arguments this defaults to the <<UPSTREAM-BRANCHES,upstream>>
24
+
for the current branch.
25
+
Then it integrates that branch into the current branch.
51
26
52
-
Then "`git pull`" will fetch and replay the changes from the remote
53
-
`master` branch since it diverged from the local `master` (i.e., `E`)
54
-
until its current commit (`C`) on top of `master` and record the
55
-
result in a new commit along with the names of the two parent commits
56
-
and a log message from the user describing the changes.
57
-
58
-
------------
59
-
A---B---C origin/master
60
-
/ \
61
-
D---E---F---G---H master
62
-
------------
27
+
There are 4 main options for integrating the remote branch:
63
28
64
-
See linkgit:git-merge[1] for details, including how conflicts
65
-
are presented and handled.
29
+
1. `git pull --ff-only` will only do "fast-forward" updates: it
30
+
fails if your local branch has diverged from the remote branch.
31
+
This is the default.
32
+
2. `git pull --rebase` runs `git rebase`
33
+
3. `git pull --no-rebase` runs `git merge`.
34
+
4. `git pull --squash` runs `git merge --squash`
66
35
67
-
In Git 1.7.0 or later, to cancel a conflicting merge, use
68
-
`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'
69
-
with uncommitted changes is discouraged: while possible, it leaves you
70
-
in a state that may be hard to back out of in the case of a conflict.
36
+
You can also set the configuration options `pull.rebase`, `pull.squash`,
37
+
or `pull.ff` with your preferred behaviour.
71
38
72
-
If any of the remote changes overlap with local uncommitted changes,
73
-
the merge will be automatically canceled and the work tree untouched.
74
-
It is generally best to get any local changes in working order before
75
-
pulling or stash them away with linkgit:git-stash[1].
39
+
If there's a merge conflict during the merge or rebase that you don't
40
+
want to handle, you can safely abort it with `git merge --abort` or `git
41
+
--rebase abort`.
76
42
77
43
OPTIONS
78
44
-------
45
+
46
+
<repository>::
47
+
The "remote" repository to pull from. This can be either
48
+
a URL (see the section <<URLS,GIT URLS>> below) or the name
49
+
of a remote (see the section <<REMOTES,REMOTES>> below).
50
+
+
51
+
Defaults to the configured upstream for the current branch, or `origin`.
52
+
See <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> below for more on how to
53
+
configure upstreams.
54
+
55
+
<refspec>::
56
+
Which branch or other reference(s) to fetch and integrate into the
57
+
current branch, for example `main` in `git pull origin main`.
58
+
Defaults to the configured upstream for the current branch.
59
+
+
60
+
This can be a branch, tag, or other collection of reference(s).
61
+
See <<fetch-refspec,<refspec>>> below under "Options related to fetching"
62
+
for the full syntax, and <<DEFAULT-BEHAVIOUR,DEFAULT BEHAVIOUR>> below
63
+
for how `git pull` uses this argument to determine which remote branch
64
+
to integrate.
79
65
80
66
-q::
81
67
--quiet::
···
145
131
146
132
include::merge-strategies.adoc[]
147
133
134
+
[[DEFAULT-BEHAVIOUR]]
148
135
DEFAULT BEHAVIOUR
149
136
-----------------
150
137