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/3f14d8fa
  11
  12 And further imagine that “3f14d8fa” 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
  22 Installation
  23 ------------
  24 First, you need at least YOURLS, version 1.5. Versions before that do not
  25 provide a plugin infrastructure.
  26
  27  * Copy the plugin to “$yourls_dir/user/plugins/”. To check out the Git
  28    repository change into this directory and run:
  29
  30      $ git clone git://git.verplant.org/yourls-gitweb.git gitweb
  31
  32  * Open the administrative interface in the web-browser of your choice.
  33  * Open the “Plugins” page and search for the “Gitweb” plugin in the table.
  34  * Click “Activate” in the rightmost “Action” column.
  35  * A new bulletin “Gitweb” should appear below the link to the “Plugins” page.
  36  * Go to the “Gitweb” page.
  37  * Insert the base directory and the Gitweb URL. The base directory should be
  38    the same directory you specified using “$projectroot” in your Gitweb
  39    configuration. You can pass any valid Gitweb URL into the second box –
  40    superfluous arguments are automatically stripped.
  41  * Click “Update” to store your changes.
  42
  43
  44 Caveats
  45 -------
  46 The plugin executes the “git” command line utility to check for objects in the
  47 configured Git repositories. Great care has been taken that every argument
  48 passed to the shell has been sanitized, but you may experience problems if
  49 PHP's “safe mode” is activated. The commands used are:
  50
  51  * git rev-parse
  52    Check existence of an object and determine it's complete object id.
  53  * git cat-file
  54    Determine an object's type.
  55
  56
  57 License
  58 -------
  59 The “Gitweb” plugin is distributed under the terms of the MIT license. The
  60 complete licensing terms can be found at the beginning of the file
  61 “plugin.php”.
  62
  63
  64 Author
  65 ------
  66 Florian “octo” Forster <ff at octo.it>