Blob


1 <!DOCTYPE html>
2 <html>
3 <!-- This is an automatically generated file. Do not edit.
4 Copyright (c) 2020 Stefan Sperling <stsp@openbsd.org>
6 Permission to use, copy, modify, and distribute this software for any
7 purpose with or without fee is hereby granted, provided that the above
8 copyright notice and this permission notice appear in all copies.
10 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 -->
18 <head>
19 <meta charset="utf-8"/>
20 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
21 <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
22 <title>GOT.CONF(5)</title>
23 </head>
24 <body>
25 <table class="head">
26 <tr>
27 <td class="head-ltitle">GOT.CONF(5)</td>
28 <td class="head-vol">File Formats Manual</td>
29 <td class="head-rtitle">GOT.CONF(5)</td>
30 </tr>
31 </table>
32 <div class="manual-text">
33 <section class="Sh">
34 <h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
35 <p class="Pp"><code class="Nm">got.conf</code> &#x2014; <span class="Nd">Game of
36 Trees configuration file</span></p>
37 </section>
38 <section class="Sh">
39 <h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
40 <p class="Pp"><code class="Nm">got.conf</code> is the run-time configuration
41 file for <a class="Xr">got(1)</a>.</p>
42 <p class="Pp"><code class="Nm">got.conf</code> may be present in the root
43 directory of a Git repository for repository-wide settings, or in the
44 <span class="Pa">.got</span> meta-data directory of a work tree to override
45 repository-wide settings for <a class="Xr">got(1)</a> commands executed
46 within this work tree.</p>
47 <p class="Pp">The file format is line-based, with one configuration directive
48 per line. Any lines beginning with a &#x2018;#&#x2019; are treated as
49 comments and ignored.</p>
50 <p class="Pp">The available configuration directives are as follows:</p>
51 <dl class="Bl-tag">
52 <dt id="author"><a class="permalink" href="#author"><code class="Ic">author</code></a>
53 &#x201C;Real Name &lt;email address&gt;&#x201D;</dt>
54 <dd>Configure the author's name and email address for <code class="Cm">got
55 commit</code> and <code class="Cm">got import</code> when operating on
56 this repository. Author information specified here overrides the
57 <code class="Ev">GOT_AUTHOR</code> environment variable.
58 <p class="Pp">Because <a class="Xr">git(1)</a> may fail to parse commits
59 without an email address in author data, <a class="Xr">got(1)</a>
60 attempts to reject author information with a missing email address.</p>
61 </dd>
62 <dt id="remote"><a class="permalink" href="#remote"><code class="Ic">remote</code></a>
63 <var class="Ar">name</var> {...}</dt>
64 <dd>Define a remote repository. The specified <var class="Ar">name</var> can
65 be used to refer to the remote repository on the command line of
66 <code class="Cm">got fetch</code> and <code class="Cm">got send</code>.
67 <p class="Pp">Information about this repository is declared in a block of
68 options enclosed in curly brackets:</p>
69 <dl class="Bl-tag">
70 <dt id="server"><a class="permalink" href="#server"><code class="Ic">server</code></a>
71 <var class="Ar">hostname</var></dt>
72 <dd>Defines the hostname to use for contacting the remote repository's
73 server.</dd>
74 <dt id="repository"><a class="permalink" href="#repository"><code class="Ic">repository</code></a>
75 <var class="Ar">path</var></dt>
76 <dd>Defines the path to the repository on the remote repository's
77 server.</dd>
78 <dt id="protocol"><a class="permalink" href="#protocol"><code class="Ic">protocol</code></a>
79 <var class="Ar">scheme</var></dt>
80 <dd>Defines the protocol to use for communicating with the remote
81 repository's server.
82 <p class="Pp">The following protocol schemes are supported:</p>
83 <dl class="Bl-tag">
84 <dt>git</dt>
85 <dd>The Git protocol as implemented by the
86 <a class="Xr">git-daemon(1)</a> server. Use of this protocol is
87 discouraged since it supports neither authentication nor
88 encryption.</dd>
89 <dt>git+ssh</dt>
90 <dd>The Git protocol wrapped in an authenticated and encrypted
91 <a class="Xr">ssh(1)</a> tunnel. With this protocol the hostname
92 may contain an embedded username for <a class="Xr">ssh(1)</a> to
93 use:
94 <a class="Mt" href="mailto:user@hostname">user@hostname</a></dd>
95 <dt>ssh</dt>
96 <dd>Short alias for git+ssh.</dd>
97 </dl>
98 </dd>
99 <dt id="port"><a class="permalink" href="#port"><code class="Ic">port</code></a>
100 <var class="Ar">port</var></dt>
101 <dd>Defines the port to use for connecting to the remote repository's
102 server. The <var class="Ar">port</var> can be specified by number or
103 name. The port name to number mappings are found in the file
104 <span class="Pa">/etc/services</span>; see
105 <a class="Xr">services(5)</a> for details. If not specified, the
106 default port of the specified <code class="Cm">protocol</code> will be
107 used.</dd>
108 <dt id="branch"><a class="permalink" href="#branch"><code class="Ic">branch</code></a>
109 {<var class="Ar">branch ...</var>}</dt>
110 <dd>Specify one or more branches which <code class="Cm">got fetch</code>
111 and <code class="Cm">got send</code> should fetch from and send to the
112 remote repository by default. The list of branches specified here can
113 be overridden at the <code class="Cm">got fetch</code> and
114 <code class="Cm">got send</code> command lines with the
115 <code class="Fl">-b</code> option.</dd>
116 <dt id="fetch-all-branches"><a class="permalink" href="#fetch-all-branches"><code class="Ic">fetch-all-branches</code></a>
117 <var class="Ar">yes</var> | <var class="Ar">no</var></dt>
118 <dd>This option controls whether <code class="Cm">got fetch</code> will
119 fetch all branches from the remote repository by default. If enabled,
120 this behaviour can be overridden at the <code class="Cm">got
121 fetch</code> command line with the <code class="Fl">-b</code> option,
122 and any <code class="Cm">branch</code> configuration settings for this
123 remote repository will be ignored.</dd>
124 <dt id="reference"><a class="permalink" href="#reference"><code class="Ic">reference</code></a>
125 {<var class="Ar">reference ...</var>}</dt>
126 <dd>Specify one or more arbitrary references which <code class="Cm">got
127 fetch</code> should fetch by default, in addition to the branches and
128 tags that will be fetched. The list of references specified here can
129 be overridden at the <code class="Cm">got fetch</code> command line
130 with the <code class="Fl">-R</code> option. <code class="Cm">got
131 fetch</code> will refuse to fetch references from the remote
132 repository's &#x201C;refs/remotes/&#x201D; or
133 &#x201C;refs/got/&#x201D; namespace. In any case, references in the
134 &#x201C;refs/tags/&#x201D; namespace will always be fetched and mapped
135 directly to local references in the same namespace.</dd>
136 <dt id="mirror-references"><a class="permalink" href="#mirror-references"><code class="Ic">mirror-references</code></a>
137 <var class="Ar">yes</var> | <var class="Ar">no</var></dt>
138 <dd>This option controls the behaviour of <code class="Cm">got
139 fetch</code> when updating references.
140 <a class="permalink" href="#Enabling"><b class="Sy" id="Enabling">Enabling
141 this option can lead to the loss of local commits.</b></a> Maintaining
142 custom changes in a mirror repository is therefore discouraged.
143 <p class="Pp">If this option is not specified or set to
144 <var class="Ar">no</var>, <code class="Cm">got fetch</code> will map
145 references of the remote repository into the local repository's
146 &#x201C;refs/remotes/&#x201D; namespace.</p>
147 <p class="Pp">If this option is set to <var class="Ar">yes</var>, all
148 branches in the &#x201C;refs/heads/&#x201D; namespace will be
149 updated directly to match the corresponding branches in the remote
150 repository.</p>
151 </dd>
152 <dt id="fetch"><a class="permalink" href="#fetch"><code class="Ic">fetch</code></a>
153 {...}</dt>
154 <dd>An optional <code class="Ic">fetch</code> block may contain any of the
155 following configuration settings for use by <code class="Cm">got
156 fetch</code>, overriding corresponding settings in the containing
157 <code class="Ic">remote</code> <var class="Ar">name</var> {...} block.
158 <ul class="Bl-bullet">
159 <li id="server~2"><a class="permalink" href="#server~2"><code class="Ic">server</code></a>
160 <var class="Ar">hostname</var></li>
161 <li id="repository~2"><a class="permalink" href="#repository~2"><code class="Ic">repository</code></a>
162 <var class="Ar">path</var></li>
163 <li id="protocol~2"><a class="permalink" href="#protocol~2"><code class="Ic">protocol</code></a>
164 <var class="Ar">scheme</var></li>
165 <li id="port~2"><a class="permalink" href="#port~2"><code class="Ic">port</code></a>
166 <var class="Ar">port</var></li>
167 <li id="branch~2"><a class="permalink" href="#branch~2"><code class="Ic">branch</code></a>
168 {<var class="Ar">branch ...</var>}</li>
169 </ul>
170 </dd>
171 <dt id="send"><a class="permalink" href="#send"><code class="Ic">send</code></a>
172 {...}</dt>
173 <dd>An optional <code class="Ic">send</code> block may contain any of the
174 following configuration settings for use by <code class="Cm">got
175 send</code>, overriding corresponding settings in the containing
176 <code class="Ic">remote</code> <var class="Ar">name</var> {...} block.
177 <ul class="Bl-bullet">
178 <li id="server~3"><a class="permalink" href="#server~3"><code class="Ic">server</code></a>
179 <var class="Ar">hostname</var></li>
180 <li id="repository~3"><a class="permalink" href="#repository~3"><code class="Ic">repository</code></a>
181 <var class="Ar">path</var></li>
182 <li id="protocol~3"><a class="permalink" href="#protocol~3"><code class="Ic">protocol</code></a>
183 <var class="Ar">scheme</var></li>
184 <li id="port~3"><a class="permalink" href="#port~3"><code class="Ic">port</code></a>
185 <var class="Ar">port</var></li>
186 <li id="branch~3"><a class="permalink" href="#branch~3"><code class="Ic">branch</code></a>
187 {<var class="Ar">branch ...</var>}</li>
188 </ul>
189 </dd>
190 </dl>
191 </dd>
192 </dl>
193 </section>
194 <section class="Sh">
195 <h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
196 <p class="Pp">Configure author information:</p>
197 <div class="Bd Pp Bd-indent Li">
198 <pre>author &quot;Flan Hacker &lt;flan_hacker@openbsd.org&gt;&quot;</pre>
199 </div>
200 <p class="Pp">Remote repository specification for the Game of Trees
201 repository:</p>
202 <div class="Bd Pp Bd-indent Li">
203 <pre>remote &quot;origin&quot; {
204 server git.gameoftrees.org
205 protocol git
206 repository got
207 branch { &quot;main&quot; }
208 }</pre>
209 </div>
210 <p class="Pp">Mirror the <span class="Ux">OpenBSD</span> src repository from
211 Github:</p>
212 <div class="Bd Pp Bd-indent Li">
213 <pre>remote &quot;origin&quot; {
214 repository &quot;openbsd/src&quot;
215 server git@github.com
216 protocol git+ssh
217 mirror-references yes
218 }</pre>
219 </div>
220 <p class="Pp">Fetch changes via the Git protocol and send changes via the SSH
221 protocol:</p>
222 <div class="Bd Pp Bd-indent Li">
223 <pre>remote &quot;origin&quot; {
224 repository my_repo
225 server git.example.com
226 protocol git
227 send {
228 server git@git.example.com
229 protocol ssh
231 }</pre>
232 </div>
233 </section>
234 <section class="Sh">
235 <h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
236 <dl class="Bl-tag Bl-compact">
237 <dt><span class="Pa">got.conf</span></dt>
238 <dd>If present, <code class="Nm">got.conf</code> located in the root directory
239 of a Git repository supersedes any relevant settings in Git's
240 <span class="Pa">config</span> file.
241 <p class="Pp"></p>
242 </dd>
243 <dt><span class="Pa">.got/got.conf</span></dt>
244 <dd>If present, <code class="Nm">got.conf</code> located in the
245 <span class="Pa">.got</span> meta-data directory of a
246 <a class="Xr">got(1)</a> work tree supersedes any relevant settings in the
247 repository's <code class="Nm">got.conf</code> configuration file and Git's
248 <span class="Pa">config</span> file.</dd>
249 </dl>
250 </section>
251 <section class="Sh">
252 <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
253 ALSO</a></h1>
254 <p class="Pp"><a class="Xr">got(1)</a>, <a class="Xr">git-repository(5)</a>,
255 <a class="Xr">got-worktree(5)</a></p>
256 </section>
257 <section class="Sh">
258 <h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1>
259 <p class="Pp"><code class="Nm">got.conf</code> offers no way to configure the
260 editor spawned by <code class="Cm">got commit</code>, <code class="Cm">got
261 histedit</code>, <code class="Cm">got import</code>, or <code class="Cm">got
262 tag</code>. This is deliberate and prevents potential arbitrary command
263 execution as another user when repositories or work trees are shared between
264 users. Users should set their <code class="Ev">VISUAL</code> or
265 <code class="Ev">EDITOR</code> environment variables instead.</p>
266 </section>
267 </div>
268 <table class="foot">
269 <tr>
270 <td class="foot-date">May 10, 2022</td>
271 <td class="foot-os">OpenBSD 7.1</td>
272 </tr>
273 </table>
274 </body>
275 </html>