Florian octo Forster's Homepage

YOURLS is an URL shortener – a small PHP script which redirects users based on short URLs stored in a database. It provides a plugin infrastructure which makes it possible to extend the script without having to modify the core code.

I've written a plugin for YOURLS, called Gitweb, which can be used to automatically redirect to a Gitweb installation, if the provided keyword identifies a Git object. Gitweb is a web-based front-end to the source code management tool Git. A Git object has one of four types:

• commit
• tree
• tag
• blob

In Git, every “object” is identified by the SHA-1 hash value of its content. The 160 bit hash value is usually displayed as a 40-digit hexadecimal number. However, in most cases a lot less digits suffice to unambiguously identify an object; usually the first seven or eight digits are used. This plugin redirects the user to the Gitweb page of an object, if

1. the provided keyword is not in the database,
2. the keyword looks like a valid object name, i.e. it matches the regular expression ^[0-9a-fA-F]{6,40}$, and
3. an object of that name is found in one of the configured Git repositories.

For example, imagine a user opening this URL:

And further imagine that “c09f76fe” is not a short URL stored in the database. This plugin will intercept the redirect_keyword_not_found action and check if the keyword is a hexadecimal number with at least six (hexadecimal) digits. If so, the plugin will iterate over all Git repositories in a base directory and check if there's an object in one of them which matches the given id. If such an object is found, the user will be redirected to the appropriate Gitweb page. Otherwise, YOURLS will proceed as usual.

Download

It's recommended that you “clone” the Git repository, which is available at:

If you can't clone the repository for some reason, you can download one of the following tarballs:

• gitweb-1.0.tar.bz2
• gitweb-1.0.tar.gz

Installation

First, you need at least YOURLS, version 1.5. Versions before that do not provide a plugin infrastructure.

• Change to the directory
  $ cd $yourls_dir/user/plugins/
  and clone the Git repository of the Gitweb plugin:
  $ git clone git://git.verplant.org/yourls-gitweb.git gitweb
  This will create a new subdirectory called gitweb and download the plugin into it.
• Open the administrative interface in the web-browser of your choice. Open the Plugins page and search for the Gitweb plugin in the table. Click Activate in the Action column (the rightmost column).
• A new bulletin Gitweb should appear below the link to the Plugins page. Go to the Gitweb page.
• Insert the base directory and the Gitweb URL. The base directory should be the same directory you specified using $projectroot in your Gitweb configuration. You can pass any valid Gitweb URL into the second box – superfluous arguments are automatically stripped. Click Update to store your changes.

Caveats

The plugin executes the git(1) command line utility to check for objects in the configured Git repositories. Great care has been taken that every argument passed to the shell has been sanitized, but you may experience problems if PHP's safe mode is activated. The commands used are:

• git-rev-parse(1)
  Check existence of an object and determine it's complete object id.
• git-cat-file(1)
  Determine an object's type.

The plugin will redirect to the first object that is uniquely identified by a keyword. If multiple repositories are applicable, for example because the same project is cloned multiple times, it will redirect to a pseudo-random repository (the order in which repositories are tried depends on the file system). If the keyword is ambiguous in a repository, then the plugin will not redirect to this repository. It may still redirect to another repository in which an object is uniquely identified by the keyword.

See also

• YOURLS website
• Page about Gitweb in the Git wiki
• Gitweb page of the yourls-gitweb.git repository

License

The Gitweb plugin is distributed under the terms of the MIT license. The complete licensing terms can be found at the beginning of the file plugin.php.