2 257add31 2020-09-09 stsp .\" Copyright (c) 2020 Stefan Sperling <stsp@openbsd.org>
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.
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.
16 257add31 2020-09-09 stsp .Dd $Mdocdate$
17 257add31 2020-09-09 stsp .Dt GOT.CONF 5
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
24 257add31 2020-09-09 stsp is the run-time configuration file for
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
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
34 50b0790e 2020-09-11 stsp commands executed within this work tree.
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
39 257add31 2020-09-09 stsp are treated as comments and ignored.
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
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.
55 257add31 2020-09-09 stsp may fail to parse commits without an email address in author data,
57 257add31 2020-09-09 stsp attempts to reject author information with a missing email address.
58 257add31 2020-09-09 stsp .It Ic remote Ar name Brq ...
59 257add31 2020-09-09 stsp Define a remote repository.
60 257add31 2020-09-09 stsp The specified
62 257add31 2020-09-09 stsp can be used to refer to the remote repository on the command line of
63 6480c871 2021-08-30 stsp .Cm got fetch
65 6480c871 2021-08-30 stsp .Cm got send .
67 257add31 2020-09-09 stsp Information about this repository is declared in a block of options
68 257add31 2020-09-09 stsp enclosed in curly brackets:
69 257add31 2020-09-09 stsp .Bl -tag -width Ds
70 257add31 2020-09-09 stsp .It Ic server Ar hostname
71 257add31 2020-09-09 stsp Defines the hostname to use for contacting the remote repository's server.
72 257add31 2020-09-09 stsp .It Ic repository Ar path
73 257add31 2020-09-09 stsp Defines the path to the repository on the remote repository's server.
74 257add31 2020-09-09 stsp .It Ic protocol Ar scheme
75 257add31 2020-09-09 stsp Defines the protocol to use for communicating with the remote repository's
78 257add31 2020-09-09 stsp The following protocol schemes are supported:
79 257add31 2020-09-09 stsp .Bl -tag -width git+ssh
81 257add31 2020-09-09 stsp The Git protocol as implemented by the
82 257add31 2020-09-09 stsp .Xr git-daemon 1
84 257add31 2020-09-09 stsp Use of this protocol is discouraged since it supports neither authentication
85 257add31 2020-09-09 stsp nor encryption.
87 257add31 2020-09-09 stsp The Git protocol wrapped in an authenticated and encrypted
90 257add31 2020-09-09 stsp With this protocol the hostname may contain an embedded username for
93 257add31 2020-09-09 stsp .Mt user@hostname
95 257add31 2020-09-09 stsp Short alias for git+ssh.
97 257add31 2020-09-09 stsp .It Ic port Ar port
98 257add31 2020-09-09 stsp Defines the port to use for connecting to the remote repository's server.
101 257add31 2020-09-09 stsp can be specified by number or name.
102 257add31 2020-09-09 stsp The port name to number mappings are found in the file
103 257add31 2020-09-09 stsp .Pa /etc/services ;
105 257add31 2020-09-09 stsp .Xr services 5
106 257add31 2020-09-09 stsp for details.
107 257add31 2020-09-09 stsp If not specified, the default port of the specified
108 257add31 2020-09-09 stsp .Cm protocol
109 257add31 2020-09-09 stsp will be used.
110 b8adfa55 2020-09-25 stsp .It Ic branch Brq Ar branch ...
111 b8adfa55 2020-09-25 stsp Specify one or more branches which
112 b8adfa55 2020-09-25 stsp .Cm got fetch
114 6480c871 2021-08-30 stsp .Cm got send
115 93f8a337 2021-08-30 naddy should fetch from and send to the remote repository by default.
116 b8adfa55 2020-09-25 stsp The list of branches specified here can be overridden at the
117 b8adfa55 2020-09-25 stsp .Cm got fetch
119 6480c871 2021-08-30 stsp .Cm got send
120 6480c871 2021-08-30 stsp command lines with the
123 0c8b29c5 2021-01-05 stsp .It Ic fetch-all-branches Ar yes | no
124 0c8b29c5 2021-01-05 stsp This option controls whether
125 0c8b29c5 2021-01-05 stsp .Cm got fetch
126 0c8b29c5 2021-01-05 stsp will fetch all branches from the remote repository by default.
127 0c8b29c5 2021-01-05 stsp If enabled, this behaviour can be overridden at the
128 0c8b29c5 2021-01-05 stsp .Cm got fetch
129 0c8b29c5 2021-01-05 stsp command line with the
131 0c8b29c5 2021-01-05 stsp option, and any
133 0c8b29c5 2021-01-05 stsp configuration settings for this remote repository will be ignored.
134 99495ddb 2021-01-10 stsp .It Ic reference Brq Ar reference ...
135 99495ddb 2021-01-10 stsp Specify one or more arbitrary references which
136 99495ddb 2021-01-10 stsp .Cm got fetch
137 99495ddb 2021-01-10 stsp should fetch by default, in addition to the branches and tags that will
138 99495ddb 2021-01-10 stsp be fetched.
139 99495ddb 2021-01-10 stsp The list of references specified here can be overridden at the
140 99495ddb 2021-01-10 stsp .Cm got fetch
141 99495ddb 2021-01-10 stsp command line with the
144 99495ddb 2021-01-10 stsp .Cm got fetch
145 99495ddb 2021-01-10 stsp will refuse to fetch references from the remote repository's
146 99495ddb 2021-01-10 stsp .Dq refs/remotes/
148 99495ddb 2021-01-10 stsp .Dq refs/got/
150 99495ddb 2021-01-10 stsp In any case, references in the
151 99495ddb 2021-01-10 stsp .Dq refs/tags/
152 99495ddb 2021-01-10 stsp namespace will always be fetched and mapped directly to local references
153 99495ddb 2021-01-10 stsp in the same namespace.
154 257add31 2020-09-09 stsp .It Ic mirror-references Ar yes | no
155 257add31 2020-09-09 stsp This option controls the behaviour of
156 257add31 2020-09-09 stsp .Cm got fetch
157 257add31 2020-09-09 stsp when updating references.
158 257add31 2020-09-09 stsp .Sy Enabling this option can lead to the loss of local commits.
159 257add31 2020-09-09 stsp Maintaining custom changes in a mirror repository is therefore discouraged.
161 257add31 2020-09-09 stsp If this option is not specified or set to
163 257add31 2020-09-09 stsp .Cm got fetch
164 257add31 2020-09-09 stsp will map references of the remote repository into the local repository's
165 257add31 2020-09-09 stsp .Dq refs/remotes/
168 257add31 2020-09-09 stsp If this option is set to
170 257add31 2020-09-09 stsp all branches in the
171 257add31 2020-09-09 stsp .Dq refs/heads/
172 257add31 2020-09-09 stsp namespace will be updated directly to match the corresponding branches in
173 257add31 2020-09-09 stsp the remote repository.
174 6480c871 2021-08-30 stsp .It Ic fetch Brq ...
175 6480c871 2021-08-30 stsp An optional
177 6480c871 2021-08-30 stsp block may contain any of the following configuration settings
179 6480c871 2021-08-30 stsp .Cm got fetch ,
180 6480c871 2021-08-30 stsp overriding corresponding settings in the containing
181 6480c871 2021-08-30 stsp .Ic remote Ar name Brq ...
183 6480c871 2021-08-30 stsp .Bl -bullet
185 6480c871 2021-08-30 stsp .Ic server Ar hostname
187 6480c871 2021-08-30 stsp .Ic repository Ar path
189 824d5f77 2021-09-12 stsp .Ic protocol Ar scheme
191 6480c871 2021-08-30 stsp .Ic port Ar port
193 6480c871 2021-08-30 stsp .Ic branch Brq Ar branch ...
195 6480c871 2021-08-30 stsp .It Ic send Brq ...
196 6480c871 2021-08-30 stsp An optional
198 6480c871 2021-08-30 stsp block may contain any of the following configuration settings
200 6480c871 2021-08-30 stsp .Cm got send ,
201 6480c871 2021-08-30 stsp overriding corresponding settings in the containing
202 6480c871 2021-08-30 stsp .Ic remote Ar name Brq ...
204 6480c871 2021-08-30 stsp .Bl -bullet
206 6480c871 2021-08-30 stsp .Ic server Ar hostname
208 6480c871 2021-08-30 stsp .Ic repository Ar path
210 824d5f77 2021-09-12 stsp .Ic protocol Ar scheme
212 6480c871 2021-08-30 stsp .Ic port Ar port
214 6480c871 2021-08-30 stsp .Ic branch Brq Ar branch ...
218 257add31 2020-09-09 stsp .Sh EXAMPLES
219 257add31 2020-09-09 stsp Configure author information:
220 257add31 2020-09-09 stsp .Bd -literal -offset indent
221 257add31 2020-09-09 stsp author "Flan Hacker <flan_hacker@openbsd.org>"
224 257add31 2020-09-09 stsp Remote repository specification for the Game of Trees repository:
225 257add31 2020-09-09 stsp .Bd -literal -offset indent
226 257add31 2020-09-09 stsp remote "origin" {
227 257add31 2020-09-09 stsp server git.gameoftrees.org
228 257add31 2020-09-09 stsp protocol git
229 257add31 2020-09-09 stsp repository got
230 b8adfa55 2020-09-25 stsp branch { "main" }
236 1795b260 2021-04-02 kn src repository from Github:
237 257add31 2020-09-09 stsp .Bd -literal -offset indent
238 257add31 2020-09-09 stsp remote "origin" {
239 257add31 2020-09-09 stsp repository "openbsd/src"
240 257add31 2020-09-09 stsp server git@github.com
241 257add31 2020-09-09 stsp protocol git+ssh
242 257add31 2020-09-09 stsp mirror-references yes
246 6480c871 2021-08-30 stsp Fetch changes via the Git protocol and send changes via the SSH protocol:
247 6480c871 2021-08-30 stsp .Bd -literal -offset indent
248 6480c871 2021-08-30 stsp remote "origin" {
249 6480c871 2021-08-30 stsp repository my_repo
250 6480c871 2021-08-30 stsp server git.example.com
251 6480c871 2021-08-30 stsp protocol git
253 6480c871 2021-08-30 stsp server git@git.example.com
254 6480c871 2021-08-30 stsp protocol ssh
259 257add31 2020-09-09 stsp .Bl -tag -width Ds -compact
260 257add31 2020-09-09 stsp .It Pa got.conf
261 50b0790e 2020-09-11 stsp If present,
263 50b0790e 2020-09-11 stsp located in the root directory of a Git repository supersedes any relevant
264 50b0790e 2020-09-11 stsp settings in Git's
268 50b0790e 2020-09-11 stsp .It Pa .got/got.conf
269 50b0790e 2020-09-11 stsp If present,
271 50b0790e 2020-09-11 stsp located in the
273 50b0790e 2020-09-11 stsp meta-data directory of a
275 50b0790e 2020-09-11 stsp work tree supersedes any relevant settings in the repository's
277 50b0790e 2020-09-11 stsp configuration file and Git's
281 257add31 2020-09-09 stsp .Sh SEE ALSO
282 257add31 2020-09-09 stsp .Xr got 1 ,
283 42536c09 2020-09-11 stsp .Xr git-repository 5 ,
284 50b0790e 2020-09-11 stsp .Xr got-worktree 5
285 53643ae1 2020-09-14 stsp .Sh CAVEATS
287 53643ae1 2020-09-14 stsp offers no way to configure the editor spawned by
288 53643ae1 2020-09-14 stsp .Cm got commit ,
289 53643ae1 2020-09-14 stsp .Cm got histedit ,
290 53643ae1 2020-09-14 stsp .Cm got import ,
292 53643ae1 2020-09-14 stsp .Cm got tag .
293 53643ae1 2020-09-14 stsp This is deliberate and prevents potential arbitrary command execution
294 53643ae1 2020-09-14 stsp as another user when repositories or work trees are shared between users.
295 53643ae1 2020-09-14 stsp Users should set their
299 53643ae1 2020-09-14 stsp environment variables instead.
