| blob | 6e7ca5a02c54e06736b5ac4e5d9755da996cf1f5 |
1 .\"
2 .\" Copyright (c) 2020 Stefan Sperling <stsp@openbsd.org>
3 .\"
4 .\" Permission to use, copy, modify, and distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
7 .\"
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\"
16 .Dd $Mdocdate$
17 .Dt GOT.CONF 5
18 .Os
19 .Sh NAME
20 .Nm got.conf
21 .Nd Game of Trees configuration file
22 .Sh DESCRIPTION
23 .Nm
24 is the run-time configuration file for
25 .Xr got 1 .
26 .Pp
27 .Nm
28 may be present in the root directory of a Git repository for
29 repository-wide settings, or in the
30 .Pa .got
31 meta-data directory of a work tree to override repository-wide
32 settings for
33 .Xr got 1
34 commands executed within this work tree.
35 .Pp
36 The file format is line-based, with one configuration directive per line.
37 Any lines beginning with a
38 .Sq #
39 are treated as comments and ignored.
40 .Pp
41 The available configuration directives are as follows:
42 .Bl -tag -width Ds
43 .It Ic author Dq Real Name <email address>
44 Configure the author's name and email address for
45 .Cm got commit
46 and
47 .Cm got import
48 when operating on this repository.
49 Author information specified here overrides the
50 .Ev GOT_AUTHOR
51 environment variable.
52 .Pp
53 Because
54 .Xr git 1
55 may fail to parse commits without an email address in author data,
56 .Xr got 1
57 attempts to reject author information with a missing email address.
58 .It Ic signer_id Pa signer-id
59 Configure a
60 .Ar signer-id
61 to sign tag objects.
62 This key will be used to sign all tag objects unless overridden by
63 .Cm got tag Fl s Ar signer-id .
64 .Pp
65 For SSH-based signatures,
66 .Ar signer-id
67 is the path to a file which may refer to either a private SSH key,
68 or a public SSH key with the private half available via
69 .Xr ssh-agent 1 .
70 .It Ic allowed_signers Pa path
71 Configure a
72 .Ar path
73 to the "allowed signers" file which contains a list of trusted
74 SSH signer identities.
75 The file will be passed to
76 .Xr ssh-keygen 1
77 during verification of SSH-based signatures with
78 .Cm got tag Fl V .
79 The format of the "allowed signers" file is documented in the
80 ALLOWED SIGNERS section of
81 .Xr ssh-keygen 1 .
82 .Pp
83 Verification of SSH-based signatures is impossible unless the
84 .Ic allowed_signers
85 option is set in
86 .Nm .
87 .It Ic revoked_signers Pa path
88 Configure a
89 .Ar path
90 to the optional "revoked signers" file, which contains a list of revoked
91 SSH signer identities.
92 This file is passed to
93 .Xr ssh-keygen 1
94 during signature verification with
95 .Cm got tag Fl V .
96 Revoked identities are no longer considered trustworthy and verification
97 of relevant signatures will fail.
98 .It Ic remote Ar name Brq ...
99 Define a remote repository.
100 The specified
101 .Ar name
102 can be used to refer to the remote repository on the command line of
103 .Cm got fetch
104 and
105 .Cm got send .
106 .Pp
107 When repositories are shared between multiple users on the system, it is
108 recommended that users configure their trusted remote repositories in each
109 of their work-trees'
110 .Nm
111 files, overriding corresponding repository-wide settings.
112 This can avoid potentially undesirable connections to remote repositories
113 placed into the shared repository's
114 .Nm
115 file by other users.
116 .Pp
117 Information about a repository is declared in a block of options
118 enclosed in curly brackets:
119 .Bl -tag -width Ds
120 .It Ic server Ar hostname
121 Defines the hostname to use for contacting the remote repository's server.
122 .It Ic repository Ar path
123 Defines the path to the repository on the remote repository's server.
124 .It Ic protocol Ar scheme
125 Defines the protocol to use for communicating with the remote repository's
126 server.
127 .Pp
128 The following protocol schemes are supported:
129 .Bl -tag -width https
130 .It git
131 The Git protocol as implemented by the
132 .Xr git-daemon 1
133 server.
134 Use of this protocol is discouraged since it supports neither authentication
135 nor encryption.
136 .It ssh
137 The Git protocol wrapped in an authenticated and encrypted
138 .Xr ssh 1
139 tunnel.
140 With this protocol the hostname may contain an embedded username for
141 .Xr ssh 1
142 to use:
143 .Mt user@hostname
144 .It http
145 The
146 .Dq smart
147 Git HTTP protocol.
148 Not compatible with servers using the
149 .Dq dumb
150 Git HTTP protocol.
151 .Pp
152 The
153 .Dq smart
154 Git HTTP protocol is supported by
155 .Cm got clone
156 and
157 .Cm got fetch ,
158 but not by
159 .Cm got send .
160 To send from a repository cloned over HTTP, add a
161 .Ic send
162 block (see below) to ensure that the
163 .Dq ssh://
164 protocol will be used by
165 .Cm got send .
166 .Pp
167 Use of this protocol is discouraged since it supports neither authentication
168 nor encryption.
169 .It https
170 The
171 .Dq smart
172 Git HTTP protocol wrapped in SSL/TLS.
173 .El
174 .It Ic port Ar port
175 Defines the port to use for connecting to the remote repository's server.
176 The
177 .Ar port
178 can be specified by number or name.
179 The port name to number mappings are found in the file
180 .Pa /etc/services ;
181 see
182 .Xr services 5
183 for details.
184 If not specified, the default port of the specified
185 .Cm protocol
186 will be used.
187 .It Ic branch Brq Ar branch ...
188 Specify one or more branches which
189 .Cm got fetch
190 and
191 .Cm got send
192 should fetch from and send to the remote repository by default.
193 The list of branches specified here can be overridden at the
194 .Cm got fetch
195 and
196 .Cm got send
197 command lines with the
198 .Fl b
199 option.
200 .It Ic fetch_all_branches Ar yes | no
201 This option controls whether
202 .Cm got fetch
203 will fetch all branches from the remote repository by default.
204 If enabled, this behaviour can be overridden at the
205 .Cm got fetch
206 command line with the
207 .Fl b
208 option, and any
209 .Cm branch
210 configuration settings for this remote repository will be ignored.
211 .It Ic reference Brq Ar reference ...
212 Specify one or more arbitrary references which
213 .Cm got fetch
214 should fetch by default, in addition to the branches and tags that will
215 be fetched.
216 The list of references specified here can be overridden at the
217 .Cm got fetch
218 command line with the
219 .Fl R
220 option.
221 .Cm got fetch
222 will refuse to fetch references from the remote repository's
223 .Dq refs/remotes/
224 or
225 .Dq refs/got/
226 namespace.
227 In any case, references in the
228 .Dq refs/tags/
229 namespace will always be fetched and mapped directly to local references
230 in the same namespace.
231 .It Ic mirror_references Ar yes | no
232 This option controls the behaviour of
233 .Cm got fetch
234 when updating references.
235 .Sy Enabling this option can lead to the loss of local commits.
236 Maintaining custom changes in a mirror repository is therefore discouraged.
237 .Pp
238 If this option is not specified or set to
239 .Ar no ,
240 .Cm got fetch
241 will map references of the remote repository into the local repository's
242 .Dq refs/remotes/
243 namespace.
244 .Pp
245 If this option is set to
246 .Ar yes ,
247 all branches in the
248 .Dq refs/heads/
249 namespace will be updated directly to match the corresponding branches in
250 the remote repository.
251 .It Ic fetch Brq ...
252 An optional
253 .Ic fetch
254 block may contain any of the following configuration settings
255 for use by
256 .Cm got fetch ,
257 overriding corresponding settings in the containing
258 .Ic remote Ar name Brq ...
259 block.
260 .Bl -bullet
261 .It
262 .Ic server Ar hostname
263 .It
264 .Ic repository Ar path
265 .It
266 .Ic protocol Ar scheme
267 .It
268 .Ic port Ar port
269 .It
270 .Ic branch Brq Ar branch ...
271 .El
272 .It Ic send Brq ...
273 An optional
274 .Ic send
275 block may contain any of the following configuration settings
276 for use by
277 .Cm got send ,
278 overriding corresponding settings in the containing
279 .Ic remote Ar name Brq ...
280 block.
281 .Bl -bullet
282 .It
283 .Ic server Ar hostname
284 .It
285 .Ic repository Ar path
286 .It
287 .Ic protocol Ar scheme
288 .It
289 .Ic port Ar port
290 .It
291 .Ic branch Brq Ar branch ...
292 .El
293 .El
294 .El
295 .Sh FILES
296 .Bl -tag -width Ds -compact
297 .It Pa got.conf
298 If present,
299 .Nm
300 located in the root directory of a Git repository supersedes any relevant
301 settings in Git's
302 .Pa config
303 file.
304 .Pp
305 .It Pa .got/got.conf
306 If present,
307 .Nm
308 located in the
309 .Pa .got
310 meta-data directory of a
311 .Xr got 1
312 work tree supersedes any relevant settings in the repository's
313 .Nm
314 configuration file and Git's
315 .Pa config
316 file.
317 .El
318 .Sh EXAMPLES
319 Configure author information:
320 .Bd -literal -offset indent
321 author "Flan Hacker <flan_hacker@openbsd.org>"
322 .Ed
323 .Pp
324 Remote repository specification for the Game of Trees repository:
325 .Bd -literal -offset indent
326 remote "origin" {
327 server anonymous@got.gameoftrees.org
328 protocol ssh
329 repository got
330 branch { "main" }
331 }
332 .Ed
333 .Pp
334 Mirror the
335 .Ox
336 src repository from Github:
337 .Bd -literal -offset indent
338 remote "origin" {
339 repository "openbsd/src"
340 server git@github.com
341 protocol git+ssh
342 mirror_references yes
343 }
344 .Ed
345 .Pp
346 Fetch changes via the Git protocol and send changes via the SSH protocol:
347 .Bd -literal -offset indent
348 remote "origin" {
349 repository my_repo
350 server git.example.com
351 protocol git
352 send {
353 server git@git.example.com
354 protocol ssh
355 }
356 }
357 .Ed
358 .Sh SEE ALSO
359 .Xr got 1 ,
360 .Xr git-repository 5 ,
361 .Xr got-worktree 5
362 .Sh CAVEATS
363 .Nm
364 offers no way to configure the editor spawned by
365 .Cm got commit ,
366 .Cm got histedit ,
367 .Cm got import ,
368 or
369 .Cm got tag .
370 This is deliberate and prevents potential arbitrary command execution
371 as another user when repositories or work trees are shared between users.
372 Users should set their
373 .Ev VISUAL
374 or
375 .Ev EDITOR
376 environment variables instead.