.\"
.\" Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt GOTWEB.CONF 5
.Os
.Sh NAME
.Nm gotweb.conf
.Nd gotweb configuration file
.Sh DESCRIPTION
.Nm
is the run-time configuration file for
.Xr gotweb 8 .
.Pp
The file format is line-based, with one configuration directive per line.
Any lines beginning with a
.Sq #
are treated as comments and ignored.
.Pp
Paths mentioned in
.Nm
must be relative to
.Pa /var/www ,
the
.Xr chroot 2
environment of
.Xr httpd 8 .
.Sh GLOBAL CONFIGURATION
The available configuration directives are as follows:
.Bl -tag -width Ds
.It Ic got_max_commits_display Ar number
Set the maximum amount of commits displayed per page.
.It Ic got_logo Ar path
Set the path to an image file containing a logo to be displayed.
.It Ic got_logo_url Ar url
Set a hyperlink for the logo.
.It Ic got_max_repos Ar number
Set the maximum amount of repositories
.Xr gotweb 8
will work with.
.It Ic got_max_repos_display Ar number
Set the maximum amount of repositories displayed on the index screen.
.It Ic got_show_repo_age Ar on | off
Toggle display of last repository modification date.
.It Ic got_show_repo_cloneurl Ar on | off
Toggle display of clone URLs for a repository.
This requires the creation of a
.Pa cloneurl
file inside the repository which contains one URL per line.
.It Ic got_show_repo_description Ar on | off
Toggle display of the repository description.
The
.Pa description
file in the repository should be updated with an appropriate description.
.It Ic got_repos_path Ar path
Set the path to the directory which contains Git repositories that
.Xr gotweb 8
should publish.
.It Ic got_show_repo_owner Ar on | off
Set whether to display the repository owner.
Displaying the owner requires owner information to be added to the
.Pa config
file in the repository.
.Xr gotweb 8
will parse owner information from either a [gotweb] or a [gitweb] section.
For example:
.Bd -literal -offset indent
[gotweb]
owner = "Your Name"
.Ed
.It Ic got_site_link Ar string
Set the displayed site link name for the index page.
.It Ic got_site_name Ar string
Set the displayed site name title.
.It Ic got_site_owner Ar string
Set the displayed site owner.
.It Ic got_show_site_owner Ar on | off
Toggle display of the site owner.
.It Ic got_www_path Ar string
Set the public gotweb httpd path.
.El
.Sh EXAMPLES
These are the currently configurable items for
.Xr gotweb 8
with their default values.
.Bd -literal -offset indent

#
# gotweb options
# all paths relative to /var/www (httpd chroot jail)
#

got_repos_path			"/got/public"
got_www_path			"/gotweb"

#got_max_repos			100
#got_max_repos_display		25
got_max_commits_display		50

got_site_name			"my public repos"
got_site_owner			"Got Owner"
got_site_link			"repos"

got_logo			"got.png"
got_logo_url			"https://gameoftrees.org"

# on by default
#got_show_site_owner		off
#got_show_repo_owner		off
#got_show_repo_age		false
#got_show_repo_description	no
#got_show_repo_cloneurl		off
.Ed
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /var/www/etc/gotweb.conf
Location of the
.Nm
configuration file.
.El
.Sh SEE ALSO
.Xr got 1 ,
.Xr gotweb 8