Blob


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 git+ssh
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 git+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 ssh
145 Short alias for git+ssh.
146 .El
147 .It Ic port Ar port
148 Defines the port to use for connecting to the remote repository's server.
149 The
150 .Ar port
151 can be specified by number or name.
152 The port name to number mappings are found in the file
153 .Pa /etc/services ;
154 see
155 .Xr services 5
156 for details.
157 If not specified, the default port of the specified
158 .Cm protocol
159 will be used.
160 .It Ic branch Brq Ar branch ...
161 Specify one or more branches which
162 .Cm got fetch
163 and
164 .Cm got send
165 should fetch from and send to the remote repository by default.
166 The list of branches specified here can be overridden at the
167 .Cm got fetch
168 and
169 .Cm got send
170 command lines with the
171 .Fl b
172 option.
173 .It Ic fetch_all_branches Ar yes | no
174 This option controls whether
175 .Cm got fetch
176 will fetch all branches from the remote repository by default.
177 If enabled, this behaviour can be overridden at the
178 .Cm got fetch
179 command line with the
180 .Fl b
181 option, and any
182 .Cm branch
183 configuration settings for this remote repository will be ignored.
184 .It Ic reference Brq Ar reference ...
185 Specify one or more arbitrary references which
186 .Cm got fetch
187 should fetch by default, in addition to the branches and tags that will
188 be fetched.
189 The list of references specified here can be overridden at the
190 .Cm got fetch
191 command line with the
192 .Fl R
193 option.
194 .Cm got fetch
195 will refuse to fetch references from the remote repository's
196 .Dq refs/remotes/
197 or
198 .Dq refs/got/
199 namespace.
200 In any case, references in the
201 .Dq refs/tags/
202 namespace will always be fetched and mapped directly to local references
203 in the same namespace.
204 .It Ic mirror_references Ar yes | no
205 This option controls the behaviour of
206 .Cm got fetch
207 when updating references.
208 .Sy Enabling this option can lead to the loss of local commits.
209 Maintaining custom changes in a mirror repository is therefore discouraged.
210 .Pp
211 If this option is not specified or set to
212 .Ar no ,
213 .Cm got fetch
214 will map references of the remote repository into the local repository's
215 .Dq refs/remotes/
216 namespace.
217 .Pp
218 If this option is set to
219 .Ar yes ,
220 all branches in the
221 .Dq refs/heads/
222 namespace will be updated directly to match the corresponding branches in
223 the remote repository.
224 .It Ic fetch Brq ...
225 An optional
226 .Ic fetch
227 block may contain any of the following configuration settings
228 for use by
229 .Cm got fetch ,
230 overriding corresponding settings in the containing
231 .Ic remote Ar name Brq ...
232 block.
233 .Bl -bullet
234 .It
235 .Ic server Ar hostname
236 .It
237 .Ic repository Ar path
238 .It
239 .Ic protocol Ar scheme
240 .It
241 .Ic port Ar port
242 .It
243 .Ic branch Brq Ar branch ...
244 .El
245 .It Ic send Brq ...
246 An optional
247 .Ic send
248 block may contain any of the following configuration settings
249 for use by
250 .Cm got send ,
251 overriding corresponding settings in the containing
252 .Ic remote Ar name Brq ...
253 block.
254 .Bl -bullet
255 .It
256 .Ic server Ar hostname
257 .It
258 .Ic repository Ar path
259 .It
260 .Ic protocol Ar scheme
261 .It
262 .Ic port Ar port
263 .It
264 .Ic branch Brq Ar branch ...
265 .El
266 .El
267 .El
268 .Sh FILES
269 .Bl -tag -width Ds -compact
270 .It Pa got.conf
271 If present,
272 .Nm
273 located in the root directory of a Git repository supersedes any relevant
274 settings in Git's
275 .Pa config
276 file.
277 .Pp
278 .It Pa .got/got.conf
279 If present,
280 .Nm
281 located in the
282 .Pa .got
283 meta-data directory of a
284 .Xr got 1
285 work tree supersedes any relevant settings in the repository's
286 .Nm
287 configuration file and Git's
288 .Pa config
289 file.
290 .El
291 .Sh EXAMPLES
292 Configure author information:
293 .Bd -literal -offset indent
294 author "Flan Hacker <flan_hacker@openbsd.org>"
295 .Ed
296 .Pp
297 Remote repository specification for the Game of Trees repository:
298 .Bd -literal -offset indent
299 remote "origin" {
300 server git.gameoftrees.org
301 protocol git
302 repository got
303 branch { "main" }
305 .Ed
306 .Pp
307 Mirror the
308 .Ox
309 src repository from Github:
310 .Bd -literal -offset indent
311 remote "origin" {
312 repository "openbsd/src"
313 server git@github.com
314 protocol git+ssh
315 mirror_references yes
317 .Ed
318 .Pp
319 Fetch changes via the Git protocol and send changes via the SSH protocol:
320 .Bd -literal -offset indent
321 remote "origin" {
322 repository my_repo
323 server git.example.com
324 protocol git
325 send {
326 server git@git.example.com
327 protocol ssh
330 .Ed
331 .Sh SEE ALSO
332 .Xr got 1 ,
333 .Xr git-repository 5 ,
334 .Xr got-worktree 5
335 .Sh CAVEATS
336 .Nm
337 offers no way to configure the editor spawned by
338 .Cm got commit ,
339 .Cm got histedit ,
340 .Cm got import ,
341 or
342 .Cm got tag .
343 This is deliberate and prevents potential arbitrary command execution
344 as another user when repositories or work trees are shared between users.
345 Users should set their
346 .Ev VISUAL
347 or
348 .Ev EDITOR
349 environment variables instead.