git: レンタルサーバーに cgit で構築する Web インターフェイス

cgit とは

kernel.org で利用されている git リポジトリの Web インターフェイスです。

• cgit - A hyperfast web frontend for git repositories written in C.

cgit という名前からも察せられるように、 cgi で動きます。

さくらのレンタルサーバー で試しに cgit をセットアップしたところスムーズにセットアップできたのですが、 設定で少々詰まったところもあり、また日本語どころか英語の情報もあまりなかったので、メモがてら書いていきます。

この記事で書か ない こと

レンタルサーバー上の設定を考慮しているので、以下のようなことは書いてません。

• Apache のインストール方法
• httpd.conf （apache2.conf） の設定方法

また、ssh でのログイン方法なども書いてません。

書くこと

逆に、以下のようなことは書きます。

• Makefile 設定上書き例
• htaccess の例
• cgit の設定方法とよく使われるであろう設定

注意事項

cgit は C 言語で書かれているため、cgi はバイナリで提供されます。

バイナリ実行形式の cgi が禁止されているレンタルサーバーには、インストールしないようご注意ください。

前提

サーバー

• レンタルサーバーに ssh でログインできること。
• 各種コマンドはレンタルサーバー上で実行することを想定しています。

リポジトリへの push

cgit はサーバー上のリポジトリを 一覧・参照するため の Web インターフェイス です。

つまり、 読み取り専用 です。

サーバー上のリポジトリへ git push するためには、ssh など別の手段を使います。
詳しくは下記をご参考ください。

• Git - サーバー用の Git の取得

セットアップ

ssh でレンタルサーバーにログインします。

以下の例では、ドキュメントルートを /home/niceuser/www/example としています。

ソースのダウンロード

この記事の例ではホームディレクトリ直下に local フォルダを作成して各種作業ファイルを展開していきます。

cgit のリポジトリ URL は こちら から取得しました。^{1 2}

$ mkdir -p local/src
$ cd local/src
$ git clone https://git.zx2c4.com/cgit 

以降この記事ではデフォルトのブランチをそのままビルドしていきます。

Makefile 設定のオーバーライド

root 権限不要なフォルダ上にインストールできるように Makefile の設定をオーバーライドします。

Makefile の中を見ると cgit.conf ファイルで上書きできるようです:

#
# Let the user override the above settings.
#
-include cgit.conf

cgit.conf は自分で作成して設定を記述します。

$ cd cgit/
$ vi cgit.conf

• ホームディレクトリが /home/niceuser
• ドキュメントルートが /home/niceuser/www/example

となるように設定を上書きする例が以下です。

CGIT_SCRIPT_PATH = /home/niceuser/www/example
CGIT_CONFIG = /home/niceuser/local/etc/cgitrc
CACHE_ROOT = /home/niceuser/local/var/cache/cgit
prefix = /home/niceuser/local

ディレクトリの作成

CACHE_ROOT に指定したディレクトリパスが存在しないとエラーになるので、ディレクトリを作成しておきます。

$ mkdir -p ~/local/etc ~/local/var/cache/cgit

git ソースの取得

cgit で利用する git のソースを取得するために、make get-git コマンドを実行します。

$ make get-git

ただし、さくらのレンタルサーバーは FreeBSD である関係で、GNU Make の文法で書かれている cgit の Makefile ではエラーになります。

幸い gmake ³ がインストールされているので、こちらを使いましょう。

$ gmake get-git

ビルド・インストール

あとは普通に make（gmake） するだけです。

$ gmake install
# make install

設定値 CGIT_SCRIPT_NAME を cgit.cgi から変えていなければ、 さくらのレンタルサーバーでは、以上でインストールが完了し、特に設定不要で Web にアクセスできるはずです。⁴

レンタルサーバーによっては、.cgi ファイルのために、.htaccess へ以下のような設定が必要になるかも知れません。⁵

Options +ExecCGI
AddHandler cgi-script cgi

設定ファイル

