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 257add31 2020-09-09 stsp .Cm got fetch .
65 257add31 2020-09-09 stsp Information about this repository is declared in a block of options
66 257add31 2020-09-09 stsp enclosed in curly brackets:
67 257add31 2020-09-09 stsp .Bl -tag -width Ds
68 257add31 2020-09-09 stsp .It Ic server Ar hostname
69 257add31 2020-09-09 stsp Defines the hostname to use for contacting the remote repository's server.
70 257add31 2020-09-09 stsp .It Ic repository Ar path
71 257add31 2020-09-09 stsp Defines the path to the repository on the remote repository's server.
72 257add31 2020-09-09 stsp .It Ic protocol Ar scheme
73 257add31 2020-09-09 stsp Defines the protocol to use for communicating with the remote repository's
76 257add31 2020-09-09 stsp The following protocol schemes are supported:
77 257add31 2020-09-09 stsp .Bl -tag -width git+ssh
79 257add31 2020-09-09 stsp The Git protocol as implemented by the
80 257add31 2020-09-09 stsp .Xr git-daemon 1
82 257add31 2020-09-09 stsp Use of this protocol is discouraged since it supports neither authentication
83 257add31 2020-09-09 stsp nor encryption.
85 257add31 2020-09-09 stsp The Git protocol wrapped in an authenticated and encrypted
88 257add31 2020-09-09 stsp With this protocol the hostname may contain an embedded username for
91 257add31 2020-09-09 stsp .Mt user@hostname
93 257add31 2020-09-09 stsp Short alias for git+ssh.
95 257add31 2020-09-09 stsp .It Ic port Ar port
96 257add31 2020-09-09 stsp Defines the port to use for connecting to the remote repository's server.
99 257add31 2020-09-09 stsp can be specified by number or name.
100 257add31 2020-09-09 stsp The port name to number mappings are found in the file
101 257add31 2020-09-09 stsp .Pa /etc/services ;
103 257add31 2020-09-09 stsp .Xr services 5
104 257add31 2020-09-09 stsp for details.
105 257add31 2020-09-09 stsp If not specified, the default port of the specified
106 257add31 2020-09-09 stsp .Cm protocol
107 257add31 2020-09-09 stsp will be used.
108 b8adfa55 2020-09-25 stsp .It Ic branch Brq Ar branch ...
109 b8adfa55 2020-09-25 stsp Specify one or more branches which
110 b8adfa55 2020-09-25 stsp .Cm got fetch
111 b8adfa55 2020-09-25 stsp should fetch from the remote repository by default.
112 b8adfa55 2020-09-25 stsp The list of branches specified here can be overridden at the
113 b8adfa55 2020-09-25 stsp .Cm got fetch
114 b8adfa55 2020-09-25 stsp command line with the
117 0c8b29c5 2021-01-05 stsp .It Ic fetch-all-branches Ar yes | no
118 0c8b29c5 2021-01-05 stsp This option controls whether
119 0c8b29c5 2021-01-05 stsp .Cm got fetch
120 0c8b29c5 2021-01-05 stsp will fetch all branches from the remote repository by default.
121 0c8b29c5 2021-01-05 stsp If enabled, this behaviour can be overridden at the
122 0c8b29c5 2021-01-05 stsp .Cm got fetch
123 0c8b29c5 2021-01-05 stsp command line with the
125 0c8b29c5 2021-01-05 stsp option, and any
127 0c8b29c5 2021-01-05 stsp configuration settings for this remote repository will be ignored.
128 99495ddb 2021-01-10 stsp .It Ic reference Brq Ar reference ...
129 99495ddb 2021-01-10 stsp Specify one or more arbitrary references which
130 99495ddb 2021-01-10 stsp .Cm got fetch
131 99495ddb 2021-01-10 stsp should fetch by default, in addition to the branches and tags that will
132 99495ddb 2021-01-10 stsp be fetched.
133 99495ddb 2021-01-10 stsp The list of references specified here can be overridden at the
134 99495ddb 2021-01-10 stsp .Cm got fetch
135 99495ddb 2021-01-10 stsp command line with the
138 99495ddb 2021-01-10 stsp .Cm got fetch
139 99495ddb 2021-01-10 stsp will refuse to fetch references from the remote repository's
140 99495ddb 2021-01-10 stsp .Dq refs/remotes/
142 99495ddb 2021-01-10 stsp .Dq refs/got/
144 99495ddb 2021-01-10 stsp In any case, references in the
145 99495ddb 2021-01-10 stsp .Dq refs/tags/
146 99495ddb 2021-01-10 stsp namespace will always be fetched and mapped directly to local references
147 99495ddb 2021-01-10 stsp in the same namespace.
148 257add31 2020-09-09 stsp .It Ic mirror-references Ar yes | no
149 257add31 2020-09-09 stsp This option controls the behaviour of
150 257add31 2020-09-09 stsp .Cm got fetch
151 257add31 2020-09-09 stsp when updating references.
152 257add31 2020-09-09 stsp .Sy Enabling this option can lead to the loss of local commits.
153 257add31 2020-09-09 stsp Maintaining custom changes in a mirror repository is therefore discouraged.
155 257add31 2020-09-09 stsp If this option is not specified or set to
157 257add31 2020-09-09 stsp .Cm got fetch
158 257add31 2020-09-09 stsp will map references of the remote repository into the local repository's
159 257add31 2020-09-09 stsp .Dq refs/remotes/
162 257add31 2020-09-09 stsp If this option is set to
164 257add31 2020-09-09 stsp all branches in the
165 257add31 2020-09-09 stsp .Dq refs/heads/
166 257add31 2020-09-09 stsp namespace will be updated directly to match the corresponding branches in
167 257add31 2020-09-09 stsp the remote repository.
170 257add31 2020-09-09 stsp .Sh EXAMPLES
171 257add31 2020-09-09 stsp Configure author information:
172 257add31 2020-09-09 stsp .Bd -literal -offset indent
173 257add31 2020-09-09 stsp author "Flan Hacker <flan_hacker@openbsd.org>"
176 257add31 2020-09-09 stsp Remote repository specification for the Game of Trees repository:
177 257add31 2020-09-09 stsp .Bd -literal -offset indent
178 257add31 2020-09-09 stsp remote "origin" {
179 257add31 2020-09-09 stsp server git.gameoftrees.org
180 257add31 2020-09-09 stsp protocol git
181 257add31 2020-09-09 stsp repository got
182 b8adfa55 2020-09-25 stsp branch { "main" }
188 1795b260 2021-04-02 kn src repository from Github:
189 257add31 2020-09-09 stsp .Bd -literal -offset indent
190 257add31 2020-09-09 stsp remote "origin" {
191 257add31 2020-09-09 stsp repository "openbsd/src"
192 257add31 2020-09-09 stsp server git@github.com
193 257add31 2020-09-09 stsp protocol git+ssh
194 257add31 2020-09-09 stsp mirror-references yes
198 257add31 2020-09-09 stsp .Bl -tag -width Ds -compact
199 257add31 2020-09-09 stsp .It Pa got.conf
200 50b0790e 2020-09-11 stsp If present,
202 50b0790e 2020-09-11 stsp located in the root directory of a Git repository supersedes any relevant
203 50b0790e 2020-09-11 stsp settings in Git's
207 50b0790e 2020-09-11 stsp .It Pa .got/got.conf
208 50b0790e 2020-09-11 stsp If present,
210 50b0790e 2020-09-11 stsp located in the
212 50b0790e 2020-09-11 stsp meta-data directory of a
214 50b0790e 2020-09-11 stsp work tree supersedes any relevant settings in the repository's
216 50b0790e 2020-09-11 stsp configuration file and Git's
220 257add31 2020-09-09 stsp .Sh SEE ALSO
221 257add31 2020-09-09 stsp .Xr got 1 ,
222 42536c09 2020-09-11 stsp .Xr git-repository 5 ,
223 50b0790e 2020-09-11 stsp .Xr got-worktree 5
224 53643ae1 2020-09-14 stsp .Sh CAVEATS
226 53643ae1 2020-09-14 stsp offers no way to configure the editor spawned by
227 53643ae1 2020-09-14 stsp .Cm got commit ,
228 53643ae1 2020-09-14 stsp .Cm got histedit ,
229 53643ae1 2020-09-14 stsp .Cm got import ,
231 53643ae1 2020-09-14 stsp .Cm got tag .
232 53643ae1 2020-09-14 stsp This is deliberate and prevents potential arbitrary command execution
233 53643ae1 2020-09-14 stsp as another user when repositories or work trees are shared between users.
234 53643ae1 2020-09-14 stsp Users should set their
238 53643ae1 2020-09-14 stsp environment variables instead.
