README

   1 Gitweb plugin for YOURLS
   2 ========================
   3 <http://octo.it/yourls-gitweb/>
   4
   5 This plugin can be used to automatically redirect to a Gitweb installation, if
   6 the provided keywors is not found in the database.
   7
   8 For example, imagine a user opening this URL:
   9
  10   http://sho.rt/a06c1a52
  11
  12 And further imagine that “a06c1a52” is not a short URL stored in the database.
  13 This plugin will intercept the “redirect_keyword_not_found” action and check if
  14 the keyword is a hexadecimal number with at least six (hexadecimal) digits.
  15
  16 If so, the plugin will iterate over all Git repositories in a base directory
  17 and check if there's an object in one of them which matches the given id. If
  18 such an object is found, the user will be redirected to the appropriate Gitweb
  19 page. Otherwise, YOURLS will proceed as usual.
  20
  21 Installation
  22 ------------
  23 First, you need at least YOURLS, version 1.5. Versions before that do not
  24 provide a plugin infrastructure.
  25
  26  * Copy the plugin to “$yourls_dir/user/plugins/”.
  27  * Open the administrative interface in the web-browser of your choice.
  28  * Open the “Plugins” page and search for the “Gitweb” plugin in the table.
  29  * Click “Activate” in the rightmost “Action” column.
  30  * A new bulletin “Gitweb” should appear below the link to the “Plugins” page.
  31  * Go to the “Gitweb” page.
  32  * Insert the base directory and the Gitweb URL. The base directory should be
  33    the same directory you specified using “$projectroot” in your Gitweb
  34    configuration. You can pass any valid Gitweb URL into the second box –
  35    superfluous arguments are automatically stripped.
  36  * Click “Update” to store your changes.
  37
  38 Caveats
  39 -------
  40 The plugin executes the “git” command line utility to check for objects in the
  41 configured Git repositories. Great care has been taken that every argument
  42 passed to the shell has been sanitized, but you may experience problems if
  43 PHP's “safe mode” is activated. The commands used are:
  44
  45  * git rev-parse
  46    Check existence of an object and determine it's complete object id.
  47  * git cat-file
  48    Determine an object's type.
  49
  50 License
  51 -------
  52 The “Gitweb” plugin is distributed under the terms of the MIT license. The
  53 complete licensing terms can be found at the beginning of the file
  54 “plugin.php”.
  55
  56 Author
  57 ------
  58 Florian “octo” Forster <ff at octo.it>