設定値 CGIT_CONFIG に指定していたファイルを作成し、各種設定を行えます。
各種設定値の詳細や記述方法などは、cgit リポジトリ直下のテキストファイル cgitrc.5.txt を参考にしてください。

本記事では基本的な設定のみ触れます。

グローバル設定

全リポジトリに対するグローバルな設定と、個別のリポジトリのための設定があります。

グローバル設定を中心に見ていきます。

readme

readme=:README.md
readme=:readme.md
readme=:readme.txt
readme=:README
readme=:readme
readme=:INSTALL.md
readme=:install.md

cgit ページの「about」タブに表示するファイルのファイル名を指定します。 一番最初にファイル名が一致したファイルが表示されます。

設定値を hoge:README とすると、hoge ブランチ直下の README ファイルが about タブに利用されます。

上記例のようにブランチ（コロンの左側）を省略すると、デフォルトブランチが選択されます。

注意点として、readme 設定は後述する scan-path 設定より上部に書かないとフォーマットに使われません。

enable-http-clone

enable-http-clone=1

http プロトコルによる git clone を可能にします。

clone-url

clone-url=git://example.com/$CGIT_REPO_URL http://$HTTP_HOST$SCRIPT_NAME/$CGIT_REPO_URL

cgit の画面に見せる リポジトリ URL です。スペース区切りで複数指定できます。 ⁶

enable-http-clone を有効化している場合、（htaccess などで URL パスを変更していなければ） http://$HTTP_HOST$SCRIPT_NAME/$CGIT_REPO_URL という設定が、クローン可能な URL に相当します。

source-filter

2023-11-26 追記

シンタックスハイライトのために利用するフィルタスクリプトを指定します：

# Highlight source code with python pygments-based highlighter
source-filter=/var/www/cgit/filters/syntax-highlighting.py

引用元

cgit のリポジトリにはシンタックスハイライトのための python スクリプト が含まれているのでこちらを利用できるのですが、python とそのパッケージの pygments を cgi から利用可能にする必要があります。

レンタルサーバー上では root 権限が当然ないので、venv を利用する構成例を紹介しておきます。

まず適当なフォルダでまず仮想環境を作り、その中で各パッケージをインストールします。

# python-venv ディレクトリを作成して仮想環境を作る
$ python -m venv python-venv
$ cd python-venv
$ source bin/activate # 仮想環境をアクティベーション
# 必要なパッケージをインストール
$ pip install pygments

パッケージの準備ができたら、次のようなラッパー（wrapper）スクリプトを用意します。

#!/bin/sh

###
### filters/syntax-highlighting.py のラッパースクリプト
###

# 先程作成した python-env 内の bin ディレクトリを PATH に追加する
export PATH=<仮想環境のパス>/bin:$PATH

exec <cgit.confで指定したprefix>/lib/cgit/filters/syntax-highlighting.py "$@"

見たままですが、スクリプト内の PATH 環境変数に仮想環境の bin を追加しているだけです。 ⁷

このファイルを例えば syntax-highlighting-wrapper.sh といった名前で保存し、実行権限を付与（chmod +x syntax-highlighting-wrapper.sh）してから、次のように設定すれば、シンタックスハイライトが利くようになるはずです。

source-filter=<ファイルを置いたディレクトリパス>/syntax-highlighting-wrapper.sh

about-filter

2023-11-26 追記

about ページの表示に利用するフィルタースクリプトを設定します。前述の readme 設定で読み込むファイルなどに対して適用されます。

# Format markdown, restructuredtext, manpages, text files, and html files
# through the right converters
about-filter=/var/www/cgit/filters/about-formatting.sh

引用元

こちらも source-filter と同様フォーマッタスクリプトが cgit から提供されています。

source-filter と同様、フォーマッタスクリプトに必要なパッケージを venv 仮想環境にインストールし、ラッパースクリプトを作成すれば利用できるようになります。

