1 257add31 2020-09-09 stsp .\"
  2 257add31 2020-09-09 stsp .\" Copyright (c) 2020 Stefan Sperling <stsp@openbsd.org>
  3 257add31 2020-09-09 stsp .\"
  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.
  7 257add31 2020-09-09 stsp .\"
  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.
 15 257add31 2020-09-09 stsp .\"
 16 257add31 2020-09-09 stsp .Dd $Mdocdate$
 17 257add31 2020-09-09 stsp .Dt GOT.CONF 5
 18 257add31 2020-09-09 stsp .Os
 19 257add31 2020-09-09 stsp .Sh NAME
 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
 23 257add31 2020-09-09 stsp .Nm
 24 257add31 2020-09-09 stsp is the run-time configuration file for
 25 257add31 2020-09-09 stsp .Xr got 1 .
 26 257add31 2020-09-09 stsp .Pp
 27 50b0790e 2020-09-11 stsp .Nm
 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
 30 50b0790e 2020-09-11 stsp .Pa .got
 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
 33 50b0790e 2020-09-11 stsp .Xr got 1
 34 50b0790e 2020-09-11 stsp commands executed within this work tree.
 35 50b0790e 2020-09-11 stsp .Pp
 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
 38 257add31 2020-09-09 stsp .Sq #
 39 257add31 2020-09-09 stsp are treated as comments and ignored.
 40 257add31 2020-09-09 stsp .Pp
 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
 46 257add31 2020-09-09 stsp and
 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.
 52 257add31 2020-09-09 stsp .Pp
 53 257add31 2020-09-09 stsp Because
 54 257add31 2020-09-09 stsp .Xr git 1
 55 257add31 2020-09-09 stsp may fail to parse commits without an email address in author data,
 56 257add31 2020-09-09 stsp .Xr got 1
 57 257add31 2020-09-09 stsp attempts to reject author information with a missing email address.
 58 d68f2c0e 2022-07-05 jrick .It Ic signer_id Pa signer-id
 59 d68f2c0e 2022-07-05 jrick Configure a
 60 d68f2c0e 2022-07-05 jrick .Ar signer-id
 61 d68f2c0e 2022-07-05 jrick to sign tag objects.
 62 d68f2c0e 2022-07-05 jrick This key will be used to sign all tag objects unless overridden by
 63 d68f2c0e 2022-07-05 jrick .Cm got tag Fl s Ar signer-id .
 64 d68f2c0e 2022-07-05 jrick .Pp
 65 d68f2c0e 2022-07-05 jrick For SSH-based signatures,
 66 d68f2c0e 2022-07-05 jrick .Ar signer-id
 67 d68f2c0e 2022-07-05 jrick is the path to a file which may refer to either a private SSH key,
 68 d68f2c0e 2022-07-05 jrick or a public SSH key with the private half available via
 69 d68f2c0e 2022-07-05 jrick .Xr ssh-agent 1 .
 70 10c4445c 2022-07-04 stsp .It Ic allowed_signers Pa path
 71 10c4445c 2022-07-04 stsp Configure a
 72 10c4445c 2022-07-04 stsp .Ar path
 73 10c4445c 2022-07-04 stsp to the "allowed signers" file which contains a list of trusted
 74 10c4445c 2022-07-04 stsp SSH signer identities.
 75 10c4445c 2022-07-04 stsp The file will be passed to
 76 10c4445c 2022-07-04 stsp .Xr ssh-keygen 1
 77 10c4445c 2022-07-04 stsp during verification of SSH-based signatures with
 78 10c4445c 2022-07-04 stsp .Cm got tag Fl V .
 79 10c4445c 2022-07-04 stsp The format of the "allowed signers" file is documented in the
 80 10c4445c 2022-07-04 stsp ALLOWED SIGNERS section of
 81 10c4445c 2022-07-04 stsp .Xr ssh-keygen 1 .
 82 10c4445c 2022-07-04 stsp .Pp
 83 10c4445c 2022-07-04 stsp Verification of SSH-based signatures is impossible unless the
 84 10c4445c 2022-07-04 stsp .Ic allowed_signers
 85 10c4445c 2022-07-04 stsp option is set in
 86 10c4445c 2022-07-04 stsp .Nm .
 87 10c4445c 2022-07-04 stsp .It Ic revoked_signers Pa path
 88 10c4445c 2022-07-04 stsp Configure a
 89 10c4445c 2022-07-04 stsp .Ar path
 90 10c4445c 2022-07-04 stsp to the optional "revoked signers" file, which contains a list of revoked
 91 10c4445c 2022-07-04 stsp SSH signer identities.
 92 10c4445c 2022-07-04 stsp This file is passed to
 93 10c4445c 2022-07-04 stsp .Xr ssh-keygen 1
 94 10c4445c 2022-07-04 stsp during signature verification with
 95 10c4445c 2022-07-04 stsp .Cm got tag Fl V .
 96 10c4445c 2022-07-04 stsp Revoked identities are no longer considered trustworthy and verification
 97 10c4445c 2022-07-04 stsp 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
