1 <!DOCTYPE html>
2 <html>
3 <head>
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>
8 </head>
9 <!-- This is an automatically generated file. Do not edit.
10 Copyright (c) 2020 Stefan Sperling <>
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.
23 -->
24 <body>
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">
29 <section class="Sh">
30 <h2 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h2>
31 <p class="Pp"><code class="Nm">got.conf</code> &#x2014;
32 <span class="Nd" role="doc-subtitle">Game of Trees configuration
33 file</span></p>
34 </section>
35 <section class="Sh">
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. Any lines beginning with a &#x2018;#&#x2019; are treated as
46 comments and ignored.</p>
47 <p class="Pp">The available configuration directives are as follows:</p>
48 <dl class="Bl-tag">
49 <dt id="author"><a class="permalink" href="#author"><code class="Ic">author</code></a>
50 &#x201C;Real Name &lt;email address&gt;&#x201D;</dt>
51 <dd>Configure the author's name and email address for <code class="Cm">got
52 commit</code> and <code class="Cm">got import</code> when operating on
53 this repository. Author information specified here overrides the
54 <code class="Ev">GOT_AUTHOR</code> environment variable.
55 <p class="Pp">Because <a class="Xr" aria-label="git, section 1">git(1)</a>
56 may fail to parse commits without an email address in author data,
57 <a class="Xr" aria-label="got, section 1">got(1)</a> attempts to reject
58 author information with a missing email address.</p>
59 </dd>
60 <dt id="signer_id"><a class="permalink" href="#signer_id"><code class="Ic">signer_id</code></a>
61 <span class="Pa">signer-id</span></dt>
62 <dd>Configure a <var class="Ar">signer-id</var> to sign tag objects. This key
63 will be used to sign all tag objects unless overridden by
64 <code class="Cm">got tag</code> <code class="Fl">-s</code>
65 <var class="Ar">signer-id</var>.
66 <p class="Pp">For SSH-based signatures, <var class="Ar">signer-id</var> is
67 the path to a file which may refer to either a private SSH key, or a
68 public SSH key with the private half available via
69 <a class="Xr" aria-label="ssh-agent, section 1">ssh-agent(1)</a>.</p>
70 </dd>
71 <dt id="allowed_signers"><a class="permalink" href="#allowed_signers"><code class="Ic">allowed_signers</code></a>
72 <span class="Pa">path</span></dt>
73 <dd>Configure a <var class="Ar">path</var> to the &quot;allowed signers&quot;
74 file which contains a list of trusted SSH signer identities. The file will
75 be passed to <a class="Xr" aria-label="ssh-keygen, section
76 1">ssh-keygen(1)</a> during verification of SSH-based signatures with
77 <code class="Cm">got tag</code> <code class="Fl">-V</code>. The format of
78 the &quot;allowed signers&quot; file is documented in the ALLOWED SIGNERS
79 section of <a class="Xr" aria-label="ssh-keygen, section
80 1">ssh-keygen(1)</a>.
81 <p class="Pp">Verification of SSH-based signatures is impossible unless the
82 <code class="Ic">allowed_signers</code> option is set in
83 <code class="Nm">got.conf</code>.</p>
84 </dd>
85 <dt id="revoked_signers"><a class="permalink" href="#revoked_signers"><code class="Ic">revoked_signers</code></a>
86 <span class="Pa">path</span></dt>
87 <dd>Configure a <var class="Ar">path</var> to the optional &quot;revoked
88 signers&quot; file, which contains a list of revoked SSH signer
89 identities. This file is passed to <a class="Xr" aria-label="ssh-keygen,
90 section 1">ssh-keygen(1)</a> during signature verification with
91 <code class="Cm">got tag</code> <code class="Fl">-V</code>. Revoked
92 identities are no longer considered trustworthy and verification of
93 relevant signatures will fail.</dd>
94 <dt id="remote"><a class="permalink" href="#remote"><code class="Ic">remote</code></a>
95 <var class="Ar">name</var> {...}</dt>
96 <dd>Define a remote repository. The specified <var class="Ar">name</var> can
97 be used to refer to the remote repository on the command line of
98 <code class="Cm">got fetch</code> and <code class="Cm">got send</code>.
99 <p class="Pp">When repositories are shared between multiple users on the
100 system, it is recommended that users configure their trusted remote
101 repositories in each of their work-trees'
102 <code class="Nm">got.conf</code> files, overriding corresponding
103 repository-wide settings. This can avoid potentially undesirable
104 connections to remote repositories placed into the shared repository's
105 <code class="Nm">got.conf</code> file by other users.</p>
106 <p class="Pp">Information about a repository is declared in a block of
107 options enclosed in curly brackets:</p>
108 <dl class="Bl-tag">
109 <dt id="server"><a class="permalink" href="#server"><code class="Ic">server</code></a>
110 <var class="Ar">hostname</var></dt>
111 <dd>Defines the hostname to use for contacting the remote repository's
112 server.</dd>
113 <dt id="repository"><a class="permalink" href="#repository"><code class="Ic">repository</code></a>
114 <var class="Ar">path</var></dt>
115 <dd>Defines the path to the repository on the remote repository's
116 server.</dd>
117 <dt id="protocol"><a class="permalink" href="#protocol"><code class="Ic">protocol</code></a>
118 <var class="Ar">scheme</var></dt>
119 <dd>Defines the protocol to use for communicating with the remote
120 repository's server.
121 <p class="Pp">The following protocol schemes are supported:</p>
122 <dl class="Bl-tag">
123 <dt>git</dt>
124 <dd>The Git protocol as implemented by the
125 <a class="Xr" aria-label="git-daemon, section 1">git-daemon(1)</a>
126 server. Use of this protocol is discouraged since it supports
127 neither authentication nor encryption.</dd>
128 <dt>ssh</dt>
129 <dd>The Git protocol wrapped in an authenticated and encrypted
130 <a class="Xr" aria-label="ssh, section 1">ssh(1)</a> tunnel. With
131 this protocol the hostname may contain an embedded username for
132 <a class="Xr" aria-label="ssh, section 1">ssh(1)</a> to use:
133 <a class="Mt" href="mailto:user@hostname">user@hostname</a></dd>
134 <dt>http</dt>
135 <dd>The &#x201C;smart&#x201D; Git HTTP protocol. Not compatible with
136 servers using the &#x201C;dumb&#x201D; Git HTTP protocol.
137 <p class="Pp">The &#x201C;smart&#x201D; Git HTTP protocol is
138 supported by <code class="Cm">got clone</code> and
139 <code class="Cm">got fetch</code>, but not by
140 <code class="Cm">got send</code>. To send from a repository
141 cloned over HTTP, add a <code class="Ic">send</code> block (see
142 below) to ensure that the &#x201C;ssh://&#x201D; protocol will
143 be used by <code class="Cm">got send</code>.</p>
144 <p class="Pp">Use of this protocol is discouraged since it supports
145 neither authentication nor encryption.</p>
146 </dd>
147 <dt>https</dt>
148 <dd>The &#x201C;smart&#x201D; Git HTTP protocol wrapped in
149 SSL/TLS.</dd>
150 </dl>
151 </dd>
152 <dt id="port"><a class="permalink" href="#port"><code class="Ic">port</code></a>
153 <var class="Ar">port</var></dt>
154 <dd>Defines the port to use for connecting to the remote repository's
155 server. The <var class="Ar">port</var> can be specified by number or
156 name. The port name to number mappings are found in the file
157 <span class="Pa">/etc/services</span>; see
158 <a class="Xr" aria-label="services, section 5">services(5)</a> for
159 details. If not specified, the default port of the specified
160 <code class="Cm">protocol</code> will be used.</dd>
161 <dt id="branch"><a class="permalink" href="#branch"><code class="Ic">branch</code></a>
162 {<var class="Ar">branch ...</var>}</dt>
163 <dd>Specify one or more branches which <code class="Cm">got fetch</code>
164 and <code class="Cm">got send</code> should fetch from and send to the
165 remote repository by default. The list of branches specified here can
166 be overridden at the <code class="Cm">got fetch</code> and
167 <code class="Cm">got send</code> command lines with the
168 <code class="Fl">-b</code> option.</dd>
169 <dt id="fetch_all_branches"><a class="permalink" href="#fetch_all_branches"><code class="Ic">fetch_all_branches</code></a>
170 <var class="Ar">yes</var> | <var class="Ar">no</var></dt>
171 <dd>This option controls whether <code class="Cm">got fetch</code> will
172 fetch all branches from the remote repository by default. If enabled,
173 this behaviour can be overridden at the <code class="Cm">got
174 fetch</code> command line with the <code class="Fl">-b</code> option,
175 and any <code class="Cm">branch</code> configuration settings for this
176 remote repository will be ignored.</dd>
177 <dt id="reference"><a class="permalink" href="#reference"><code class="Ic">reference</code></a>
178 {<var class="Ar">reference ...</var>}</dt>
179 <dd>Specify one or more arbitrary references which <code class="Cm">got
180 fetch</code> should fetch by default, in addition to the branches and
181 tags that will be fetched. The list of references specified here can
182 be overridden at the <code class="Cm">got fetch</code> command line
183 with the <code class="Fl">-R</code> option. <code class="Cm">got
184 fetch</code> will refuse to fetch references from the remote
185 repository's &#x201C;refs/remotes/&#x201D; or
186 &#x201C;refs/got/&#x201D; namespace. In any case, references in the
187 &#x201C;refs/tags/&#x201D; namespace will always be fetched and mapped
188 directly to local references in the same namespace.</dd>
189 <dt id="mirror_references"><a class="permalink" href="#mirror_references"><code class="Ic">mirror_references</code></a>
190 <var class="Ar">yes</var> | <var class="Ar">no</var></dt>
191 <dd>This option controls the behaviour of <code class="Cm">got
192 fetch</code> when updating references.
193 <a class="permalink" href="#Enabling"><b class="Sy" id="Enabling">Enabling
194 this option can lead to the loss of local commits.</b></a> Maintaining
195 custom changes in a mirror repository is therefore discouraged.
196 <p class="Pp">If this option is not specified or set to
197 <var class="Ar">no</var>, <code class="Cm">got fetch</code> will map
198 references of the remote repository into the local repository's
199 &#x201C;refs/remotes/&#x201D; namespace.</p>
200 <p class="Pp">If this option is set to <var class="Ar">yes</var>, all
201 branches in the &#x201C;refs/heads/&#x201D; namespace will be
202 updated directly to match the corresponding branches in the remote
203 repository.</p>
204 </dd>
205 <dt id="fetch"><a class="permalink" href="#fetch"><code class="Ic">fetch</code></a>
206 {...}</dt>
207 <dd>An optional <code class="Ic">fetch</code> block may contain any of the
208 following configuration settings for use by <code class="Cm">got
209 fetch</code>, overriding corresponding settings in the containing
210 <code class="Ic">remote</code> <var class="Ar">name</var> {...} block.
211 <ul class="Bl-bullet">
212 <li id="server~2"><a class="permalink" href="#server~2"><code class="Ic">server</code></a>
213 <var class="Ar">hostname</var></li>
214 <li id="repository~2"><a class="permalink" href="#repository~2"><code class="Ic">repository</code></a>
215 <var class="Ar">path</var></li>
216 <li id="protocol~2"><a class="permalink" href="#protocol~2"><code class="Ic">protocol</code></a>
217 <var class="Ar">scheme</var></li>
218 <li id="port~2"><a class="permalink" href="#port~2"><code class="Ic">port</code></a>
219 <var class="Ar">port</var></li>
220 <li id="branch~2"><a class="permalink" href="#branch~2"><code class="Ic">branch</code></a>
221 {<var class="Ar">branch ...</var>}</li>
222 </ul>
223 </dd>
224 <dt id="send"><a class="permalink" href="#send"><code class="Ic">send</code></a>
225 {...}</dt>
226 <dd>An optional <code class="Ic">send</code> block may contain any of the
227 following configuration settings for use by <code class="Cm">got
228 send</code>, overriding corresponding settings in the containing
229 <code class="Ic">remote</code> <var class="Ar">name</var> {...} block.
230 <ul class="Bl-bullet">
231 <li id="server~3"><a class="permalink" href="#server~3"><code class="Ic">server</code></a>
232 <var class="Ar">hostname</var></li>
233 <li id="repository~3"><a class="permalink" href="#repository~3"><code class="Ic">repository</code></a>
234 <var class="Ar">path</var></li>
235 <li id="protocol~3"><a class="permalink" href="#protocol~3"><code class="Ic">protocol</code></a>
236 <var class="Ar">scheme</var></li>
237 <li id="port~3"><a class="permalink" href="#port~3"><code class="Ic">port</code></a>
238 <var class="Ar">port</var></li>
239 <li id="branch~3"><a class="permalink" href="#branch~3"><code class="Ic">branch</code></a>
240 {<var class="Ar">branch ...</var>}</li>
241 </ul>
242 </dd>
243 </dl>
244 </dd>
245 </dl>
246 </section>
247 <section class="Sh">
248 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
249 <dl class="Bl-tag Bl-compact">
250 <dt><span class="Pa">got.conf</span></dt>
251 <dd>If present, <code class="Nm">got.conf</code> located in the root directory
252 of a Git repository supersedes any relevant settings in Git's
253 <span class="Pa">config</span> file.
254 <p class="Pp"></p>
255 </dd>
256 <dt><span class="Pa">.got/got.conf</span></dt>
257 <dd>If present, <code class="Nm">got.conf</code> located in the
258 <span class="Pa">.got</span> meta-data directory of a
259 <a class="Xr" aria-label="got, section 1">got(1)</a> work tree supersedes
260 any relevant settings in the repository's <code class="Nm">got.conf</code>
261 configuration file and Git's <span class="Pa">config</span> file.</dd>
262 </dl>
263 </section>
264 <section class="Sh">
265 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
266 <p class="Pp">Configure author information:</p>
267 <div class="Bd Pp Bd-indent Li">
268 <pre>author &quot;Flan Hacker &lt;;&quot;</pre>
269 </div>
270 <p class="Pp">Remote repository specification for the Game of Trees
271 repository:</p>
272 <div class="Bd Pp Bd-indent Li">
273 <pre>remote &quot;origin&quot; {
274 server
275 protocol ssh
276 repository got
277 branch { &quot;main&quot; }
278 }</pre>
279 </div>
280 <p class="Pp">Mirror the <span class="Ux">OpenBSD</span> src repository from
281 Github:</p>
282 <div class="Bd Pp Bd-indent Li">
283 <pre>remote &quot;origin&quot; {
284 repository &quot;openbsd/src&quot;
285 server
286 protocol git+ssh
287 mirror_references yes
288 }</pre>
289 </div>
290 <p class="Pp">Fetch changes via the Git protocol and send changes via the SSH
291 protocol:</p>
292 <div class="Bd Pp Bd-indent Li">
293 <pre>remote &quot;origin&quot; {
294 repository my_repo
295 server
296 protocol git
297 send {
298 server
299 protocol ssh
301 }</pre>
302 </div>
303 </section>
304 <section class="Sh">
305 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
306 ALSO</a></h2>
307 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
308 <a class="Xr" aria-label="git-repository, section 5">git-repository(5)</a>,
309 <a class="Xr" aria-label="got-worktree, section 5">got-worktree(5)</a></p>
310 </section>
311 <section class="Sh">
312 <h2 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h2>
313 <p class="Pp"><code class="Nm">got.conf</code> offers no way to configure the
314 editor spawned by <code class="Cm">got commit</code>, <code class="Cm">got
315 histedit</code>, <code class="Cm">got import</code>, or <code class="Cm">got
316 tag</code>. This is deliberate and prevents potential arbitrary command
317 execution as another user when repositories or work trees are shared between
318 users. Users should set their <code class="Ev">VISUAL</code> or
319 <code class="Ev">EDITOR</code> environment variables instead.</p>
320 </section>
321 </main>
322 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
323 line"><span class="foot-left"></span><span class="foot-date">June 3,
324 2024</span> <span class="foot-os">OpenBSD 7.5</span></div>
325 </body>
326 </html>