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 257add31 2020-09-09 stsp .It Ic mirror-references Ar yes | no
129 257add31 2020-09-09 stsp This option controls the behaviour of
130 257add31 2020-09-09 stsp .Cm got fetch
131 257add31 2020-09-09 stsp when updating references.
132 257add31 2020-09-09 stsp .Sy Enabling this option can lead to the loss of local commits.
133 257add31 2020-09-09 stsp Maintaining custom changes in a mirror repository is therefore discouraged.
135 257add31 2020-09-09 stsp If this option is not specified or set to
137 257add31 2020-09-09 stsp .Cm got fetch
138 257add31 2020-09-09 stsp will map references of the remote repository into the local repository's
139 257add31 2020-09-09 stsp .Dq refs/remotes/
142 257add31 2020-09-09 stsp If this option is set to
144 257add31 2020-09-09 stsp all branches in the
145 257add31 2020-09-09 stsp .Dq refs/heads/
146 257add31 2020-09-09 stsp namespace will be updated directly to match the corresponding branches in
147 257add31 2020-09-09 stsp the remote repository.
149 257add31 2020-09-09 stsp .Sh EXAMPLES
150 257add31 2020-09-09 stsp Configure author information:
151 257add31 2020-09-09 stsp .Bd -literal -offset indent
152 257add31 2020-09-09 stsp author "Flan Hacker <flan_hacker@openbsd.org>"
155 257add31 2020-09-09 stsp Remote repository specification for the Game of Trees repository:
156 257add31 2020-09-09 stsp .Bd -literal -offset indent
157 257add31 2020-09-09 stsp remote "origin" {
158 257add31 2020-09-09 stsp server git.gameoftrees.org
159 257add31 2020-09-09 stsp protocol git
160 257add31 2020-09-09 stsp repository got
161 b8adfa55 2020-09-25 stsp branch { "main" }
165 257add31 2020-09-09 stsp Mirror the OpenBSD src repository from Github:
166 257add31 2020-09-09 stsp .Bd -literal -offset indent
167 257add31 2020-09-09 stsp remote "origin" {
168 257add31 2020-09-09 stsp repository "openbsd/src"
169 257add31 2020-09-09 stsp server git@github.com
170 257add31 2020-09-09 stsp protocol git+ssh
171 257add31 2020-09-09 stsp mirror-references yes
175 257add31 2020-09-09 stsp .Bl -tag -width Ds -compact
176 257add31 2020-09-09 stsp .It Pa got.conf
177 50b0790e 2020-09-11 stsp If present,
179 50b0790e 2020-09-11 stsp located in the root directory of a Git repository supersedes any relevant
180 50b0790e 2020-09-11 stsp settings in Git's
184 50b0790e 2020-09-11 stsp .It Pa .got/got.conf
185 50b0790e 2020-09-11 stsp If present,
187 50b0790e 2020-09-11 stsp located in the
189 50b0790e 2020-09-11 stsp meta-data directory of a
191 50b0790e 2020-09-11 stsp work tree supersedes any relevant settings in the repository's
193 50b0790e 2020-09-11 stsp configuration file and Git's
197 257add31 2020-09-09 stsp .Sh SEE ALSO
198 257add31 2020-09-09 stsp .Xr got 1 ,
199 42536c09 2020-09-11 stsp .Xr git-repository 5 ,
200 50b0790e 2020-09-11 stsp .Xr got-worktree 5
201 53643ae1 2020-09-14 stsp .Sh CAVEATS
203 53643ae1 2020-09-14 stsp offers no way to configure the editor spawned by
204 53643ae1 2020-09-14 stsp .Cm got commit ,
205 53643ae1 2020-09-14 stsp .Cm got histedit ,
206 53643ae1 2020-09-14 stsp .Cm got import ,
208 53643ae1 2020-09-14 stsp .Cm got tag .
209 53643ae1 2020-09-14 stsp This is deliberate and prevents potential arbitrary command execution
210 53643ae1 2020-09-14 stsp as another user when repositories or work trees are shared between users.
211 53643ae1 2020-09-14 stsp Users should set their
215 53643ae1 2020-09-14 stsp environment variables instead.
