Documentation/git-pull: describe default behaviour and config interactions
The way 'git pull' without explicit parameters work were not explained well in any existing documentation. Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Feb 8, 2007 at 23:35 UTC
9e2586ff2f8b2b3f5bbdd7ad47af0db6abf0f6f8
1 file changed
+54
Documentation/git-pull.txt
+54
@@ -33,6 +33,60 @@ include::urls.txt[]
33
34
include::merge-strategies.txt[]
35
36
+DEFAULT BEHAVIOUR
37
+-----------------
38
+
39
+Often people use `git pull` without giving any parameter.
40
+Traditionally, this has been equivalent to saying `git pull
41
+origin`. However, when configuration `branch.<name>.remote` is
42
+present while on branch `<name>`, that value is used instead of
43
+`origin`.
44
+
45
+In order to determine what URL to use to fetch from, the value
46
+of the configuration `remote.<origin>.url` is consulted
47
+and if there is not any such variable, the value on `URL: ` line
48
+in `$GIT_DIR/remotes/<origin>` file is used.
49
+
50
+In order to determine what remote branches to fetch (and
51
+optionally store in the tracking branches) when the command is
52
+run without any refspec parameters on the command line, values
53
+of the configuration variable `remote.<origin>.fetch` are
54
+consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>`
55
+file is consulted and its `Pull: ` lines are used.
56
+In addition to the refspec formats described in the OPTIONS
57
+section, you can have a globbing refspec that looks like this:
58
+
59
+------------
60
+refs/heads/*:refs/remotes/origin/*
61
+------------
62
+
63
+A globbing refspec must have a non-empty RHS (i.e. must store
64
+what were fetched in tracking branches), and its LHS and RHS
65
+must end with `/*`. The above specifies that all remote
66
+branches are tracked using tracking branches in
67
+`refs/remotes/origin/` hierarchy under the same name.
68
+
69
+The rule to determine which remote branch to merge after
70
+fetching is a bit involved, in order not to break backward
71
+compatibility.
72
+
73
+If explicit refspecs were given on the command
74
+line of `git pull`, they are all merged.
75
+
76
+When no refspec was given on the command line, then `git pull`
77
+uses the refspec from the configuration or
78
+`$GIT_DIR/remotes/<origin>`. In such cases, the following
79
+rules apply:
80
+
81
+. If `branch.<name>.merge` configuration for the current
82
+ branch `<name>` exists, that is the name of the branch at the
83
+ remote site that is merged.
84
+
85
+. If the refspec is a globbing one, nothing is merged.
86
+
87
+. Otherwise the remote branch of the first refspec is merged.
88
+
89
+
90
EXAMPLES
91
--------
92