# 先程作成した仮想環境変数ディレクトリ
$ cd python-venv
$ source bin/activate # 仮想環境をアクティベーション
# 必要なパッケージをインストール
$ pip install rst2html markdown pygments 

#!/bin/sh

###
### filters/about-formatting.sh のラッパースクリプト
###

# 先程作成した python-env 内の bin ディレクトリを PATH に追加する
export PATH=<仮想環境のパス>/bin:$PATH

exec <cgit.confで指定したprefix>/lib/cgit/filters/about-formatting.sh "$@"

注意点として、about-filter 設定は後述する scan-path 設定より上部に書かないとフォーマットに使われません。

scan-path

scan-path=/home/niceuser/git-data

この設定で /home/niceuser/git-data 内に作成したベアリポジトリは cgit 上にリストされます。

敢えて最後にこの設定を書きましたが、前述の readme 設定などは scan-path 設定の 前に書かないと有効化されません。⁸

リポジトリごとの設定

以下のように個別のリポジトリの設定も記載できます。cgitrc.5.txt ファイル内 EXAMPLE CGITRC FILE セクションから転載します。

repo.url=foo
repo.path=/pub/git/foo.git
repo.desc=the master foo repository
repo.owner=fooman@example.com
repo.readme=info/web/about.html

リポジトリごとの cgitrc ファイル

グローバル設定の scan-path で自動的に読み込まれたリポジトリ内にcgitrc ファイルを配置すると、 そのリポジトリ固有の設定となります。

この場合、前述の個別設定のようなプレフィックス repo. を削除して記載する必要があります。

つまり先程の設定を個別リポジトリの cgitrc に記載する場合は以下のようになります。

url=foo
path=/pub/git/foo.git
desc=the master foo repository
owner=fooman@example.com
readme=info/web/about.html

認証

cgit それ自体に認証機能はないので、Basic 認証なりを設定する⁹ か、 auth-filter ¹⁰ を設定します。auth-filter の詳しい内容は本記事の趣旨を超えてくるので、割愛します。

URL の変更

デフォルトだと http://git.example.com/cgit.cgi/ のように、 cgi ファイル名が URL に含まれます。

htaccess に以下の設定をすることで、URL から cgit.cgi を削除できます。¹¹

RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule (.*) /cgit.cgi/$1

この場合、clone-url に設定すべき URL は http://$HTTP_HOST/$CGIT_REPO_URL になります（$SCRIPT_NAME が不要です）。

一体いつから ― GitHub が スタンダード だと錯覚していた？

タイトルは言いたかっただけです。はい。

リナックスカーネルの開発から git は生まれました。¹²

git のネイティブ機能には Web インターフェース GitWeb が組み込まれ、kernel.org でも利用されていました。

GitWeb はやがてパフォーマンスの面で問題が指摘されるようになり¹³、そして cgit が生まれ^{14 15}、 kernel.org で採用されるに至りました。¹⁶

正統派にこだわる硬派なあなたには、cgit や GitWeb がお似合いかも知れません。

こういうときどうするの？

プルリクエストを受け付ける（プロジェクトの運営）

プロジェクト運営については以下が参考になると思います。

• Git - プロジェクトの運営
• Git - プロジェクトへの貢献

メールはスケール可能なインテグレーション方法

GitHub や GitLab などの ホスティングサービス上でプルリクエストを扱わない 、というだけで 前時代的 と考える方もいるかも知れません。

考え方は人それぞれですが、参考として LWN.net の記事を貼っておきます。

• Why kernel development still uses email [LWN.net] （タイトル訳: なぜカーネルは未だメールを使って開発を行うのか）

この記事では、 言語やインフラ状況などが多様な世界中の開発者が関わる開発では、むしろメールでやりとりする方がスケールでき、実際非常に速いスループットでパッチを取り込んでいる といったことが書かれています。

メンテナの管理

複数人でリポジトリを管理したい（メンテナを追加したい）場合は、Gitolite が利用できそうです。これも kernel.org で採用されています¹⁷ 。

機会があったら試して記事にできたらなと思います。