fetch doc: add a section on configured remote-tracking branches
To resurrect a misleading mention removed in the previous step, add a section to explain how the remote-tracking configuration interacts with the refspecs given as the command-line arguments. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
May 29, 2014 at 14:24 UTC
fcb14b0c8d7a732b1d26b5fda18f730851a76eed
1 file changed
+45
Documentation/git-fetch.txt
+45
@@ -51,6 +51,51 @@ include::pull-fetch-param.txt[]
51
include::urls-remotes.txt[]
52
53
54
+CONFIGURED REMOTE-TRACKING BRANCHES
55
+-----------------------------------
56
+
57
+You often interact with the same remote repository by
58
+regularly and repeatedly fetching from it. In order to keep track
59
+of the progress of such a remote repository, `git fetch` allows you
60
+to configure `remote.<repository>.fetch` configuration variables.
61
+
62
+Typically such a variable may look like this:
63
+
64
+------------------------------------------------
65
+[remote "origin"]
66
+ fetch = +refs/heads/*:refs/remotes/origin/*
67
+------------------------------------------------
68
+
69
+This configuration is used in two ways:
70
+
71
+* When `git fetch` is run without specifying what branches
72
+ and/or tags to fetch on the command line, e.g. `git fetch origin`
73
+ or `git fetch`, `remote.<repository>.fetch` values are used as
74
+ the refspecs---they specify which refs to fetch and which local refs
75
+ to update. The example above will fetch
76
+ all branches that exist in the `origin` (i.e. any ref that matches
77
+ the left-hand side of the value, `refs/heads/*`) and update the
78
+ corresponding remote-tracking branches in the `refs/remotes/origin/*`
79
+ hierarchy.
80
+
81
+* When `git fetch` is run with explicit branches and/or tags
82
+ to fetch on the command line, e.g. `git fetch origin master`, the
83
+ <refspec>s given on the command line determine what are to be
84
+ fetched (e.g. `master` in the example,
85
+ which is a short-hand for `master:`, which in turn means
86
+ "fetch the 'master' branch but I do not explicitly say what
87
+ remote-tracking branch to update with it from the command line"),
88
+ and the example command will
89
+ fetch _only_ the 'master' branch. The `remote.<repository>.fetch`
90
+ values determine which
91
+ remote-tracking branch, if any, is updated. When used in this
92
+ way, the `remote.<repository>.fetch` values do not have any
93
+ effect in deciding _what_ gets fetched (i.e. the values are not
94
+ used as refspecs when the command-line lists refspecs); they are
95
+ only used to decide _where_ the refs that are fetched are stored
96
+ by acting as a mapping.
97
+
98
+
99
EXAMPLES
100
--------
101