2 257add31 2020-09-09 stsp .\" Copyright (c) 2020 Stefan Sperling <stsp@openbsd.org>
4 257add31 2020-09-09 stsp .\" Permission to use, copy, modify, and distribute this software for any
5 257add31 2020-09-09 stsp .\" purpose with or without fee is hereby granted, provided that the above
6 257add31 2020-09-09 stsp .\" copyright notice and this permission notice appear in all copies.
8 257add31 2020-09-09 stsp .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 257add31 2020-09-09 stsp .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 257add31 2020-09-09 stsp .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 257add31 2020-09-09 stsp .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 257add31 2020-09-09 stsp .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 257add31 2020-09-09 stsp .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 257add31 2020-09-09 stsp .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 257add31 2020-09-09 stsp .Dd $Mdocdate$
17 257add31 2020-09-09 stsp .Dt GOT.CONF 5
20 257add31 2020-09-09 stsp .Nm got.conf
21 257add31 2020-09-09 stsp .Nd Game of Trees configuration file
22 257add31 2020-09-09 stsp .Sh DESCRIPTION
24 257add31 2020-09-09 stsp is the run-time configuration file for
28 50b0790e 2020-09-11 stsp may be present in the root directory of a Git repository for
29 50b0790e 2020-09-11 stsp repository-wide settings, or in the
31 50b0790e 2020-09-11 stsp meta-data directory of a work tree to override repository-wide
32 50b0790e 2020-09-11 stsp settings for
34 50b0790e 2020-09-11 stsp commands executed within this work tree.
36 257add31 2020-09-09 stsp The file format is line-based, with one configuration directive per line.
37 257add31 2020-09-09 stsp Any lines beginning with a
39 257add31 2020-09-09 stsp are treated as comments and ignored.
41 257add31 2020-09-09 stsp The available configuration directives are as follows:
42 257add31 2020-09-09 stsp .Bl -tag -width Ds
43 257add31 2020-09-09 stsp .It Ic author Dq Real Name <email address>
44 257add31 2020-09-09 stsp Configure the author's name and email address for
45 257add31 2020-09-09 stsp .Cm got commit
47 257add31 2020-09-09 stsp .Cm got import
48 257add31 2020-09-09 stsp when operating on this repository.
49 257add31 2020-09-09 stsp Author information specified here overrides the
50 257add31 2020-09-09 stsp .Ev GOT_AUTHOR
51 257add31 2020-09-09 stsp environment variable.
55 257add31 2020-09-09 stsp may fail to parse commits without an email address in author data,
57 257add31 2020-09-09 stsp attempts to reject author information with a missing email address.
58 ff5e1f09 2022-07-06 thomas .It Ic signer_id Pa signer-id
59 ff5e1f09 2022-07-06 thomas Configure a
60 ff5e1f09 2022-07-06 thomas .Ar signer-id
61 ff5e1f09 2022-07-06 thomas to sign tag objects.
62 ff5e1f09 2022-07-06 thomas This key will be used to sign all tag objects unless overridden by
63 ff5e1f09 2022-07-06 thomas .Cm got tag Fl s Ar signer-id .
65 ff5e1f09 2022-07-06 thomas For SSH-based signatures,
66 ff5e1f09 2022-07-06 thomas .Ar signer-id
67 ff5e1f09 2022-07-06 thomas is the path to a file which may refer to either a private SSH key,
68 ff5e1f09 2022-07-06 thomas or a public SSH key with the private half available via
69 ff5e1f09 2022-07-06 thomas .Xr ssh-agent 1 .
70 839dd04f 2022-07-04 thomas .It Ic allowed_signers Pa path
71 839dd04f 2022-07-04 thomas Configure a
73 839dd04f 2022-07-04 thomas to the "allowed signers" file which contains a list of trusted
74 839dd04f 2022-07-04 thomas SSH signer identities.
75 839dd04f 2022-07-04 thomas The file will be passed to
76 839dd04f 2022-07-04 thomas .Xr ssh-keygen 1
77 839dd04f 2022-07-04 thomas during verification of SSH-based signatures with
78 839dd04f 2022-07-04 thomas .Cm got tag Fl V .
79 839dd04f 2022-07-04 thomas The format of the "allowed signers" file is documented in the
80 839dd04f 2022-07-04 thomas ALLOWED SIGNERS section of
81 839dd04f 2022-07-04 thomas .Xr ssh-keygen 1 .
83 839dd04f 2022-07-04 thomas Verification of SSH-based signatures is impossible unless the
84 839dd04f 2022-07-04 thomas .Ic allowed_signers
85 839dd04f 2022-07-04 thomas option is set in
87 839dd04f 2022-07-04 thomas .It Ic revoked_signers Pa path
88 839dd04f 2022-07-04 thomas Configure a
90 839dd04f 2022-07-04 thomas to the optional "revoked signers" file, which contains a list of revoked
91 839dd04f 2022-07-04 thomas SSH signer identities.
92 839dd04f 2022-07-04 thomas This file is passed to
93 839dd04f 2022-07-04 thomas .Xr ssh-keygen 1
94 839dd04f 2022-07-04 thomas during signature verification with
95 839dd04f 2022-07-04 thomas .Cm got tag Fl V .
96 839dd04f 2022-07-04 thomas Revoked identities are no longer considered trustworthy and verification
97 839dd04f 2022-07-04 thomas of relevant signatures will fail.
98 257add31 2020-09-09 stsp .It Ic remote Ar name Brq ...
99 257add31 2020-09-09 stsp Define a remote repository.
100 257add31 2020-09-09 stsp The specified
102 257add31 2020-09-09 stsp can be used to refer to the remote repository on the command line of
103 6480c871 2021-08-30 stsp .Cm got fetch
105 6480c871 2021-08-30 stsp .Cm got send .
107 6ca25bfc 2022-10-27 thomas When repositories are shared between multiple users on the system, it is
108 6ca25bfc 2022-10-27 thomas recommended that users configure their trusted remote repositories in each
109 6ca25bfc 2022-10-27 thomas of their work-trees'
111 6ca25bfc 2022-10-27 thomas files, overriding corresponding repository-wide settings.
112 6ca25bfc 2022-10-27 thomas This can avoid potentially undesirable connections to remote repositories
113 6ca25bfc 2022-10-27 thomas placed into the shared repository's
115 6ca25bfc 2022-10-27 thomas file by other users.
117 6ca25bfc 2022-10-27 thomas Information about a repository is declared in a block of options
118 257add31 2020-09-09 stsp enclosed in curly brackets:
119 257add31 2020-09-09 stsp .Bl -tag -width Ds
120 257add31 2020-09-09 stsp .It Ic server Ar hostname
121 257add31 2020-09-09 stsp Defines the hostname to use for contacting the remote repository's server.
122 257add31 2020-09-09 stsp .It Ic repository Ar path
123 257add31 2020-09-09 stsp Defines the path to the repository on the remote repository's server.
124 257add31 2020-09-09 stsp .It Ic protocol Ar scheme
125 257add31 2020-09-09 stsp Defines the protocol to use for communicating with the remote repository's
128 257add31 2020-09-09 stsp The following protocol schemes are supported:
129 257add31 2020-09-09 stsp .Bl -tag -width git+ssh
131 257add31 2020-09-09 stsp The Git protocol as implemented by the
132 257add31 2020-09-09 stsp .Xr git-daemon 1
134 257add31 2020-09-09 stsp Use of this protocol is discouraged since it supports neither authentication
135 257add31 2020-09-09 stsp nor encryption.
136 257add31 2020-09-09 stsp .It git+ssh
137 257add31 2020-09-09 stsp The Git protocol wrapped in an authenticated and encrypted
140 257add31 2020-09-09 stsp With this protocol the hostname may contain an embedded username for
143 257add31 2020-09-09 stsp .Mt user@hostname
145 257add31 2020-09-09 stsp Short alias for git+ssh.
147 257add31 2020-09-09 stsp .It Ic port Ar port
148 257add31 2020-09-09 stsp Defines the port to use for connecting to the remote repository's server.
151 257add31 2020-09-09 stsp can be specified by number or name.
152 257add31 2020-09-09 stsp The port name to number mappings are found in the file
153 257add31 2020-09-09 stsp .Pa /etc/services ;
155 257add31 2020-09-09 stsp .Xr services 5
156 257add31 2020-09-09 stsp for details.
157 257add31 2020-09-09 stsp If not specified, the default port of the specified
158 257add31 2020-09-09 stsp .Cm protocol
159 257add31 2020-09-09 stsp will be used.
160 b8adfa55 2020-09-25 stsp .It Ic branch Brq Ar branch ...
161 b8adfa55 2020-09-25 stsp Specify one or more branches which
162 b8adfa55 2020-09-25 stsp .Cm got fetch
164 6480c871 2021-08-30 stsp .Cm got send
165 93f8a337 2021-08-30 naddy should fetch from and send to the remote repository by default.
166 b8adfa55 2020-09-25 stsp The list of branches specified here can be overridden at the
167 b8adfa55 2020-09-25 stsp .Cm got fetch
169 6480c871 2021-08-30 stsp .Cm got send
170 6480c871 2021-08-30 stsp command lines with the
173 25eb5847 2022-07-03 thomas .It Ic fetch_all_branches Ar yes | no
174 0c8b29c5 2021-01-05 stsp This option controls whether
175 0c8b29c5 2021-01-05 stsp .Cm got fetch
176 0c8b29c5 2021-01-05 stsp will fetch all branches from the remote repository by default.
177 0c8b29c5 2021-01-05 stsp If enabled, this behaviour can be overridden at the
178 0c8b29c5 2021-01-05 stsp .Cm got fetch
179 0c8b29c5 2021-01-05 stsp command line with the
181 0c8b29c5 2021-01-05 stsp option, and any
183 0c8b29c5 2021-01-05 stsp configuration settings for this remote repository will be ignored.
184 99495ddb 2021-01-10 stsp .It Ic reference Brq Ar reference ...
185 99495ddb 2021-01-10 stsp Specify one or more arbitrary references which
186 99495ddb 2021-01-10 stsp .Cm got fetch
187 99495ddb 2021-01-10 stsp should fetch by default, in addition to the branches and tags that will
188 99495ddb 2021-01-10 stsp be fetched.
189 99495ddb 2021-01-10 stsp The list of references specified here can be overridden at the
190 99495ddb 2021-01-10 stsp .Cm got fetch
191 99495ddb 2021-01-10 stsp command line with the
194 99495ddb 2021-01-10 stsp .Cm got fetch
195 99495ddb 2021-01-10 stsp will refuse to fetch references from the remote repository's
196 99495ddb 2021-01-10 stsp .Dq refs/remotes/
198 99495ddb 2021-01-10 stsp .Dq refs/got/
200 99495ddb 2021-01-10 stsp In any case, references in the
201 99495ddb 2021-01-10 stsp .Dq refs/tags/
202 99495ddb 2021-01-10 stsp namespace will always be fetched and mapped directly to local references
203 99495ddb 2021-01-10 stsp in the same namespace.
204 459c9b5d 2022-07-03 thomas .It Ic mirror_references Ar yes | no
205 257add31 2020-09-09 stsp This option controls the behaviour of
206 257add31 2020-09-09 stsp .Cm got fetch
207 257add31 2020-09-09 stsp when updating references.
208 257add31 2020-09-09 stsp .Sy Enabling this option can lead to the loss of local commits.
209 257add31 2020-09-09 stsp Maintaining custom changes in a mirror repository is therefore discouraged.
211 257add31 2020-09-09 stsp If this option is not specified or set to
213 257add31 2020-09-09 stsp .Cm got fetch
214 257add31 2020-09-09 stsp will map references of the remote repository into the local repository's
215 257add31 2020-09-09 stsp .Dq refs/remotes/
218 257add31 2020-09-09 stsp If this option is set to
220 257add31 2020-09-09 stsp all branches in the
221 257add31 2020-09-09 stsp .Dq refs/heads/
222 257add31 2020-09-09 stsp namespace will be updated directly to match the corresponding branches in
223 257add31 2020-09-09 stsp the remote repository.
224 6480c871 2021-08-30 stsp .It Ic fetch Brq ...
225 6480c871 2021-08-30 stsp An optional
227 6480c871 2021-08-30 stsp block may contain any of the following configuration settings
229 6480c871 2021-08-30 stsp .Cm got fetch ,
230 6480c871 2021-08-30 stsp overriding corresponding settings in the containing
231 6480c871 2021-08-30 stsp .Ic remote Ar name Brq ...
233 6480c871 2021-08-30 stsp .Bl -bullet
235 6480c871 2021-08-30 stsp .Ic server Ar hostname
237 6480c871 2021-08-30 stsp .Ic repository Ar path
239 824d5f77 2021-09-12 stsp .Ic protocol Ar scheme
241 6480c871 2021-08-30 stsp .Ic port Ar port
243 6480c871 2021-08-30 stsp .Ic branch Brq Ar branch ...
245 6480c871 2021-08-30 stsp .It Ic send Brq ...
246 6480c871 2021-08-30 stsp An optional
248 6480c871 2021-08-30 stsp block may contain any of the following configuration settings
250 6480c871 2021-08-30 stsp .Cm got send ,
251 6480c871 2021-08-30 stsp overriding corresponding settings in the containing
252 6480c871 2021-08-30 stsp .Ic remote Ar name Brq ...
254 6480c871 2021-08-30 stsp .Bl -bullet
256 6480c871 2021-08-30 stsp .Ic server Ar hostname
258 6480c871 2021-08-30 stsp .Ic repository Ar path
260 824d5f77 2021-09-12 stsp .Ic protocol Ar scheme
262 6480c871 2021-08-30 stsp .Ic port Ar port
264 6480c871 2021-08-30 stsp .Ic branch Brq Ar branch ...
268 634fd2c7 2022-11-17 thomas .Sh FILES
269 634fd2c7 2022-11-17 thomas .Bl -tag -width Ds -compact
270 634fd2c7 2022-11-17 thomas .It Pa got.conf
271 634fd2c7 2022-11-17 thomas If present,
273 634fd2c7 2022-11-17 thomas located in the root directory of a Git repository supersedes any relevant
274 634fd2c7 2022-11-17 thomas settings in Git's
275 634fd2c7 2022-11-17 thomas .Pa config
278 634fd2c7 2022-11-17 thomas .It Pa .got/got.conf
279 634fd2c7 2022-11-17 thomas If present,
281 634fd2c7 2022-11-17 thomas located in the
283 634fd2c7 2022-11-17 thomas meta-data directory of a
284 634fd2c7 2022-11-17 thomas .Xr got 1
285 634fd2c7 2022-11-17 thomas work tree supersedes any relevant settings in the repository's
287 634fd2c7 2022-11-17 thomas configuration file and Git's
288 634fd2c7 2022-11-17 thomas .Pa config
291 257add31 2020-09-09 stsp .Sh EXAMPLES
292 257add31 2020-09-09 stsp Configure author information:
293 257add31 2020-09-09 stsp .Bd -literal -offset indent
294 257add31 2020-09-09 stsp author "Flan Hacker <flan_hacker@openbsd.org>"
297 257add31 2020-09-09 stsp Remote repository specification for the Game of Trees repository:
298 257add31 2020-09-09 stsp .Bd -literal -offset indent
299 257add31 2020-09-09 stsp remote "origin" {
300 257add31 2020-09-09 stsp server git.gameoftrees.org
301 257add31 2020-09-09 stsp protocol git
302 257add31 2020-09-09 stsp repository got
303 b8adfa55 2020-09-25 stsp branch { "main" }
309 1795b260 2021-04-02 kn src repository from Github:
310 257add31 2020-09-09 stsp .Bd -literal -offset indent
311 257add31 2020-09-09 stsp remote "origin" {
312 257add31 2020-09-09 stsp repository "openbsd/src"
313 257add31 2020-09-09 stsp server git@github.com
314 257add31 2020-09-09 stsp protocol git+ssh
315 459c9b5d 2022-07-03 thomas mirror_references yes
319 6480c871 2021-08-30 stsp Fetch changes via the Git protocol and send changes via the SSH protocol:
320 6480c871 2021-08-30 stsp .Bd -literal -offset indent
321 6480c871 2021-08-30 stsp remote "origin" {
322 6480c871 2021-08-30 stsp repository my_repo
323 6480c871 2021-08-30 stsp server git.example.com
324 6480c871 2021-08-30 stsp protocol git
326 6480c871 2021-08-30 stsp server git@git.example.com
327 6480c871 2021-08-30 stsp protocol ssh
331 257add31 2020-09-09 stsp .Sh SEE ALSO
332 257add31 2020-09-09 stsp .Xr got 1 ,
333 42536c09 2020-09-11 stsp .Xr git-repository 5 ,
334 50b0790e 2020-09-11 stsp .Xr got-worktree 5
335 53643ae1 2020-09-14 stsp .Sh CAVEATS
337 53643ae1 2020-09-14 stsp offers no way to configure the editor spawned by
338 53643ae1 2020-09-14 stsp .Cm got commit ,
339 53643ae1 2020-09-14 stsp .Cm got histedit ,
340 53643ae1 2020-09-14 stsp .Cm got import ,
342 53643ae1 2020-09-14 stsp .Cm got tag .
343 53643ae1 2020-09-14 stsp This is deliberate and prevents potential arbitrary command execution
344 53643ae1 2020-09-14 stsp as another user when repositories or work trees are shared between users.
345 53643ae1 2020-09-14 stsp Users should set their
349 53643ae1 2020-09-14 stsp environment variables instead.
