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. Any lines beginning with a ‘#’ are treated as
46 comments and ignored.</p>
47 <p class="Pp">The available configuration directives are as follows:</p>
49 <dt id="author"><a class="permalink" href="#author"><code class="Ic">author</code></a>
50 “Real Name <email address>”</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>
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>
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 "allowed signers"
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 "allowed signers" file is documented in the ALLOWED SIGNERS
79 section of <a class="Xr" aria-label="ssh-keygen, section
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>
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 "revoked
88 signers" 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>
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
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
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
121 <p class="Pp">The following protocol schemes are supported:</p>
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>
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>
135 <dd>Short alias for git+ssh.</dd>
138 <dt id="port"><a class="permalink" href="#port"><code class="Ic">port</code></a>
139 <var class="Ar">port</var></dt>
140 <dd>Defines the port to use for connecting to the remote repository's
141 server. The <var class="Ar">port</var> can be specified by number or
142 name. The port name to number mappings are found in the file
143 <span class="Pa">/etc/services</span>; see
144 <a class="Xr" aria-label="services, section 5">services(5)</a> for
145 details. If not specified, the default port of the specified
146 <code class="Cm">protocol</code> will be used.</dd>
147 <dt id="branch"><a class="permalink" href="#branch"><code class="Ic">branch</code></a>
148 {<var class="Ar">branch ...</var>}</dt>
149 <dd>Specify one or more branches which <code class="Cm">got fetch</code>
150 and <code class="Cm">got send</code> should fetch from and send to the
151 remote repository by default. The list of branches specified here can
152 be overridden at the <code class="Cm">got fetch</code> and
153 <code class="Cm">got send</code> command lines with the
154 <code class="Fl">-b</code> option.</dd>
155 <dt id="fetch_all_branches"><a class="permalink" href="#fetch_all_branches"><code class="Ic">fetch_all_branches</code></a>
156 <var class="Ar">yes</var> | <var class="Ar">no</var></dt>
157 <dd>This option controls whether <code class="Cm">got fetch</code> will
158 fetch all branches from the remote repository by default. If enabled,
159 this behaviour can be overridden at the <code class="Cm">got
160 fetch</code> command line with the <code class="Fl">-b</code> option,
161 and any <code class="Cm">branch</code> configuration settings for this
162 remote repository will be ignored.</dd>
163 <dt id="reference"><a class="permalink" href="#reference"><code class="Ic">reference</code></a>
164 {<var class="Ar">reference ...</var>}</dt>
165 <dd>Specify one or more arbitrary references which <code class="Cm">got
166 fetch</code> should fetch by default, in addition to the branches and
167 tags that will be fetched. The list of references specified here can
168 be overridden at the <code class="Cm">got fetch</code> command line
169 with the <code class="Fl">-R</code> option. <code class="Cm">got
170 fetch</code> will refuse to fetch references from the remote
171 repository's “refs/remotes/” or
172 “refs/got/” namespace. In any case, references in the
173 “refs/tags/” namespace will always be fetched and mapped
174 directly to local references in the same namespace.</dd>
175 <dt id="mirror_references"><a class="permalink" href="#mirror_references"><code class="Ic">mirror_references</code></a>
176 <var class="Ar">yes</var> | <var class="Ar">no</var></dt>
177 <dd>This option controls the behaviour of <code class="Cm">got
178 fetch</code> when updating references.
179 <a class="permalink" href="#Enabling"><b class="Sy" id="Enabling">Enabling
180 this option can lead to the loss of local commits.</b></a> Maintaining
181 custom changes in a mirror repository is therefore discouraged.
182 <p class="Pp">If this option is not specified or set to
183 <var class="Ar">no</var>, <code class="Cm">got fetch</code> will map
184 references of the remote repository into the local repository's
185 “refs/remotes/” namespace.</p>
186 <p class="Pp">If this option is set to <var class="Ar">yes</var>, all
187 branches in the “refs/heads/” namespace will be
188 updated directly to match the corresponding branches in the remote
191 <dt id="fetch"><a class="permalink" href="#fetch"><code class="Ic">fetch</code></a>
193 <dd>An optional <code class="Ic">fetch</code> block may contain any of the
194 following configuration settings for use by <code class="Cm">got
195 fetch</code>, overriding corresponding settings in the containing
196 <code class="Ic">remote</code> <var class="Ar">name</var> {...} block.
197 <ul class="Bl-bullet">
198 <li id="server~2"><a class="permalink" href="#server~2"><code class="Ic">server</code></a>
199 <var class="Ar">hostname</var></li>
200 <li id="repository~2"><a class="permalink" href="#repository~2"><code class="Ic">repository</code></a>
201 <var class="Ar">path</var></li>
202 <li id="protocol~2"><a class="permalink" href="#protocol~2"><code class="Ic">protocol</code></a>
203 <var class="Ar">scheme</var></li>
204 <li id="port~2"><a class="permalink" href="#port~2"><code class="Ic">port</code></a>
205 <var class="Ar">port</var></li>
206 <li id="branch~2"><a class="permalink" href="#branch~2"><code class="Ic">branch</code></a>
207 {<var class="Ar">branch ...</var>}</li>
210 <dt id="send"><a class="permalink" href="#send"><code class="Ic">send</code></a>
212 <dd>An optional <code class="Ic">send</code> block may contain any of the
213 following configuration settings for use by <code class="Cm">got
214 send</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~3"><a class="permalink" href="#server~3"><code class="Ic">server</code></a>
218 <var class="Ar">hostname</var></li>
219 <li id="repository~3"><a class="permalink" href="#repository~3"><code class="Ic">repository</code></a>
220 <var class="Ar">path</var></li>
221 <li id="protocol~3"><a class="permalink" href="#protocol~3"><code class="Ic">protocol</code></a>
222 <var class="Ar">scheme</var></li>
223 <li id="port~3"><a class="permalink" href="#port~3"><code class="Ic">port</code></a>
224 <var class="Ar">port</var></li>
225 <li id="branch~3"><a class="permalink" href="#branch~3"><code class="Ic">branch</code></a>
226 {<var class="Ar">branch ...</var>}</li>
234 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
235 <dl class="Bl-tag Bl-compact">
236 <dt><span class="Pa">got.conf</span></dt>
237 <dd>If present, <code class="Nm">got.conf</code> located in the root directory
238 of a Git repository supersedes any relevant settings in Git's
239 <span class="Pa">config</span> file.
242 <dt><span class="Pa">.got/got.conf</span></dt>
243 <dd>If present, <code class="Nm">got.conf</code> located in the
244 <span class="Pa">.got</span> meta-data directory of a
245 <a class="Xr" aria-label="got, section 1">got(1)</a> work tree supersedes
246 any relevant settings in the repository's <code class="Nm">got.conf</code>
247 configuration file and Git's <span class="Pa">config</span> file.</dd>
251 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
252 <p class="Pp">Configure author information:</p>
253 <div class="Bd Pp Bd-indent Li">
254 <pre>author "Flan Hacker <flan_hacker@openbsd.org>"</pre>
256 <p class="Pp">Remote repository specification for the Game of Trees
258 <div class="Bd Pp Bd-indent Li">
259 <pre>remote "origin" {
260 server git.gameoftrees.org
263 branch { "main" }
266 <p class="Pp">Mirror the <span class="Ux">OpenBSD</span> src repository from
268 <div class="Bd Pp Bd-indent Li">
269 <pre>remote "origin" {
270 repository "openbsd/src"
271 server git@github.com
273 mirror_references yes
276 <p class="Pp">Fetch changes via the Git protocol and send changes via the SSH
278 <div class="Bd Pp Bd-indent Li">
279 <pre>remote "origin" {
281 server git.example.com
284 server git@git.example.com
291 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
293 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
294 <a class="Xr" aria-label="git-repository, section 5">git-repository(5)</a>,
295 <a class="Xr" aria-label="got-worktree, section 5">got-worktree(5)</a></p>
298 <h2 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h2>
299 <p class="Pp"><code class="Nm">got.conf</code> offers no way to configure the
300 editor spawned by <code class="Cm">got commit</code>, <code class="Cm">got
301 histedit</code>, <code class="Cm">got import</code>, or <code class="Cm">got
302 tag</code>. This is deliberate and prevents potential arbitrary command
303 execution as another user when repositories or work trees are shared between
304 users. Users should set their <code class="Ev">VISUAL</code> or
305 <code class="Ev">EDITOR</code> environment variables instead.</p>
308 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
309 line"><span class="foot-left"></span><span class="foot-date">March 11,
310 2024</span> <span class="foot-os">OpenBSD 7.5</span></div>
