API documentation for remote.h
Signed-off-by: Daniel Barkalow <barkalow@iabervon.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Daniel Barkalow committed
Feb 19, 2008 at 02:52 UTC
f019d08ea6d5ae2f83a4b4eb9211108dfab4a672
1 file changed
+123
Documentation/technical/api-remote.txt
new
+123
@@ -0,0 +1,123 @@
1
+Remotes configuration API
2
+=========================
3
+
4
+The API in remote.h gives access to the configuration related to
5
+remotes. It handles all three configuration mechanisms historically
6
+and currently used by git, and presents the information in a uniform
7
+fashion. Note that the code also handles plain URLs without any
8
+configuration, giving them just the default information.
9
+
10
+struct remote
11
+-------------
12
+
13
+`name`::
14
+
15
+ The user's nickname for the remote
16
+
17
+`url`::
18
+
19
+ An array of all of the url_nr URLs configured for the remote
20
+
21
+`push`::
22
+
23
+ An array of refspecs configured for pushing, with
24
+ push_refspec being the literal strings, and push_refspec_nr
25
+ being the quantity.
26
+
27
+`fetch`::
28
+
29
+ An array of refspecs configured for fetching, with
30
+ fetch_refspec being the literal strings, and fetch_refspec_nr
31
+ being the quantity.
32
+
33
+`fetch_tags`::
34
+
35
+ The setting for whether to fetch tags (as a separate rule from
36
+ the configured refspecs); -1 means never to fetch tags, 0
37
+ means to auto-follow tags based on the default heuristic, 1
38
+ means to always auto-follow tags, and 2 means to fetch all
39
+ tags.
40
+
41
+`receivepack`, `uploadpack`::
42
+
43
+ The configured helper programs to run on the remote side, for
44
+ git-native protocols.
45
+
46
+`http_proxy`::
47
+
48
+ The proxy to use for curl (http, https, ftp, etc.) URLs.
49
+
50
+struct remotes can be found by name with remote_get(), and iterated
51
+through with for_each_remote(). remote_get(NULL) will return the
52
+default remote, given the current branch and configuration.
53
+
54
+struct refspec
55
+--------------
56
+
57
+A struct refspec holds the parsed interpretation of a refspec. If it
58
+will force updates (starts with a '+'), force is true. If it is a
59
+pattern (sides end with '*') pattern is true. src and dest are the two
60
+sides (if a pattern, only the part outside of the wildcards); if there
61
+is only one side, it is src, and dst is NULL; if sides exist but are
62
+empty (i.e., the refspec either starts or ends with ':'), the
63
+corresponding side is "".
64
+
65
+This parsing can be done to an array of strings to give an array of
66
+struct refpsecs with parse_ref_spec().
67
+
68
+remote_find_tracking(), given a remote and a struct refspec with
69
+either src or dst filled out, will fill out the other such that the
70
+result is in the "fetch" specification for the remote (note that this
71
+evaluates patterns and returns a single result).
72
+
73
+struct branch
74
+-------------
75
+
76
+Note that this may end up moving to branch.h
77
+
78
+struct branch holds the configuration for a branch. It can be looked
79
+up with branch_get(name) for "refs/heads/{name}", or with
80
+branch_get(NULL) for HEAD.
81
+
82
+It contains:
83
+
84
+`name`::
85
+
86
+ The short name of the branch.
87
+
88
+`refname`::
89
+
90
+ The full path for the branch ref.
91
+
92
+`remote_name`::
93
+
94
+ The name of the remote listed in the configuration.
95
+
96
+`remote`::
97
+
98
+ The struct remote for that remote.
99
+
100
+`merge_name`::
101
+
102
+ An array of the "merge" lines in the configuration.
103
+
104
+`merge`::
105
+
106
+ An array of the struct refspecs used for the merge lines. That
107
+ is, merge[i]->dst is a local tracking ref which should be
108
+ merged into this branch by default.
109
+
110
+`merge_nr`::
111
+
112
+ The number of merge configurations
113
+
114
+branch_has_merge_config() returns true if the given branch has merge
115
+configuration given.
116
+
117
+Other stuff
118
+-----------
119
+
120
+There is other stuff in remote.h that is related, in general, to the
121
+process of interacting with remotes.
122
+
123
+(Daniel Barkalow)