101 257add31 2020-09-09 stsp .Ar name
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
104 6480c871 2021-08-30 stsp and
105 6480c871 2021-08-30 stsp .Cm got send .
106 257add31 2020-09-09 stsp .Pp
107 257add31 2020-09-09 stsp Information about this repository is declared in a block of options
108 257add31 2020-09-09 stsp enclosed in curly brackets:
109 257add31 2020-09-09 stsp .Bl -tag -width Ds
110 257add31 2020-09-09 stsp .It Ic server Ar hostname
111 257add31 2020-09-09 stsp Defines the hostname to use for contacting the remote repository's server.
112 257add31 2020-09-09 stsp .It Ic repository Ar path
113 257add31 2020-09-09 stsp Defines the path to the repository on the remote repository's server.
114 257add31 2020-09-09 stsp .It Ic protocol Ar scheme
115 257add31 2020-09-09 stsp Defines the protocol to use for communicating with the remote repository's
116 257add31 2020-09-09 stsp server.
117 257add31 2020-09-09 stsp .Pp
118 257add31 2020-09-09 stsp The following protocol schemes are supported:
119 257add31 2020-09-09 stsp .Bl -tag -width git+ssh
120 257add31 2020-09-09 stsp .It git
121 257add31 2020-09-09 stsp The Git protocol as implemented by the
122 257add31 2020-09-09 stsp .Xr git-daemon 1
123 257add31 2020-09-09 stsp server.
124 257add31 2020-09-09 stsp Use of this protocol is discouraged since it supports neither authentication
125 257add31 2020-09-09 stsp nor encryption.
126 257add31 2020-09-09 stsp .It git+ssh
127 257add31 2020-09-09 stsp The Git protocol wrapped in an authenticated and encrypted
128 257add31 2020-09-09 stsp .Xr ssh 1
129 257add31 2020-09-09 stsp tunnel.
130 257add31 2020-09-09 stsp With this protocol the hostname may contain an embedded username for
131 257add31 2020-09-09 stsp .Xr ssh 1
132 257add31 2020-09-09 stsp to use:
133 257add31 2020-09-09 stsp .Mt user@hostname
134 257add31 2020-09-09 stsp .It ssh
135 257add31 2020-09-09 stsp Short alias for git+ssh.
136 257add31 2020-09-09 stsp .El
137 257add31 2020-09-09 stsp .It Ic port Ar port
138 257add31 2020-09-09 stsp Defines the port to use for connecting to the remote repository's server.
139 257add31 2020-09-09 stsp The
140 257add31 2020-09-09 stsp .Ar port
141 257add31 2020-09-09 stsp can be specified by number or name.
142 257add31 2020-09-09 stsp The port name to number mappings are found in the file
143 257add31 2020-09-09 stsp .Pa /etc/services ;
144 257add31 2020-09-09 stsp see
145 257add31 2020-09-09 stsp .Xr services 5
146 257add31 2020-09-09 stsp for details.
147 257add31 2020-09-09 stsp If not specified, the default port of the specified
148 257add31 2020-09-09 stsp .Cm protocol
149 257add31 2020-09-09 stsp will be used.
150 b8adfa55 2020-09-25 stsp .It Ic branch Brq Ar branch ...
151 b8adfa55 2020-09-25 stsp Specify one or more branches which
152 b8adfa55 2020-09-25 stsp .Cm got fetch
153 6480c871 2021-08-30 stsp and
154 6480c871 2021-08-30 stsp .Cm got send
155 93f8a337 2021-08-30 naddy should fetch from and send to the remote repository by default.
156 b8adfa55 2020-09-25 stsp The list of branches specified here can be overridden at the
157 b8adfa55 2020-09-25 stsp .Cm got fetch
158 6480c871 2021-08-30 stsp and
159 6480c871 2021-08-30 stsp .Cm got send
160 6480c871 2021-08-30 stsp command lines with the
161 b8adfa55 2020-09-25 stsp .Fl b
162 b8adfa55 2020-09-25 stsp option.
163 f1bf60d1 2022-07-03 stsp .It Ic fetch_all_branches Ar yes | no
164 0c8b29c5 2021-01-05 stsp This option controls whether
165 0c8b29c5 2021-01-05 stsp .Cm got fetch
166 0c8b29c5 2021-01-05 stsp will fetch all branches from the remote repository by default.
167 0c8b29c5 2021-01-05 stsp If enabled, this behaviour can be overridden at the
168 0c8b29c5 2021-01-05 stsp .Cm got fetch
169 0c8b29c5 2021-01-05 stsp command line with the
170 0c8b29c5 2021-01-05 stsp .Fl b
171 0c8b29c5 2021-01-05 stsp option, and any
172 0c8b29c5 2021-01-05 stsp .Cm branch
173 0c8b29c5 2021-01-05 stsp configuration settings for this remote repository will be ignored.
174 99495ddb 2021-01-10 stsp .It Ic reference Brq Ar reference ...
175 99495ddb 2021-01-10 stsp Specify one or more arbitrary references which
176 99495ddb 2021-01-10 stsp .Cm got fetch
177 99495ddb 2021-01-10 stsp should fetch by default, in addition to the branches and tags that will
178 99495ddb 2021-01-10 stsp be fetched.
179 99495ddb 2021-01-10 stsp The list of references specified here can be overridden at the
180 99495ddb 2021-01-10 stsp .Cm got fetch
181 99495ddb 2021-01-10 stsp command line with the
182 99495ddb 2021-01-10 stsp .Fl R
183 99495ddb 2021-01-10 stsp option.
184 99495ddb 2021-01-10 stsp .Cm got fetch
185 99495ddb 2021-01-10 stsp will refuse to fetch references from the remote repository's
186 99495ddb 2021-01-10 stsp .Dq refs/remotes/
187 99495ddb 2021-01-10 stsp or
188 99495ddb 2021-01-10 stsp .Dq refs/got/
189 99495ddb 2021-01-10 stsp namespace.
190 99495ddb 2021-01-10 stsp In any case, references in the
191 99495ddb 2021-01-10 stsp .Dq refs/tags/
192 99495ddb 2021-01-10 stsp namespace will always be fetched and mapped directly to local references
193 99495ddb 2021-01-10 stsp in the same namespace.
194 26e6f38e 2022-07-03 stsp .It Ic mirror_references Ar yes | no
195 257add31 2020-09-09 stsp This option controls the behaviour of
196 257add31 2020-09-09 stsp .Cm got fetch
197 257add31 2020-09-09 stsp when updating references.
198 257add31 2020-09-09 stsp .Sy Enabling this option can lead to the loss of local commits.
199 257add31 2020-09-09 stsp Maintaining custom changes in a mirror repository is therefore discouraged.
200 257add31 2020-09-09 stsp .Pp
201 257add31 2020-09-09 stsp If this option is not specified or set to
202 257add31 2020-09-09 stsp .Ar no ,
203 257add31 2020-09-09 stsp .Cm got fetch
204 257add31 2020-09-09 stsp will map references of the remote repository into the local repository's
205 257add31 2020-09-09 stsp .Dq refs/remotes/
206 257add31 2020-09-09 stsp namespace.
207 257add31 2020-09-09 stsp .Pp
208 257add31 2020-09-09 stsp If this option is set to
209 257add31 2020-09-09 stsp .Ar yes ,
210 257add31 2020-09-09 stsp all branches in the
211 257add31 2020-09-09 stsp .Dq refs/heads/
212 257add31 2020-09-09 stsp namespace will be updated directly to match the corresponding branches in
213 257add31 2020-09-09 stsp the remote repository.
214 6480c871 2021-08-30 stsp .It Ic fetch Brq ...
215 6480c871 2021-08-30 stsp An optional
216 6480c871 2021-08-30 stsp .Ic fetch
217 6480c871 2021-08-30 stsp block may contain any of the following configuration settings
218 6480c871 2021-08-30 stsp for use by
219 6480c871 2021-08-30 stsp .Cm got fetch ,
220 6480c871 2021-08-30 stsp overriding corresponding settings in the containing
221 6480c871 2021-08-30 stsp .Ic remote Ar name Brq ...
222 6480c871 2021-08-30 stsp block.
223 6480c871 2021-08-30 stsp .Bl -bullet
224 6480c871 2021-08-30 stsp .It
225 6480c871 2021-08-30 stsp .Ic server Ar hostname
226 6480c871 2021-08-30 stsp .It
227 6480c871 2021-08-30 stsp .Ic repository Ar path
228 6480c871 2021-08-30 stsp .It
229 824d5f77 2021-09-12 stsp .Ic protocol Ar scheme
230 6480c871 2021-08-30 stsp .It
231 6480c871 2021-08-30 stsp .Ic port Ar port
232 6480c871 2021-08-30 stsp .It
233 6480c871 2021-08-30 stsp .Ic branch Brq Ar branch ...
234 257add31 2020-09-09 stsp .El
235 6480c871 2021-08-30 stsp .It Ic send Brq ...
236 6480c871 2021-08-30 stsp An optional
237 6480c871 2021-08-30 stsp .Ic send
238 6480c871 2021-08-30 stsp block may contain any of the following configuration settings
239 6480c871 2021-08-30 stsp for use by
240 6480c871 2021-08-30 stsp .Cm got send ,
241 6480c871 2021-08-30 stsp overriding corresponding settings in the containing
242 6480c871 2021-08-30 stsp .Ic remote Ar name Brq ...
243 6480c871 2021-08-30 stsp block.
244 6480c871 2021-08-30 stsp .Bl -bullet
245 6480c871 2021-08-30 stsp .It
246 6480c871 2021-08-30 stsp .Ic server Ar hostname
247 6480c871 2021-08-30 stsp .It
248 6480c871 2021-08-30 stsp .Ic repository Ar path
249 6480c871 2021-08-30 stsp .It
250 824d5f77 2021-09-12 stsp .Ic protocol Ar scheme
251 6480c871 2021-08-30 stsp .It
252 6480c871 2021-08-30 stsp .Ic port Ar port
253 6480c871 2021-08-30 stsp .It
254 6480c871 2021-08-30 stsp .Ic branch Brq Ar branch ...
255 1795b260 2021-04-02 kn .El
256 6480c871 2021-08-30 stsp .El
257 6480c871 2021-08-30 stsp .El
258 257add31 2020-09-09 stsp .Sh EXAMPLES
259 257add31 2020-09-09 stsp Configure author information:
260 257add31 2020-09-09 stsp .Bd -literal -offset indent
261 257add31 2020-09-09 stsp author "Flan Hacker <flan_hacker@openbsd.org>"
262 257add31 2020-09-09 stsp .Ed
263 257add31 2020-09-09 stsp .Pp
264 257add31 2020-09-09 stsp Remote repository specification for the Game of Trees repository:
265 257add31 2020-09-09 stsp .Bd -literal -offset indent
266 257add31 2020-09-09 stsp remote "origin" {
267 257add31 2020-09-09 stsp 	server git.gameoftrees.org
268 257add31 2020-09-09 stsp 	protocol git
269 257add31 2020-09-09 stsp 	repository got
270 b8adfa55 2020-09-25 stsp 	branch { "main" }
271 257add31 2020-09-09 stsp }
272 257add31 2020-09-09 stsp .Ed
273 257add31 2020-09-09 stsp .Pp
274 1795b260 2021-04-02 kn Mirror the
275 1795b260 2021-04-02 kn .Ox
276 1795b260 2021-04-02 kn src repository from Github:
277 257add31 2020-09-09 stsp .Bd -literal -offset indent
278 257add31 2020-09-09 stsp remote "origin" {
279 257add31 2020-09-09 stsp 	repository "openbsd/src"
280 257add31 2020-09-09 stsp 	server git@github.com
281 257add31 2020-09-09 stsp 	protocol git+ssh
282 26e6f38e 2022-07-03 stsp 	mirror_references yes
283 257add31 2020-09-09 stsp }
284 257add31 2020-09-09 stsp .Ed
285 6480c871 2021-08-30 stsp .Pp
286 6480c871 2021-08-30 stsp Fetch changes via the Git protocol and send changes via the SSH protocol:
287 6480c871 2021-08-30 stsp .Bd -literal -offset indent
288 6480c871 2021-08-30 stsp remote "origin" {
289 6480c871 2021-08-30 stsp 	repository my_repo
290 6480c871 2021-08-30 stsp 	server git.example.com
291 6480c871 2021-08-30 stsp 	protocol git
292 6480c871 2021-08-30 stsp 	send {
293 6480c871 2021-08-30 stsp 		server git@git.example.com
294 6480c871 2021-08-30 stsp 		protocol ssh
295 6480c871 2021-08-30 stsp 	}
296 6480c871 2021-08-30 stsp }
297 6480c871 2021-08-30 stsp .Ed
298 257add31 2020-09-09 stsp .Sh FILES
299 257add31 2020-09-09 stsp .Bl -tag -width Ds -compact
300 257add31 2020-09-09 stsp .It Pa got.conf
301 50b0790e 2020-09-11 stsp If present,
302 257add31 2020-09-09 stsp .Nm
303 50b0790e 2020-09-11 stsp located in the root directory of a Git repository supersedes any relevant
304 50b0790e 2020-09-11 stsp settings in Git's
305 257add31 2020-09-09 stsp .Pa config
306 257add31 2020-09-09 stsp file.
307 50b0790e 2020-09-11 stsp .Pp
308 50b0790e 2020-09-11 stsp .It Pa .got/got.conf
309 50b0790e 2020-09-11 stsp If present,
310 50b0790e 2020-09-11 stsp .Nm
311 50b0790e 2020-09-11 stsp located in the
312 50b0790e 2020-09-11 stsp .Pa .got
313 50b0790e 2020-09-11 stsp meta-data directory of a
314 50b0790e 2020-09-11 stsp .Xr got 1
315 50b0790e 2020-09-11 stsp work tree supersedes any relevant settings in the repository's
316 50b0790e 2020-09-11 stsp .Nm
317 50b0790e 2020-09-11 stsp configuration file and Git's
318 50b0790e 2020-09-11 stsp .Pa config
319 50b0790e 2020-09-11 stsp file.
320 257add31 2020-09-09 stsp .El
321 257add31 2020-09-09 stsp .Sh SEE ALSO
322 257add31 2020-09-09 stsp .Xr got 1 ,
323 42536c09 2020-09-11 stsp .Xr git-repository 5 ,
324 50b0790e 2020-09-11 stsp .Xr got-worktree 5
325 53643ae1 2020-09-14 stsp .Sh CAVEATS
326 53643ae1 2020-09-14 stsp .Nm
327 53643ae1 2020-09-14 stsp offers no way to configure the editor spawned by
328 53643ae1 2020-09-14 stsp .Cm got commit ,
329 53643ae1 2020-09-14 stsp .Cm got histedit ,
330 53643ae1 2020-09-14 stsp .Cm got import ,
331 53643ae1 2020-09-14 stsp or
332 53643ae1 2020-09-14 stsp .Cm got tag .
333 53643ae1 2020-09-14 stsp This is deliberate and prevents potential arbitrary command execution
334 53643ae1 2020-09-14 stsp as another user when repositories or work trees are shared between users.
335 53643ae1 2020-09-14 stsp Users should set their
336 53643ae1 2020-09-14 stsp .Ev VISUAL
337 53643ae1 2020-09-14 stsp or
338 53643ae1 2020-09-14 stsp .Ev EDITOR
339 53643ae1 2020-09-14 stsp environment variables instead.