gotweb/gotweb.conf.5

   1 .\"
   2 .\" Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
   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 GOTWEB.CONF 5
  18 .Os
  19 .Sh NAME
  20 .Nm gotweb.conf
  21 .Nd gotweb configuration file
  22 .Sh DESCRIPTION
  23 .Nm
  24 is the run-time configuration file for
  25 .Xr gotweb 8 .
  26 .Pp
  27 The file format is line-based, with one configuration directive per line.
  28 Any lines beginning with a
  29 .Sq #
  30 are treated as comments and ignored.
  31 .Pp
  32 Paths mentioned in
  33 .Nm
  34 must be relative to
  35 .Pa /var/www ,
  36 the
  37 .Xr chroot 2
  38 environment of
  39 .Xr httpd 8 .
  40 .Sh GLOBAL CONFIGURATION
  41 The available configuration directives are as follows:
  42 .Bl -tag -width Ds
  43 .It Ic got_max_commits_display Ar number
  44 Set the maximum amount of commits displayed per page.
  45 .It Ic got_logo Ar path
  46 Set the path to an image file containing a logo to be displayed.
  47 .It Ic got_logo_url Ar url
  48 Set a hyperlink for the logo.
  49 .It Ic got_max_repos Ar number
  50 Set the maximum amount of repositories
  51 .Xr gotweb 8
  52 will work with.
  53 .It Ic got_max_repos_display Ar number
  54 Set the maximum amount of repositories displayed on the index screen.
  55 .It Ic got_show_repo_age Ar on | off
  56 Toggle display of last repository modification date.
  57 .It Ic got_show_repo_cloneurl Ar on | off
  58 Toggle display of clone URLs for a repository.
  59 This requires the creation of a
  60 .Pa cloneurl
  61 file inside the repository which contains one URL per line.
  62 .It Ic got_show_repo_description Ar on | off
  63 Toggle display of the repository description.
  64 The
  65 .Pa description
  66 file in the repository should be updated with an appropriate description.
  67 .It Ic got_repos_path Ar path
  68 Set the path to the directory which contains Git repositories that
  69 .Xr gotweb 8
  70 should publish.
  71 .It Ic got_show_repo_owner Ar on | off
  72 Set whether to display the repository owner.
  73 Displaying the owner requires owner information to be added to the
  74 .Pa config
  75 file in the repository.
  76 .Xr gotweb 8
  77 will parse owner information from either a [gotweb] or a [gitweb] section.
  78 For example:
  79 .Bd -literal -offset indent
  80 [gotweb]
  81 owner = "Your Name"
  82 .Ed
  83 .It Ic got_site_link Ar string
  84 Set the displayed site link name for the index page.
  85 .It Ic got_site_name Ar string
  86 Set the displayed site name title.
  87 .It Ic got_site_owner Ar string
  88 Set the displayed site owner.
  89 .It Ic got_show_site_owner Ar on | off
  90 Toggle display of the site owner.
  91 .It Ic got_www_path Ar string
  92 Set the public gotweb httpd path.
  93 .El
  94 .Sh EXAMPLES
  95 These are the currently configurable items for
  96 .Xr gotweb 8
  97 with their default values.
  98 .Bd -literal -offset indent
  99
 100 #
 101 # gotweb options
 102 # all paths relative to /var/www (httpd chroot jail)
 103 #
 104
 105 got_repos_path                  "/got/public"
 106 got_www_path                    "/gotweb"
 107
 108 #got_max_repos                  100
 109 #got_max_repos_display          25
 110 got_max_commits_display         50
 111
 112 got_site_name                   "my public repos"
 113 got_site_owner                  "Got Owner"
 114 got_site_link                   "repos"
 115
 116 got_logo                        "got.png"
 117 got_logo_url                    "https://gameoftrees.org"
 118
 119 # on by default
 120 #got_show_site_owner            off
 121 #got_show_repo_owner            off
 122 #got_show_repo_age              false
 123 #got_show_repo_description      no
 124 #got_show_repo_cloneurl         off
 125 .Ed
 126 .Sh FILES
 127 .Bl -tag -width Ds -compact
 128 .It Pa /var/www/etc/gotweb.conf
 129 Location of the
 130 .Nm
 131 configuration file.
 132 .El
 133 .Sh SEE ALSO
 134 .Xr got 1 ,
 135 .Xr gotweb 8