-# Test #
+# Overview #
+
+This is a fork of `gitweb` containing customizations used on
+<http://git.subgeniuskitty.com>.
+
+Changes include things like using side-by-side diffs by default and
+automatically displaying README files if present while browsing in tree mode.
+
+# Status #
+
+Working. Tested on <http://git.subgeniuskitty.com>.
+
+# Instructions #
+
+The following instructions work on Debian 10. All paths are examples from
+the SGK gitweb server located at <http://git.subgeniuskitty.com>. For more
+details, including accompanying scripts, see sysadmin notes on
+<http://subgeniuskitty.com>.
+
+-----
+
+Verify prequisites are installed. Syntax highlighting is provided by
+`highlight` and markdown-to-HTML processing is provided by `discount`.
+
+ apt-get install gitweb highlight discount
+
+Create a Gitweb configuration file at `/etc/gitweb.conf`. For example,
+<http://git.subgeniuskitty.com> uses the following configuration file.
+
+ $site_name = "git.subgeniuskitty.com";
+ @git_base_url_list = ("git://git.subgeniuskitty.com");
+ $projectroot = "/srv/gitweb_cache";
+ $git_temp = "/tmp";
+
+ @stylesheets = ("static/gitweb.css");
+ $javascript = "static/gitweb.js";
+ $logo = "static/sgk-logo.png";
+ $favicon = "static/git-favicon.png";
+
+ # git-diff-tree(1) options to use for generated patches
+ @diff_opts = ();
+
+ # Enable PATH_INFO so the server can produce URLs of the
+ # form: http://git.hokietux.net/project.git/xxx/xxx
+ # This allows for pretty URLs *within* the Git repository,
+ # also needs the Apache rewrite rules for full effect.
+ $feature{'pathinfo'}{'default'} = [1];
+
+ # HTML text to include as home page header.
+ $home_text = "indextext.html";
+
+ # Add a toolbar option with the 'git clone url'.
+ $feature{'actions'}{'default'} = [('clone url', 'git://git.subgeniuskitty.com/%n', 'summary')];
+
+ # Category name is read from .git/category, in the same manner as .git/description.
+ $projects_list_group_categories = 1;
+ $project_list_default_category = "misc";
+
+ # Needed for displaying README files.
+ $prevent_xss = 0;
+
+ ################################################################################
+
+ # Enable blame, pickaxe search, snapshop, search, and grep
+ # support, but still allow individual projects to turn them off.
+ # These are features that users can use to interact with your Git trees. They
+ # consume some CPU whenever a user uses them, so you can turn them off if you
+ # need to. Note that the 'override' option means that you can override the
+ # setting on a per-repository basis.
+ $feature{'blame'}{'default'} = [1];
+ $feature{'blame'}{'override'} = [1];
+
+ $feature{'pickaxe'}{'default'} = [1];
+ $feature{'pickaxe'}{'override'} = [1];
+
+ $feature{'snapshot'}{'default'} = [1];
+ $feature{'snapshot'}{'override'} = [1];
+
+ $feature{'search'}{'default'} = [1];
+
+ $feature{'grep'}{'default'} = [1];
+ $feature{'grep'}{'override'} = [1];
+
+ $feature{'highlight'}{'default'} = [1];
+
+Create an Apache vhost definition among the Apache2 configuration files. For
+the Debian 10 server that runs <http://git.subgeniuskitty.com>, this means
+creating the file `/etc/apache2/sites-available/git.subgeniuskitty.com/conf`
+with the following contents.
+
+ <VirtualHost *:80>
+ ServerName git.subgeniuskitty.com
+ ServerAdmin webmaster@subgeniuskitty.com
+
+ DocumentRoot "/srv/apache_vhosts/git.subgeniuskitty.com"
+
+ ErrorLog /var/log/apache2/error_log.git.subgeniuskitty.com
+ CustomLog /var/log/apache2/access_log.git.subgeniuskitty.com combined
+
+ <Directory "/srv/apache_vhosts/git.subgeniuskitty.com">
+ Options +FollowSymLinks +ExecCGI
+ AllowOverride None
+ Require all granted
+ AddHandler cgi-script .cgi
+ DirectoryIndex gitweb.cgi
+ RewriteEngine On
+ RewriteCond %{REQUEST_FILENAME} !-f
+ RewriteCond %{REQUEST_FILENAME} !-d
+ RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
+ </Directory>
+ </VirtualHost>
+
+Clone a copy of the gitweb repository into the vhost's webroot. Ensure it is
+owned by an SSH-enabled user for management, and that permissions are suitable
+for reading by the Apache2 user, usually `www-data` on Debian.
+
+ mkdir -p /srv/apache2_vhosts
+ git clone /srv/git/gitweb-sgk /srv/apache2_vhosts/git.subgeniuskitty.com
+ chown -R ataylor:ataylor /srv/apache2_vhosts/git.subgeniuskitty.com
+
+In order to maintain a public/private split, gitweb only displays repos that
+have been cloned into `/srv/gitweb_cache`. Remember to set `.git/description`
+and `.git/category` for any repos cloned into this gitweb cache folder.
+
+ mkdir -p /srv/gitweb_cache
+ git clone /srv/git/repo_name /srv/gitweb_cache/repo_name
+ echo "A description goes here." > /srv/gitweb_cache/repo_name/.git/description
+ echo "Category" > /srv/gitweb_cache/repo_name/.git/category
+ printf '#!/usr/bin/bash\ncd /srv/gitweb_cache/repo_name/.git\ngit pull\n' > /srv/git/repo_name/hooks/post-update
+ chmod +x /srv/git/repo_name/hooks/post-update
+
+Turn everything on.
+
+ a2enmod cgi
+ a2enmod rewrite
+ a2ensite git.subgeniuskitty.com
+ systemctl reload apache2
-Test