lib/Gitalist.pm

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