lib/Gitalist.pm

   1 package Gitalist;
   2 use Moose;
   3 BEGIN { require 5.008006; }
   4 use Catalyst::Runtime 5.80;
   5 use namespace::autoclean;
   6
   7 extends 'Catalyst';
   8
   9 use Catalyst qw/
  10                 ConfigLoader
  11                 Unicode::Encoding
  12                 Static::Simple
  13                 StackTrace
  14                 SubRequest
  15 /;
  16
  17 our $VERSION = '0.002009';
  18 $VERSION = eval $VERSION;
  19
  20 __PACKAGE__->config(
  21     name => 'Gitalist',
  22     default_view => 'Default',
  23     default_model => 'CollectionOfRepos',
  24     use_request_uri_for_path => 1,
  25     disable_component_resolution_regex_fallback => 1,
  26 );
  27
  28 __PACKAGE__->setup();
  29
  30 after prepare_path => sub {
  31     my ($ctx) = @_;
  32     if ($ctx->req->param('a')) {
  33         $ctx->request->uri->path('/legacy' . $ctx->request->uri->path);
  34     }
  35 };
  36
  37 around uri_for => sub {
  38   my ($orig, $c) = (shift, shift);
  39   my $uri = $c->$orig(@_);
  40   $$uri =~ tr[&][;] if defined $uri;
  41   return $uri;
  42 };
  43
  44 around uri_for_action => sub {
  45   my ($orig, $c) = (shift, shift);
  46   my $uri = $c->$orig(@_);
  47   $$uri =~ s[/fragment\b][] if defined $uri;
  48   return $uri;
  49 };
  50
  51 sub uri_with {
  52   my ($self, @args) = @_;
  53   my $uri = $self->request->uri_with(@args);
  54   # Wow this awful.
  55   $uri =~ s[/fragment\b][];
  56   return $uri;
  57 }
  58
  59 1;
  60
  61 __END__
  62
  63 =encoding UTF-8
  64
  65 =head1 NAME
  66
  67 Gitalist - A modern git web viewer
  68
  69 =head1 SYNOPSIS
  70
  71     perl script/gitalist_server.pl --repo_dir /home/me/code/git
  72
  73 =head1 INSTALL
  74
  75 As Gitalist follows the usual Perl module format the usual approach
  76 for installation should work, e.g.:
  77
  78     perl Makefile.PL
  79     make
  80     make test
  81     make install
  82
  83 or
  84
  85     cpan -i Gitalist
  86
  87 You can also L<check Gitalist out from its git repository|/"GETTING GITALIST">
  88 and run it, in this case you'll additionally need the author modules,
  89 but no configuration will be needed as it will default to looking
  90 for repositories the directory above the checkout.
  91
  92 =head1 DESCRIPTION
  93
  94 Gitalist is a web frontend for git repositories based on
  95 L<gitweb.cgi|https://git.wiki.kernel.org/index.php/Gitweb> and backed by
  96 L<Catalyst>.
  97
  98 =head2 History
  99
 100 This project started off as an attempt to port I<gitweb.cgi> to a
 101 Catalyst app in a piecemeal fashion. As it turns out, thanks largely
 102 to Florian Ragwitz's earlier effort, it was easier to use I<gitweb.cgi>
 103 as a template for building a new Catalyst application.
 104
 105 =head1 GETTING GITALIST
 106
 107 You can install Gitalist from CPAN in the usual way:
 108
 109     cpan -i Gitalist
 110
 111 Alternatively, you can get Gitalist using git.
 112
 113 The canonical repository for the master branch is:
 114
 115     git://git.shadowcat.co.uk/catagits/Gitalist.git
 116
 117 Gitalist is also mirrored to GitHub at L<https://github.com/broquaint/Gitalist>,
 118 and a number of people have active forks
 119 with branches and/or new features in the master branch.
 120
 121 =head1 BOOTSTRAPPING
 122
 123 As of C<0.002001> Gitalist can now be bootstrapped to run out of its
 124 own directory by installing its prerequisites locally with the help of
 125 L<local::lib>. So instead of installing the prerequisites to the
 126 system path with CPAN they are installed under the Gitalist directory.
 127
 128 To do this clone Gitalist from the L<Shadowcat repository mentioned
 129 above|/"GETTING GITALIST"> or grab a snapshot from broquaint's GitHub repository:
 130
 131     https://github.com/broquaint/Gitalist/downloads
 132
 133 With the source acquired and unpacked run the following from within the
 134 Gitalist directory:
 135
 136     perl script/bootstrap.pl
 137
 138 This will install the necessary modules for the build process which in
 139 turn installs the prerequisites locally.
 140
 141 B<NB:> The relevant bootstrap scripts aren't available in the CPAN dist
 142 as the bootstrap scripts should not be installed.
 143
 144 =head1 INITIAL CONFIGURATION
 145
 146 Gitalist is configured using L<Catalyst::Plugin::Configloader>. The supplied sample
 147 configuration is in L<Config::General> format, however it is possible to configure
 148 Gitalist using other config file formats (such as YAML) if you prefer.
 149
 150 =head2 WHEN CHECKING GITALIST OUT OF GIT
 151
 152 Gitalist from git includes a minimal C<gitalist_local.conf>, which sets the repository
 153 directory to one directory higher than the Gitalist repository.
 154
 155 This means that if you check Gitalist out next to your other git checkouts, then starting
 156 the demo server needs no parameters at all:
 157
 158     Gitalist [master]$ perl script/gitalist_server.pl
 159     You can connect to your server at http://localhost:3000
 160
 161 =head2 FOR CPAN INSTALLS
 162
 163 Gitalist can be supplied with a config file by setting the C<< GITALIST_CONFIG >>
 164 environment variable to point to a configuration file.
 165
 166 If you install Gitalist from CPAN, a default configuration is installed along with gitalist,
 167 which is complete except for a repository directory. You can get a copy of this configuration
 168 by running:
 169
 170   cp `perl -Ilib -MGitalist -e'print Gitalist->path_to("gitalist.conf")'` gitalist.conf
 171
 172 You can then edit this configuration, adding a C<repo_dir> path and customising
 173 other settings as desired.
 174
 175 You can then start the Gitalist demo server by setting C<< GITALIST_CONFIG >>. For example:
 176
 177     GITALIST_CONFIG=/usr/local/etc/gitalist.conf gitalist_server.pl
 178
 179 Alternatively, if you only want to set a repository directory and are otherwise happy with
 180 the default configuration, then you can set the C<< GITALIST_REPO_DIR >> environment
 181 variable, or pass the C<< --repo_dir >> flag to any of the scripts.
 182
 183     GITALIST_REPO_DIR=/home/myuser/code/git gitalist_server.pl
 184     gitalist_server.pl --repo_dir home/myuser/code/git
 185
 186 The C<< GITALIST_REPO_DIR >> environment variable will override the repository directory set
 187 in configuration, and will itself be overridden by he C<< --repo_dir >> flag.
 188
 189 =head1 RUNNING
 190
 191 Once you have followed the instructions above to install and configure Gitalist, you may want
 192 to run it in a more production facing environment than using the single threaded developement
 193 server.
 194
 195 The recommended deployment method for Gitalist is FastCGI, although Gitalist can also be run
 196 under L<mod_perl|https://perl.apache.org/> or as pure Perl with L<Catalyst::Engine::PreFork>.
 197
 198 Assuming that you have installed Gitalist's dependencies into a L<local::lib>, and you
 199 are running from a git checkout, adding a trivial FCGI script as C<script/gitalist.fcgi>
 200 (this file is specifically in C<.gitignore> so you can have your own copy):
 201
 202     #!/bin/sh
 203     exec /home/t0m/public_html/Gitalist/script/gitalist_fastcgi.pl
 204
 205 This example can be seen live here:
 206
 207     http://example.gitalist.com
 208
 209 =head1 CONFIGURATION
 210
 211 The Gitalist config is loaded with L<Catalyst::Plugin::ConfigLoader>
 212 and the available config options are:
 213
 214 =head2 Model::CollectionOfRepos
 215
 216 =over
 217
 218 =item git
 219
 220 Path to the C<git> binary.
 221
 222 =item repo_dir
 223
 224 A directory containing the directories to show.
 225
 226 If no repositories are found in this directory then Gitalist will
 227 search recursively in that directory for repositories.
 228
 229 =item search_recursively
 230
 231 A boolean indicating whether to always search recursively for
 232 repositories within C<repo_dir>.
 233
 234 =item whitelist
 235
 236 Path a file containing a list of repositories that can be shown. Each
 237 line in the file will represent the name of a repo to show e.g
 238
 239   Gitalist
 240   some-bare-repo.git
 241
 242 This is compatible with C<gitweb>'s C<projects.list>.
 243
 244 =item export_ok
 245
 246 If provided every must contain a file of the same name to be
 247 visible. This is similar to C<gitweb>'s functionality.
 248
 249 =back
 250
 251 =head2 paging
 252
 253 =over
 254
 255 =item log
 256
 257 The number of commits to show in the
 258
 259 =back
 260
 261 =head2 FASTCGI
 262
 263 Running Gitalist in FastCGI mode requires a webserver with FastCGI
 264 support (such as apache with L<mod_fcgi|http://www.fastcgi.com/drupal/node/3>
 265 or L<mod_fcgid|https://httpd.apache.org/mod_fcgid/>). Below is a sample
 266 configuration using Apache2 with mod_fcgid in a dynamic configuration
 267 (as opposed to static or standalone mode). More information on these modes and
 268 their configuration can be found at L<Catalyst::Engine::FastCGI/"Standalone server mode">.
 269
 270 In Apache's F<mime.conf>, add C<AddHandler fcgid-script .fcgi>
 271 (or C<AddHandler fastcgi-script .fcgi> for mod_fcgi).
 272
 273 And a quick VirtualHost configuration:
 274
 275     <VirtualHost *:80>
 276         ServerName gitalist.yourdomain.com
 277         DocumentRoot /path/to/gitalist.fcgi
 278         <Directory "/path/to/gitalist.fcgi">
 279             AllowOverride all
 280             Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
 281             Order allow,deny
 282             Allow from all
 283         </Directory>
 284
 285         # Tell Apache this is a FastCGI application
 286         <Files gitalist.fcgi>
 287             #change the below to fastcgi-script if using mod_fcgi
 288             SetHandler fcgid-script
 289         </Files>
 290     </VirtualHost>
 291
 292 Now to access your Gitalist instance, you'll go to
 293 C<gitalist.yourdomain.com/gitalist.fcgi/> (B<do not forget that trailing> C</>).
 294 If you'd like a different URL, of course, you'll likely want to use
 295 L<mod_rewrite|https://httpd.apache.org/docs/mod/mod_rewrite.html> or equivalent.
 296
 297 If you find the need to do some troubleshooting, you can call
 298 C<http://url_to_gitalist.fcgi?dump_info=1> and/or add export C<GITALIST_DEBUG=1>
 299 to the top of your F<gitalist.fcgi> file (just below the shebang line).
 300
 301 Also, note that Apache will refuse C<%2F> in Gitalist URLs
 302 unless configured otherwise. Make sure C<AllowEncodedSlashes On>
 303 is in your F<httpd.conf> file in order for this to run smoothly.
 304
 305 =head1 CONTRIBUTING
 306
 307 Patches are welcome, please feel free to fork on github and send pull requests, send patches
 308 from git format-patch to the bug tracker, or host your own copy of gitalist somewhere and
 309 ask us to pull from it.
 310
 311 =head1 SUPPORT
 312
 313 Gitalist has an active irc community in C<#gitalist> on irc.perl.org, please feel free to stop
 314 by and ask questions, report bugs or installation issues or generally for a chat about where
 315 we plan to go with the project.
 316
 317 =head1 SEE ALSO
 318
 319 L<Gitalist::Controller::Root>
 320
 321 L<Gitalist::Git::Repository>
 322
 323 L<Catalyst>
 324
 325 =head1 AUTHORS AND COPYRIGHT
 326
 327   Catalyst application:
 328     © 2009 Venda Ltd and Dan Brook <broq@cpan.org>
 329     © 2009, Tom Doran <bobtfish@bobtfish.net>
 330     © 2009, Zac Stevens <zts@cryptocracy.com>
 331
 332   Original gitweb.cgi from which this was derived:
 333     © 2005-2006, Kay Sievers <kay.sievers@vrfy.org>
 334     © 2005, Christian Gierke
 335
 336   Model based on http://github.com/rafl/gitweb
 337     © 2008, Florian Ragwitz
 338
 339 =head1 LICENSE
 340
 341 Licensed under GNU GPL v2