README

   1 NAME
   2     Gitalist - A modern git web viewer
   3
   4 SYNOPSIS
   5         script/gitalist_server.pl --repo_dir /home/me/code/git
   6
   7 INSTALL
   8     As Gitalist follows the usual Perl module format the usual approach for
   9     installation should work e.g.
  10
  11       perl Makefile.PL
  12       make
  13       make test
  14       make install
  15
  16     or
  17
  18       cpan -i Gitalist
  19
  20     You can also check gitalist out from git and run it, in this case you'll
  21     additionally need the author modules, but no configuration will be
  22     needed as it will default to looking for repositories the directory
  23     above the checkout.
  24
  25 DESCRIPTION
  26     Gitalist is a web frontend for git repositories based on gitweb.cgi and
  27     backed by Catalyst.
  28
  29   History
  30     This project started off as an attempt to port gitweb.cgi to a Catalyst
  31     app in a piecemeal fashion. As it turns out, thanks largely to Florian
  32     Ragwitz's earlier effort, it was easier to use gitweb.cgi as a template
  33     for building a new Catalyst application.
  34
  35 GETTING GITALIST
  36     You can install Gitalist from CPAN in the usual way:
  37
  38         cpan -i Gitalist
  39
  40     Alternatively, you can get Gitalist using git.
  41
  42     The canonical repository for the master branch is:
  43
  44         git://git.shadowcat.co.uk/catagits/Gitalist.git
  45
  46     Gitalist is also mirrored to github, and a number of people have active
  47     forks with branches and/or new features in the master branch.
  48
  49 BOOTSTRAPPING
  50     As of 0.002001 Gitalist can now be bootstrapped to run out of its own
  51     directory by installing its prerequisites locally with the help of
  52     local::lib. So instead of installing the prerequisites to the system
  53     path with CPAN they are installed under the Gitalist directory.
  54
  55     To do this clone Gitalist from the Shadowcat repository mentioned above
  56     or grab a snapshot from broquaint's github repository:
  57
  58         http://github.com/broquaint/Gitalist/downloads
  59
  60     With the source acquired and unpacked run the following from within the
  61     Gitalist directory:
  62
  63         perl script/bootstrap.pl
  64
  65     This will install the necessary modules for the build process which in
  66     turn installs the prerequisites locally.
  67
  68     *NB* The relevant bootstrap scripts aren't available in the CPAN dist as
  69     the bootstrap scripts should not be installed.
  70
  71 INITIAL CONFIGURATION
  72     Gitalist is configured using Catalyst::Plugin::Configloader. The
  73     supplied sample configuration is in Config::General format, however it
  74     is possible to configure Gitalist using other config file formats (such
  75     as YAML) if you prefer.
  76
  77   WHEN CHECKING GITALIST OUT OF GIT
  78     Gitalist from git includes a minimal "gitalist_local.conf", which sets
  79     the repository directory to one directory higher than the Gitalist
  80     repository.
  81
  82     This means that if you check Gitalist out next to your other git
  83     checkouts, then starting the demo server needs no parameters at all:
  84
  85         Gitalist [master]$ ./script/gitalist_server.pl
  86         You can connect to your server at http://localhost:3000
  87
  88   FOR CPAN INSTALLS
  89     Gitalist can be supplied with a config file by setting the
  90     "GITALIST_CONFIG" environment variable to point to a configuration file.
  91
  92     If you install Gitalist from CPAN, a default configuration is installed
  93     along with gitalist, which is complete except for a repository
  94     directory. You can get a copy of this configuration by running:
  95
  96       cp `perl -Ilib -MGitalist -e'print Gitalist->path_to("gitalist.conf")'` gitalist.conf
  97
  98     You can then edit this confg, adding a repo_dir path and customising
  99     other settings as desired.
 100
 101     You can then start the Gitalist demo server by setting
 102     "GITALIST_CONFIG". For example:
 103
 104         GITALIST_CONFIG=/usr/local/etc/gitalist.conf gitalist_server.pl
 105
 106     Alternatively, if you only want to set a repository directory and are
 107     otherwise happy with the default configuration, then you can set the
 108     "GITALIST_REPO_DIR" environment variable, or pass the "--repo_dir" flag
 109     to any of the scripts.
 110
 111         GITALIST_REPO_DIR=/home/myuser/code/git gitalist_server.pl
 112         gitalist_server.pl --repo_dir home/myuser/code/git
 113
 114     The "GITALIST_REPO_DIR" environment variable will override the
 115     repository directory set in configuration, and will itself be overridden
 116     by he "--repo_dir" flag.
 117
 118 RUNNING
 119     Once you have followed the instructions above to install and configure
 120     Gitalist, you may want to run it in a more production facing environment
 121     than using the single threaded developement server.
 122
 123     The recommended deployment method for Gitalist is FastCGI, although
 124     Gitalist can also be run under mod_perl or as pure perl with
 125     Catalyst::Engine::PreFork.
 126
 127     Assuming that you have installed Gitalist's dependencies into a
 128     local::lib, and you are running from a git checkout, adding a trivial
 129     FCGI script as "script/gitalist.fcgi" (this file is specifically in
 130     ".gitignore" so you can have your own copy):
 131
 132         #!/bin/sh
 133         exec /home/t0m/public_html/Gitalist/script/gitalist_fastcgi.pl
 134
 135     This example can be seen live here:
 136
 137         http://example.gitalist.com
 138
 139   FASTCGI
 140         Running Gitalist in FastCGI mode requires a webserver with FastCGI
 141         support (such as apache with mod_fcgi or fcgid). Below is a sample
 142         configuration using Apache2 with fcgid in a dynamic configuration
 143         (as opposed to static or standalone mode). More information on these modes and
 144         their configuration can be found at
 145         http://search.cpan.org/~bobtfish/Catalyst-Runtime-5.80025/lib/Catalyst/Engine/FastCGI.pm#Standalone_server_mode
 146             In Apache's mime.conf, add AddHandler fcgid-script .fcgi (or AddHandler fastcgi-script .fcgi for mod_fcgi)
 147
 148             And a quick VirtualHost configuration:
 149
 150             <VirtualHost *:80>
 151               ServerName gitalist.yourdomain.com
 152               DocumentRoot /path/to/gitalist.fcgi
 153               <Directory "/path/to/gitalist.fcgi">
 154                 AllowOverride all
 155                 Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
 156                 Order allow,deny
 157                 Allow from all
 158               </Directory>
 159
 160             # Tell Apache this is a FastCGI application
 161             <Files gitalist.fcgi>
 162                 #change the below to fastcgi-script if using mod_fcgi
 163                 SetHandler fcgid-script
 164             </Files>
 165           </VirtualHost>
 166
 167             Now to access your gitalist instance, you'll go to gitalist.yourdomain.com/gitalist.fcgi/
 168             (DO NOT FORGET THAT TRAILING /). If you'd like a different URL, of course, you'll likely want to use
 169             mod_rewrite or equivalent
 170
 171             If you find the need to do some troubleshooting, you can call http://url_to_gitalist.fcgi?dump_info=1
 172             and/or add export GITALIST_DEBUG=1 to the top of you gitalist.fcgi file (just below the shebang line).
 173
 174             Also, note that  Apache will refuse %2F in Gitalist URL's unless configured otherwise. Make sure
 175             "AllowEncodedSlashes On" is in your httpd.conf file in order for this to run smoothly.
 176
 177 CONTRIBUTING
 178     Patches are welcome, please feel free to fork on github and send pull
 179     requests, send patches from git format-patch to the bug tracker, or host
 180     your own copy of gitalist somewhere and ask us to pull from it.
 181
 182 SUPPORT
 183     Gitalist has an active irc community in "#gitalist" on irc.perl.org,
 184     please feel free to stop by and ask questions, report bugs or
 185     installation issues or generally for a chat about where we plan to go
 186     with the project.
 187
 188 SEE ALSO
 189     Gitalist::Controller::Root
 190
 191     Gitalist::Git::Repository
 192
 193     Catalyst
 194
 195 AUTHORS AND COPYRIGHT
 196       Catalyst application:
 197         (C) 2009 Venda Ltd and Dan Brook <broq@cpan.org>
 198         (C) 2009, Tom Doran <bobtfish@bobtfish.net>
 199         (C) 2009, Zac Stevens <zts@cryptocracy.com>
 200
 201       Original gitweb.cgi from which this was derived:
 202         (C) 2005-2006, Kay Sievers <kay.sievers@vrfy.org>
 203         (C) 2005, Christian Gierke
 204
 205       Model based on http://github.com/rafl/gitweb
 206         (C) 2008, Florian Ragwitz
 207
 208 LICENSE
 209     Licensed under GNU GPL v2
 210