got/got.conf.5

   1 .\"
   2 .\" Copyright (c) 2020 Stefan Sperling <stsp@openbsd.org>
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .Dd $Mdocdate$
  17 .Dt GOT.CONF 5
  18 .Os
  19 .Sh NAME
  20 .Nm got.conf
  21 .Nd Game of Trees configuration file
  22 .Sh DESCRIPTION
  23 .Nm
  24 is the run-time configuration file for
  25 .Xr got 1 .
  26 .Pp
  27 .Nm
  28 may be present in the root directory of a Git repository for
  29 repository-wide settings, or in the
  30 .Pa .got
  31 meta-data directory of a work tree to override repository-wide
  32 settings for
  33 .Xr got 1
  34 commands executed within this work tree.
  35 .Pp
  36 The file format is line-based, with one configuration directive per line.
  37 Comments can be put anywhere in the file using a hash mark
  38 .Pq Sq # ,
  39 and extend to the end of the current line.
  40 Arguments names not beginning with a letter, digit or underscore,
  41 as well as reserved words
  42 .Pq such as Ic author , Ic remote No or Ic port ,
  43 must be quoted.
  44 Arguments containing whitespace should be surrounded by double quotes
  45 .Pq \&" .
  46 .Pp
  47 The available configuration directives are as follows:
  48 .Bl -tag -width Ds
  49 .It Ic author Dq Real Name <email address>
  50 Configure the author's name and email address for
  51 .Cm got commit
  52 and
  53 .Cm got import
  54 when operating on this repository.
  55 Author information specified here overrides the
  56 .Ev GOT_AUTHOR
  57 environment variable.
  58 .Pp
  59 Because
  60 .Xr git 1
  61 may fail to parse commits without an email address in author data,
  62 .Xr got 1
  63 attempts to reject author information with a missing email address.
  64 .It Ic signer_id Pa signer-id
  65 Configure a
  66 .Ar signer-id
  67 to sign tag objects.
  68 This key will be used to sign all tag objects unless overridden by
  69 .Cm got tag Fl s Ar signer-id .
  70 .Pp
  71 For SSH-based signatures,
  72 .Ar signer-id
  73 is the path to a file which may refer to either a private SSH key,
  74 or a public SSH key with the private half available via
  75 .Xr ssh-agent 1 .
  76 .It Ic allowed_signers Pa path
  77 Configure a
  78 .Ar path
  79 to the "allowed signers" file which contains a list of trusted
  80 SSH signer identities.
  81 The file will be passed to
  82 .Xr ssh-keygen 1
  83 during verification of SSH-based signatures with
  84 .Cm got tag Fl V .
  85 The format of the "allowed signers" file is documented in the
  86 ALLOWED SIGNERS section of
  87 .Xr ssh-keygen 1 .
  88 .Pp
  89 Verification of SSH-based signatures is impossible unless the
  90 .Ic allowed_signers
  91 option is set in
  92 .Nm .
  93 .It Ic revoked_signers Pa path
  94 Configure a
  95 .Ar path
  96 to the optional "revoked signers" file, which contains a list of revoked
  97 SSH signer identities.
  98 This file is passed to
  99 .Xr ssh-keygen 1
 100 during signature verification with
 101 .Cm got tag Fl V .
 102 Revoked identities are no longer considered trustworthy and verification
 103 of relevant signatures will fail.
 104 .It Ic remote Ar name Brq ...
 105 Define a remote repository.
 106 The specified
 107 .Ar name
 108 can be used to refer to the remote repository on the command line of
 109 .Cm got fetch
 110 and
 111 .Cm got send .
 112 .Pp
 113 When repositories are shared between multiple users on the system, it is
 114 recommended that users configure their trusted remote repositories in each
 115 of their work-trees'
 116 .Nm
 117 files, overriding corresponding repository-wide settings.
 118 This can avoid potentially undesirable connections to remote repositories
 119 placed into the shared repository's
 120 .Nm
 121 file by other users.
 122 .Pp
 123 Information about a repository is declared in a block of options
 124 enclosed in curly brackets:
 125 .Bl -tag -width Ds
 126 .It Ic server Ar hostname
 127 Defines the hostname to use for contacting the remote repository's server.
 128 .It Ic repository Ar path
 129 Defines the path to the repository on the remote repository's server.
 130 .It Ic protocol Ar scheme
 131 Defines the protocol to use for communicating with the remote repository's
 132 server.
 133 .Pp
 134 The following protocol schemes are supported:
 135 .Bl -tag -width https
 136 .It git
 137 The Git protocol as implemented by the
 138 .Xr git-daemon 1
 139 server.
 140 Use of this protocol is discouraged since it supports neither authentication
 141 nor encryption.
 142 .It ssh
 143 The Git protocol wrapped in an authenticated and encrypted
 144 .Xr ssh 1
 145 tunnel.
 146 With this protocol the hostname may contain an embedded username for
 147 .Xr ssh 1
 148 to use:
 149 .Mt user@hostname
 150 .It http
 151 The
 152 .Dq smart
 153 Git HTTP protocol.
 154 Not compatible with servers using the
 155 .Dq dumb
 156 Git HTTP protocol.
 157 .Pp
 158 The
 159 .Dq smart
 160 Git HTTP protocol is supported by
 161 .Cm got clone
 162 and
 163 .Cm got fetch ,
 164 but not by
 165 .Cm got send .
 166 To send from a repository cloned over HTTP, add a
 167 .Ic send
 168 block (see below) to ensure that the
 169 .Dq ssh://
 170 protocol will be used by
 171 .Cm got send .
 172 .Pp
 173 Use of this protocol is discouraged since it supports neither authentication
 174 nor encryption.
 175 .It https
 176 The
 177 .Dq smart
 178 Git HTTP protocol wrapped in SSL/TLS.
 179 .El
 180 .It Ic port Ar port
 181 Defines the port to use for connecting to the remote repository's server.
 182 The
 183 .Ar port
 184 can be specified by number or name.
 185 The port name to number mappings are found in the file
 186 .Pa /etc/services ;
 187 see
 188 .Xr services 5
 189 for details.
 190 If not specified, the default port of the specified
 191 .Cm protocol
 192 will be used.
 193 .It Ic branch Brq Ar branch ...
 194 Specify one or more branches which
 195 .Cm got fetch
 196 and
 197 .Cm got send
 198 should fetch from and send to the remote repository by default.
 199 The list of branches specified here can be overridden at the
 200 .Cm got fetch
 201 and
 202 .Cm got send
 203 command lines with the
 204 .Fl b
 205 option.
 206 .It Ic fetch_all_branches Ar yes | no
 207 This option controls whether
 208 .Cm got fetch
 209 will fetch all branches from the remote repository by default.
 210 If enabled, this behaviour can be overridden at the
 211 .Cm got fetch
 212 command line with the
 213 .Fl b
 214 option, and any
 215 .Cm branch
 216 configuration settings for this remote repository will be ignored.
 217 .It Ic reference Brq Ar reference ...
 218 Specify one or more arbitrary references which
 219 .Cm got fetch
 220 should fetch by default, in addition to the branches and tags that will
 221 be fetched.
 222 The list of references specified here can be overridden at the
 223 .Cm got fetch
 224 command line with the
 225 .Fl R
 226 option.
 227 .Cm got fetch
 228 will refuse to fetch references from the remote repository's
 229 .Dq refs/remotes/
 230 or
 231 .Dq refs/got/
 232 namespace.
 233 In any case, references in the
 234 .Dq refs/tags/
 235 namespace will always be fetched and mapped directly to local references
 236 in the same namespace.
 237 .It Ic mirror_references Ar yes | no
 238 This option controls the behaviour of
 239 .Cm got fetch
 240 when updating references.
 241 .Sy Enabling this option can lead to the loss of local commits.
 242 Maintaining custom changes in a mirror repository is therefore discouraged.
 243 .Pp
 244 If this option is not specified or set to
 245 .Ar no ,
 246 .Cm got fetch
 247 will map references of the remote repository into the local repository's
 248 .Dq refs/remotes/
 249 namespace.
 250 .Pp
 251 If this option is set to
 252 .Ar yes ,
 253 all branches in the
 254 .Dq refs/heads/
 255 namespace will be updated directly to match the corresponding branches in
 256 the remote repository.
 257 .It Ic fetch Brq ...
 258 An optional
 259 .Ic fetch
 260 block may contain any of the following configuration settings
 261 for use by
 262 .Cm got fetch ,
 263 overriding corresponding settings in the containing
 264 .Ic remote Ar name Brq ...
 265 block.
 266 .Bl -bullet
 267 .It
 268 .Ic server Ar hostname
 269 .It
 270 .Ic repository Ar path
 271 .It
 272 .Ic protocol Ar scheme
 273 .It
 274 .Ic port Ar port
 275 .It
 276 .Ic branch Brq Ar branch ...
 277 .El
 278 .It Ic send Brq ...
 279 An optional
 280 .Ic send
 281 block may contain any of the following configuration settings
 282 for use by
 283 .Cm got send ,
 284 overriding corresponding settings in the containing
 285 .Ic remote Ar name Brq ...
 286 block.
 287 .Bl -bullet
 288 .It
 289 .Ic server Ar hostname
 290 .It
 291 .Ic repository Ar path
 292 .It
 293 .Ic protocol Ar scheme
 294 .It
 295 .Ic port Ar port
 296 .It
 297 .Ic branch Brq Ar branch ...
 298 .El
 299 .El
 300 .El
 301 .Sh FILES
 302 .Bl -tag -width Ds -compact
 303 .It Pa got.conf
 304 If present,
 305 .Nm
 306 located in the root directory of a Git repository supersedes any relevant
 307 settings in Git's
 308 .Pa config
 309 file.
 310 .Pp
 311 .It Pa .got/got.conf
 312 If present,
 313 .Nm
 314 located in the
 315 .Pa .got
 316 meta-data directory of a
 317 .Xr got 1
 318 work tree supersedes any relevant settings in the repository's
 319 .Nm
 320 configuration file and Git's
 321 .Pa config
 322 file.
 323 .El
 324 .Sh EXAMPLES
 325 Configure author information:
 326 .Bd -literal -offset indent
 327 author "Flan Hacker <flan_hacker@openbsd.org>"
 328 .Ed
 329 .Pp
 330 Remote repository specification for the Game of Trees repository:
 331 .Bd -literal -offset indent
 332 remote "origin" {
 333         server anonymous@got.gameoftrees.org
 334         protocol ssh
 335         repository got
 336         branch { "main" }
 337 }
 338 .Ed
 339 .Pp
 340 Mirror the
 341 .Ox
 342 src repository from Github:
 343 .Bd -literal -offset indent
 344 remote "origin" {
 345         repository "openbsd/src"
 346         server git@github.com
 347         protocol git+ssh
 348         mirror_references yes
 349 }
 350 .Ed
 351 .Pp
 352 Fetch changes via the Git protocol and send changes via the SSH protocol:
 353 .Bd -literal -offset indent
 354 remote "origin" {
 355         repository my_repo
 356         server git.example.com
 357         protocol git
 358         send {
 359                 server git@git.example.com
 360                 protocol ssh
 361         }
 362 }
 363 .Ed
 364 .Sh SEE ALSO
 365 .Xr got 1 ,
 366 .Xr git-repository 5 ,
 367 .Xr got-worktree 5
 368 .Sh CAVEATS
 369 .Nm
 370 offers no way to configure the editor spawned by
 371 .Cm got commit ,
 372 .Cm got histedit ,
 373 .Cm got import ,
 374 or
 375 .Cm got tag .
 376 This is deliberate and prevents potential arbitrary command execution
 377 as another user when repositories or work trees are shared between users.
 378 Users should set their
 379 .Ev VISUAL
 380 or
 381 .Ev EDITOR
 382 environment variables instead.