Gitweb and Gitosis: Play Nice

A while back I started using gitosis and found what I call ‘the scientist’ tutorial very good for setting up gitosis on its own. If you have not read it (and setup gitosis that way) then the rest of this little guide will require a little more effort to make work. Please make sure that you have read that first so that the rest makes sense.

Installing Gitweb

Now that you have properly installed gitosis then you can install gitweb:

sudo apt-get install gitweb

For the sake of this tutorial I will be referring to the following version:

$ aptitude show gitweb Package: gitweb State: installed Automatically installed: no Version: 1:1.7.0-1 $

Making the Directory for Gitweb

Firstly you have to make sure that it is referred to correctly with apache. My ‘DocumentRoot’ is set to ‘/var/www/’ and therefore to place git in the correct location I ran the command:

cd /var/www/
sudo ln -s /usr/share/gitweb/ git

That made a link in my websites directory to the gitweb install. If you ‘cd’ into the ‘git’ directory then you will see a ‘index.cgi’ file in that directory and it is the file that actually runs all of gitweb. It is just one big Perl script and it does everything. Kinda neat and klunky at the same time. The other thing that you should notice is that we are making symlinks so you will want to make sure that your Apache config has FollowSymLinks. I would suggest running the following command:

grep export_auth_hook index.cgi

And if you get no output then you have a version of gitweb that does not support what I am about to do. You should upgrade to a later version of gitweb. I am warning you now because this caused a few hours of problems on a server running Hardy Herron.

Configuring Apache

Now you have to setup Apache so that it can put people inside the git folder when they want to go there. When we are done you will be able to access gitweb by adding ‘/git/’ to the end of your usual url.

Important: At this point I am assuming that you know how to setup apache to get a simple website and config happening. If you do not then it is time to take a quick detour and learn. Try this LAMP guide on How to Forge.

The section that I added to my site was:

    Options Indexes FollowSymLinks MultiViews ExecCGI
    AddHandler cgi-script cgi
    AllowOverride All
    Order allow,deny
    Allow from all

Most of those options are important and I would recommend that you understand what they do and why they are needed by reading through the Apache documentation for each. This is just one example of how to setup your apache config so that you can use gitweb. Infact the first time that I installed gitweb I had the luxury to give it it’s own subdomain; as in ‘’. You can configure it however you like and can use the config above as advice. The really relevant part however is where we give it its own /git/ directory extension, and the part where we set the Options. Make sure that you understand those two by reading the documentation (google it) before going on.

And don’t forget the basics, do a reload before going on:

sudo /etc/init.d/apache2 reload

Setting the /etc/gitweb.conf

I’m sure that there are good and bad ways to make the gitweb.conf work and I don’t know what they are, so I just made it work by opening the ‘/etc/getweb.conf’ file and placing this in it:

# All you need to do is edit the following two lines to point to the right place.
$projectroot = '/path/to/the/repositories';
$gitosis_conf = '/path/to/the/repositories/gitosis-admin.git/gitosis.conf';
$username = $cgi->remote_user;
$export_auth_hook = sub {
  my $projectdir = shift;
  if($projectdir =~ (/(.*?)\.git/)) {
    my $projectname = basename($1);
    open FILE, $gitosis_conf or die 'Could not open gitosis config file. Please make sure that $gitosis_conf is set properly';
    my $found_repo = 0;
    while() {
      if($_ =~ /^\[repo/) {
        if($_ =~ /^\[repo\ $projectname/) { $found_repo = 1; }
        elsif ($found_repo) { $found_repo = 0; }
      if ($found_repo) {
        if($_ =~ /^gitweb\ = yes\ *$/) { return 1; }
        if($_ =~ /^gitweb\ = no\ *$/) { return 0; }
  return 0;

Basically this script uses the export_auth_hook function to decide whether or not to show the required directories. That means that the www-data user will need to be able to get access to those repositories. In order for a repository to show from your gitosis.conf file, the config section must look something like this:

[repo fuppes]
gitweb = yes
description = Free UPnP Entertainment Service
owner = Robert Massaioli

[repo fuppes-website]
gitweb = yes
description = The FUPPES Website
owner = Robert Massaioli

Very important: As you can see, if a repository is missing, or does not have, a ‘gitweb = (yes/no)’ section then it will be discarded and not shown.

Which is an example of a part of the file containing the currently visible repositories.

Reaping the Rewards

With all of that done you should now be able to view the results by browsing to

And that is now all that there is to it. However, as a last word of warning, if you get errors then it is probably the fact that you have not given www-data the ability to read the required files in repositories/. You need to make sure that it has read access if it is to run successfully.

Leave comments and tell me what you think. I will improve this post based on peoples comments.

P.S. I should note that I was led in the right direction by this post.

2 thoughts on “Gitweb and Gitosis: Play Nice

  1. unfortunately gtiweb 1.7.2 breaks this config, they know it, but will probably have to wait for 1.7.3 for a fix since I can’t figure out how to revert to the 1.7.1 version

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s