4 <meta charset="utf-8"/>
5 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
6 <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
7 <title>GOT.CONF(5)</title>
9 <!-- This is an automatically generated file. Do not edit.
10 Copyright (c) 2020 Stefan Sperling <stsp@openbsd.org>
12 Permission to use, copy, modify, and distribute this software for any
13 purpose with or without fee is hereby granted, provided that the above
14 copyright notice and this permission notice appear in all copies.
16 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
17 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
18 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
19 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
20 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
21 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
22 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25 <div class="head" role="doc-pageheader" aria-label="Manual header
26 line"><span class="head-ltitle">GOT.CONF(5)</span> <span class="head-vol">File
27 Formats Manual</span> <span class="head-rtitle">GOT.CONF(5)</span></div>
28 <main class="manual-text">
30 <h2 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h2>
31 <p class="Pp"><code class="Nm">got.conf</code> —
32 <span class="Nd" role="doc-subtitle">Game of Trees configuration
36 <h2 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h2>
37 <p class="Pp"><code class="Nm">got.conf</code> is the run-time configuration
38 file for <a class="Xr" aria-label="got, section 1">got(1)</a>.</p>
39 <p class="Pp"><code class="Nm">got.conf</code> may be present in the root
40 directory of a Git repository for repository-wide settings, or in the
41 <span class="Pa">.got</span> meta-data directory of a work tree to override
42 repository-wide settings for <a class="Xr" aria-label="got, section
43 1">got(1)</a> commands executed within this work tree.</p>
44 <p class="Pp">The file format is line-based, with one configuration directive
45 per line. Comments can be put anywhere in the file using a hash mark
46 (‘#’), and extend to the end of the current line. Arguments
47 names not beginning with a letter, digit or underscore, as well as reserved
48 words (such as <code class="Ic">author</code>,
49 <code class="Ic">remote</code> <span class="No">or</span>
50 <code class="Ic">port</code>), must be quoted. Arguments containing
51 whitespace should be surrounded by double quotes (").</p>
52 <p class="Pp">The available configuration directives are as follows:</p>
54 <dt id="author"><a class="permalink" href="#author"><code class="Ic">author</code></a>
55 “Real Name <email address>”</dt>
56 <dd>Configure the author's name and email address for <code class="Cm">got
57 commit</code> and <code class="Cm">got import</code> when operating on
58 this repository. Author information specified here overrides the
59 <code class="Ev">GOT_AUTHOR</code> environment variable.
60 <p class="Pp">Because <a class="Xr" aria-label="git, section 1">git(1)</a>
61 may fail to parse commits without an email address in author data,
62 <a class="Xr" aria-label="got, section 1">got(1)</a> attempts to reject
63 author information with a missing email address.</p>
65 <dt id="signer_id"><a class="permalink" href="#signer_id"><code class="Ic">signer_id</code></a>
66 <span class="Pa">signer-id</span></dt>
67 <dd>Configure a <var class="Ar">signer-id</var> to sign tag objects. This key
68 will be used to sign all tag objects unless overridden by
69 <code class="Cm">got tag</code> <code class="Fl">-s</code>
70 <var class="Ar">signer-id</var>.
71 <p class="Pp">For SSH-based signatures, <var class="Ar">signer-id</var> is
72 the path to a file which may refer to either a private SSH key, or a
73 public SSH key with the private half available via
74 <a class="Xr" aria-label="ssh-agent, section 1">ssh-agent(1)</a>.</p>
76 <dt id="allowed_signers"><a class="permalink" href="#allowed_signers"><code class="Ic">allowed_signers</code></a>
77 <span class="Pa">path</span></dt>
78 <dd>Configure a <var class="Ar">path</var> to the "allowed signers"
79 file which contains a list of trusted SSH signer identities. The file will
80 be passed to <a class="Xr" aria-label="ssh-keygen, section
81 1">ssh-keygen(1)</a> during verification of SSH-based signatures with
82 <code class="Cm">got tag</code> <code class="Fl">-V</code>. The format of
83 the "allowed signers" file is documented in the ALLOWED SIGNERS
84 section of <a class="Xr" aria-label="ssh-keygen, section
86 <p class="Pp">Verification of SSH-based signatures is impossible unless the
87 <code class="Ic">allowed_signers</code> option is set in
88 <code class="Nm">got.conf</code>.</p>
90 <dt id="revoked_signers"><a class="permalink" href="#revoked_signers"><code class="Ic">revoked_signers</code></a>
91 <span class="Pa">path</span></dt>
92 <dd>Configure a <var class="Ar">path</var> to the optional "revoked
93 signers" file, which contains a list of revoked SSH signer
94 identities. This file is passed to <a class="Xr" aria-label="ssh-keygen,
95 section 1">ssh-keygen(1)</a> during signature verification with
96 <code class="Cm">got tag</code> <code class="Fl">-V</code>. Revoked
97 identities are no longer considered trustworthy and verification of
98 relevant signatures will fail.</dd>
99 <dt id="remote"><a class="permalink" href="#remote"><code class="Ic">remote</code></a>
100 <var class="Ar">name</var> {...}</dt>
101 <dd>Define a remote repository. The specified <var class="Ar">name</var> can
102 be used to refer to the remote repository on the command line of
103 <code class="Cm">got fetch</code> and <code class="Cm">got send</code>.
104 <p class="Pp">When repositories are shared between multiple users on the
105 system, it is recommended that users configure their trusted remote
106 repositories in each of their work-trees'
107 <code class="Nm">got.conf</code> files, overriding corresponding
108 repository-wide settings. This can avoid potentially undesirable
109 connections to remote repositories placed into the shared repository's
110 <code class="Nm">got.conf</code> file by other users.</p>
111 <p class="Pp">Information about a repository is declared in a block of
112 options enclosed in curly brackets:</p>
114 <dt id="server"><a class="permalink" href="#server"><code class="Ic">server</code></a>
115 <var class="Ar">hostname</var></dt>
116 <dd>Defines the hostname to use for contacting the remote repository's
118 <dt id="repository"><a class="permalink" href="#repository"><code class="Ic">repository</code></a>
119 <var class="Ar">path</var></dt>
120 <dd>Defines the path to the repository on the remote repository's
122 <dt id="protocol"><a class="permalink" href="#protocol"><code class="Ic">protocol</code></a>
123 <var class="Ar">scheme</var></dt>
124 <dd>Defines the protocol to use for communicating with the remote
126 <p class="Pp">The following protocol schemes are supported:</p>
129 <dd>The Git protocol as implemented by the
130 <a class="Xr" aria-label="git-daemon, section 1">git-daemon(1)</a>
131 server. Use of this protocol is discouraged since it supports
132 neither authentication nor encryption.</dd>
134 <dd>The Git protocol wrapped in an authenticated and encrypted
135 <a class="Xr" aria-label="ssh, section 1">ssh(1)</a> tunnel. With
136 this protocol the hostname may contain an embedded username for
137 <a class="Xr" aria-label="ssh, section 1">ssh(1)</a> to use:
138 <a class="Mt" href="mailto:user@hostname">user@hostname</a></dd>
140 <dd>The “smart” Git HTTP protocol. Not compatible with
141 servers using the “dumb” Git HTTP protocol.
142 <p class="Pp">The “smart” Git HTTP protocol is
143 supported by <code class="Cm">got clone</code> and
144 <code class="Cm">got fetch</code>, but not by
145 <code class="Cm">got send</code>. To send from a repository
146 cloned over HTTP, add a <code class="Ic">send</code> block (see
147 below) to ensure that the “ssh://” protocol will
148 be used by <code class="Cm">got send</code>.</p>
149 <p class="Pp">Use of this protocol is discouraged since it supports
150 neither authentication nor encryption.</p>
153 <dd>The “smart” Git HTTP protocol wrapped in
157 <dt id="port"><a class="permalink" href="#port"><code class="Ic">port</code></a>
158 <var class="Ar">port</var></dt>
159 <dd>Defines the port to use for connecting to the remote repository's
160 server. The <var class="Ar">port</var> can be specified by number or
161 name. The port name to number mappings are found in the file
162 <span class="Pa">/etc/services</span>; see
163 <a class="Xr" aria-label="services, section 5">services(5)</a> for
164 details. If not specified, the default port of the specified
165 <code class="Cm">protocol</code> will be used.</dd>
166 <dt id="branch"><a class="permalink" href="#branch"><code class="Ic">branch</code></a>
167 {<var class="Ar">branch ...</var>}</dt>
168 <dd>Specify one or more branches which <code class="Cm">got fetch</code>
169 and <code class="Cm">got send</code> should fetch from and send to the
170 remote repository by default. The list of branches specified here can
171 be overridden at the <code class="Cm">got fetch</code> and
172 <code class="Cm">got send</code> command lines with the
173 <code class="Fl">-b</code> option.</dd>
174 <dt id="fetch_all_branches"><a class="permalink" href="#fetch_all_branches"><code class="Ic">fetch_all_branches</code></a>
175 <var class="Ar">yes</var> | <var class="Ar">no</var></dt>
176 <dd>This option controls whether <code class="Cm">got fetch</code> will
177 fetch all branches from the remote repository by default. If enabled,
178 this behaviour can be overridden at the <code class="Cm">got
179 fetch</code> command line with the <code class="Fl">-b</code> option,
180 and any <code class="Cm">branch</code> configuration settings for this
181 remote repository will be ignored.</dd>
182 <dt id="reference"><a class="permalink" href="#reference"><code class="Ic">reference</code></a>
183 {<var class="Ar">reference ...</var>}</dt>
184 <dd>Specify one or more arbitrary references which <code class="Cm">got
185 fetch</code> should fetch by default, in addition to the branches and
186 tags that will be fetched. The list of references specified here can
187 be overridden at the <code class="Cm">got fetch</code> command line
188 with the <code class="Fl">-R</code> option. <code class="Cm">got
189 fetch</code> will refuse to fetch references from the remote
190 repository's “refs/remotes/” or
191 “refs/got/” namespace. In any case, references in the
192 “refs/tags/” namespace will always be fetched and mapped
193 directly to local references in the same namespace.</dd>
194 <dt id="mirror_references"><a class="permalink" href="#mirror_references"><code class="Ic">mirror_references</code></a>
195 <var class="Ar">yes</var> | <var class="Ar">no</var></dt>
196 <dd>This option controls the behaviour of <code class="Cm">got
197 fetch</code> when updating references.
198 <a class="permalink" href="#Enabling"><b class="Sy" id="Enabling">Enabling
199 this option can lead to the loss of local commits.</b></a> Maintaining
200 custom changes in a mirror repository is therefore discouraged.
201 <p class="Pp">If this option is not specified or set to
202 <var class="Ar">no</var>, <code class="Cm">got fetch</code> will map
203 references of the remote repository into the local repository's
204 “refs/remotes/” namespace.</p>
205 <p class="Pp">If this option is set to <var class="Ar">yes</var>, all
206 branches in the “refs/heads/” namespace will be
207 updated directly to match the corresponding branches in the remote
210 <dt id="fetch"><a class="permalink" href="#fetch"><code class="Ic">fetch</code></a>
212 <dd>An optional <code class="Ic">fetch</code> block may contain any of the
213 following configuration settings for use by <code class="Cm">got
214 fetch</code>, overriding corresponding settings in the containing
215 <code class="Ic">remote</code> <var class="Ar">name</var> {...} block.
216 <ul class="Bl-bullet">
217 <li id="server~2"><a class="permalink" href="#server~2"><code class="Ic">server</code></a>
218 <var class="Ar">hostname</var></li>
219 <li id="repository~2"><a class="permalink" href="#repository~2"><code class="Ic">repository</code></a>
220 <var class="Ar">path</var></li>
221 <li id="protocol~2"><a class="permalink" href="#protocol~2"><code class="Ic">protocol</code></a>
222 <var class="Ar">scheme</var></li>
223 <li id="port~2"><a class="permalink" href="#port~2"><code class="Ic">port</code></a>
224 <var class="Ar">port</var></li>
225 <li id="branch~2"><a class="permalink" href="#branch~2"><code class="Ic">branch</code></a>
226 {<var class="Ar">branch ...</var>}</li>
229 <dt id="send"><a class="permalink" href="#send"><code class="Ic">send</code></a>
231 <dd>An optional <code class="Ic">send</code> block may contain any of the
232 following configuration settings for use by <code class="Cm">got
233 send</code>, overriding corresponding settings in the containing
234 <code class="Ic">remote</code> <var class="Ar">name</var> {...} block.
235 <ul class="Bl-bullet">
236 <li id="server~3"><a class="permalink" href="#server~3"><code class="Ic">server</code></a>
237 <var class="Ar">hostname</var></li>
238 <li id="repository~3"><a class="permalink" href="#repository~3"><code class="Ic">repository</code></a>
239 <var class="Ar">path</var></li>
240 <li id="protocol~3"><a class="permalink" href="#protocol~3"><code class="Ic">protocol</code></a>
241 <var class="Ar">scheme</var></li>
242 <li id="port~3"><a class="permalink" href="#port~3"><code class="Ic">port</code></a>
243 <var class="Ar">port</var></li>
244 <li id="branch~3"><a class="permalink" href="#branch~3"><code class="Ic">branch</code></a>
245 {<var class="Ar">branch ...</var>}</li>
253 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
254 <dl class="Bl-tag Bl-compact">
255 <dt><span class="Pa">got.conf</span></dt>
256 <dd>If present, <code class="Nm">got.conf</code> located in the root directory
257 of a Git repository supersedes any relevant settings in Git's
258 <span class="Pa">config</span> file.
261 <dt><span class="Pa">.got/got.conf</span></dt>
262 <dd>If present, <code class="Nm">got.conf</code> located in the
263 <span class="Pa">.got</span> meta-data directory of a
264 <a class="Xr" aria-label="got, section 1">got(1)</a> work tree supersedes
265 any relevant settings in the repository's <code class="Nm">got.conf</code>
266 configuration file and Git's <span class="Pa">config</span> file.</dd>
270 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
271 <p class="Pp">Configure author information:</p>
272 <div class="Bd Pp Bd-indent Li">
273 <pre>author "Flan Hacker <flan_hacker@openbsd.org>"</pre>
275 <p class="Pp">Remote repository specification for the Game of Trees
277 <div class="Bd Pp Bd-indent Li">
278 <pre>remote "origin" {
279 server anonymous@got.gameoftrees.org
282 branch { "main" }
285 <p class="Pp">Mirror the <span class="Ux">OpenBSD</span> src repository from
287 <div class="Bd Pp Bd-indent Li">
288 <pre>remote "origin" {
289 repository "openbsd/src"
290 server git@github.com
292 mirror_references yes
295 <p class="Pp">Fetch changes via the Git protocol and send changes via the SSH
297 <div class="Bd Pp Bd-indent Li">
298 <pre>remote "origin" {
300 server git.example.com
303 server git@git.example.com
310 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
312 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
313 <a class="Xr" aria-label="git-repository, section 5">git-repository(5)</a>,
314 <a class="Xr" aria-label="got-worktree, section 5">got-worktree(5)</a></p>
317 <h2 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h2>
318 <p class="Pp"><code class="Nm">got.conf</code> offers no way to configure the
319 editor spawned by <code class="Cm">got commit</code>, <code class="Cm">got
320 histedit</code>, <code class="Cm">got import</code>, or <code class="Cm">got
321 tag</code>. This is deliberate and prevents potential arbitrary command
322 execution as another user when repositories or work trees are shared between
323 users. Users should set their <code class="Ev">VISUAL</code> or
324 <code class="Ev">EDITOR</code> environment variables instead.</p>
327 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
328 line"><span class="foot-left"></span><span class="foot-date">November 21,
329 2024</span> <span class="foot-os">OpenBSD 7.6</span></div>
