Enabling `*.go` files in the syntax highlighter.

[gitweb-sgk] / README.md

# Overview #

This is a fork of `gitweb` containing customizations used on
<https://git.subgeniuskitty.com>.

Changes include defaulting to side-by-side diffs, automatically displaying
README files when present, and a new tree+readme page for 'summary' mode.


# Status #

Working. Runs <https://git.subgeniuskitty.com> on Debian Linux.


# Instructions #

The following instructions work on Debian 10. All paths are examples from
the SGK gitweb server located at <https://git.subgeniuskitty.com>. For more
details, including accompanying scripts, see sysadmin notes on
<https://subgeniuskitty.com/notes/mail_web_git_server>.

-----

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 <https://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/apache_vhosts
    git clone /srv/git/gitweb-sgk /srv/apache_vhosts/git.subgeniuskitty.com
    chown -R ataylor:ataylor /srv/apache_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\ngit --git-dir=.git 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