Blame


1 257add31 2020-09-09 stsp .\"
2 257add31 2020-09-09 stsp .\" Copyright (c) 2020 Stefan Sperling <stsp@openbsd.org>
3 257add31 2020-09-09 stsp .\"
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.
7 257add31 2020-09-09 stsp .\"
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.
15 257add31 2020-09-09 stsp .\"
16 257add31 2020-09-09 stsp .Dd $Mdocdate$
17 257add31 2020-09-09 stsp .Dt GOT.CONF 5
18 257add31 2020-09-09 stsp .Os
19 257add31 2020-09-09 stsp .Sh NAME
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
23 257add31 2020-09-09 stsp .Nm
24 257add31 2020-09-09 stsp is the run-time configuration file for
25 257add31 2020-09-09 stsp .Xr got 1 .
26 257add31 2020-09-09 stsp .Pp
27 50b0790e 2020-09-11 stsp .Nm
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
30 50b0790e 2020-09-11 stsp .Pa .got
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
33 50b0790e 2020-09-11 stsp .Xr got 1
34 50b0790e 2020-09-11 stsp commands executed within this work tree.
35 50b0790e 2020-09-11 stsp .Pp
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
38 257add31 2020-09-09 stsp .Sq #
39 257add31 2020-09-09 stsp are treated as comments and ignored.
40 257add31 2020-09-09 stsp .Pp
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
46 257add31 2020-09-09 stsp and
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.
52 257add31 2020-09-09 stsp .Pp
53 257add31 2020-09-09 stsp Because
54 257add31 2020-09-09 stsp .Xr git 1
55 257add31 2020-09-09 stsp may fail to parse commits without an email address in author data,
56 257add31 2020-09-09 stsp .Xr got 1
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
61 257add31 2020-09-09 stsp .Ar name
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 .
64 257add31 2020-09-09 stsp .Pp
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
74 257add31 2020-09-09 stsp server.
75 257add31 2020-09-09 stsp .Pp
76 257add31 2020-09-09 stsp The following protocol schemes are supported:
77 257add31 2020-09-09 stsp .Bl -tag -width git+ssh
78 257add31 2020-09-09 stsp .It git
79 257add31 2020-09-09 stsp The Git protocol as implemented by the
80 257add31 2020-09-09 stsp .Xr git-daemon 1
81 257add31 2020-09-09 stsp server.
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.
84 257add31 2020-09-09 stsp .It git+ssh
85 257add31 2020-09-09 stsp The Git protocol wrapped in an authenticated and encrypted
86 257add31 2020-09-09 stsp .Xr ssh 1
87 257add31 2020-09-09 stsp tunnel.
88 257add31 2020-09-09 stsp With this protocol the hostname may contain an embedded username for
89 257add31 2020-09-09 stsp .Xr ssh 1
90 257add31 2020-09-09 stsp to use:
91 257add31 2020-09-09 stsp .Mt user@hostname
92 257add31 2020-09-09 stsp .It ssh
93 257add31 2020-09-09 stsp Short alias for git+ssh.
94 257add31 2020-09-09 stsp .El
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.
97 257add31 2020-09-09 stsp The
98 257add31 2020-09-09 stsp .Ar port
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 ;
102 257add31 2020-09-09 stsp see
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
115 b8adfa55 2020-09-25 stsp .Fl b
116 b8adfa55 2020-09-25 stsp option.
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
124 0c8b29c5 2021-01-05 stsp .Fl b
125 0c8b29c5 2021-01-05 stsp option, and any
126 0c8b29c5 2021-01-05 stsp .Cm branch
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
136 99495ddb 2021-01-10 stsp .Fl R
137 99495ddb 2021-01-10 stsp option.
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/
141 99495ddb 2021-01-10 stsp or
142 99495ddb 2021-01-10 stsp .Dq refs/got/
143 99495ddb 2021-01-10 stsp namespace.
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.
154 257add31 2020-09-09 stsp .Pp
155 257add31 2020-09-09 stsp If this option is not specified or set to
156 257add31 2020-09-09 stsp .Ar no ,
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/
160 257add31 2020-09-09 stsp namespace.
161 257add31 2020-09-09 stsp .Pp
162 257add31 2020-09-09 stsp If this option is set to
163 257add31 2020-09-09 stsp .Ar yes ,
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.
168 257add31 2020-09-09 stsp .El
169 1795b260 2021-04-02 kn .El
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>"
174 257add31 2020-09-09 stsp .Ed
175 257add31 2020-09-09 stsp .Pp
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" }
183 257add31 2020-09-09 stsp }
184 257add31 2020-09-09 stsp .Ed
185 257add31 2020-09-09 stsp .Pp
186 1795b260 2021-04-02 kn Mirror the
187 1795b260 2021-04-02 kn .Ox
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
195 257add31 2020-09-09 stsp }
196 257add31 2020-09-09 stsp .Ed
197 257add31 2020-09-09 stsp .Sh FILES
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,
201 257add31 2020-09-09 stsp .Nm
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
204 257add31 2020-09-09 stsp .Pa config
205 257add31 2020-09-09 stsp file.
206 50b0790e 2020-09-11 stsp .Pp
207 50b0790e 2020-09-11 stsp .It Pa .got/got.conf
208 50b0790e 2020-09-11 stsp If present,
209 50b0790e 2020-09-11 stsp .Nm
210 50b0790e 2020-09-11 stsp located in the
211 50b0790e 2020-09-11 stsp .Pa .got
212 50b0790e 2020-09-11 stsp meta-data directory of a
213 50b0790e 2020-09-11 stsp .Xr got 1
214 50b0790e 2020-09-11 stsp work tree supersedes any relevant settings in the repository's
215 50b0790e 2020-09-11 stsp .Nm
216 50b0790e 2020-09-11 stsp configuration file and Git's
217 50b0790e 2020-09-11 stsp .Pa config
218 50b0790e 2020-09-11 stsp file.
219 257add31 2020-09-09 stsp .El
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
225 53643ae1 2020-09-14 stsp .Nm
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 ,
230 53643ae1 2020-09-14 stsp or
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
235 53643ae1 2020-09-14 stsp .Ev VISUAL
236 53643ae1 2020-09-14 stsp or
237 53643ae1 2020-09-14 stsp .Ev EDITOR
238 53643ae1 2020-09-14 stsp environment variables instead.