lib/Gitalist.pm

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