README

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