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