Florian octo Forster's Homepage

Gitweb plugin for YOURLS

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:

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.


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

git clone git://git.verplant.org/yourls-gitweb.git gitweb

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


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


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:

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


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.