rel=vcs-* microformat

The rel=vcs-* microformat allows a page to indicate the location of a Version Control System repository related to that page.

Tools can parse the microformat and use it to determine how to check out / clone from the VCS.

Examples
Format
Multiple repositories
Producers
Consumers
Related efforts and motivations

Examples

<head>
<link rel="vcs-git" href="git://example.org/foo.git" title="foo git repository" />
<link rel="vcs-svn" href="svn://svn.example.org/bar/trunk" title="bar svn repository" />
</head>

<a rel="vcs-git" href="git://example.org/foo.git" title="git repository">git://example.org/foo.git</a>
<a rel="vcs-git" href="git://example.org/foo.git">git repository</a>

Format

The rel=vcs-* microformat can only appear in the html <link> element in the <head> of the page, or in an <a> element in its body.

The rel attribute specifies what VCS is used. It can contain the name of any version control system, prefixed with "vcs-". Common values include "vcs-git", "vcs-svn", and "vcs-bzr".

The "href" holds a URI, or other location identifier, in a format supported by the version control system. If a version control system supports both URIs and some other location identifier form, the URI form is strongly preferred here. Making up URI forms just for use here is, however, discouraged.

The "title" is optional, but recommended if there are multiple, different repositories linked to on one page. It is a human-readable description of the repository. If the title is omitted from an <a> tag, the body of the tag should be a human-readable description.

Multiple repositories

Since many version control systems use one URI form (such as git:// or http://) for anonymous access, and another form (such as ssh:// or svn+ssh://) for authenticated access, multiple <link> or <a> tags can be used on the same page, to list each available URI. When this is done, the same text should be used for the title parameter of each repository. For example:

<head>
<link rel="vcs-git" href="git://foo.org/foo.git" title="foo git repository" />
<link rel="vcs-git" href="ssh://foo.org/git/foo.git" title="foo git repository" />
</head>

On the other hand, if a page links to multiple differing repositories, it should take care the use different titles for each.

<head>
<link rel="vcs-git" href="git://foo.org/foo.git" title="foo git repository" />
<link rel="vcs-git" href="git://foo.org/foo-contrib.git" title="foo-contrib git repository" />
</head>

Tools that process the microformats can assume that repositories listed on the same page, with the same title, each contain the same data. Such tools can choose which repository to use based on the type of URI it uses (for example by preferring git://, then http://, and finally ssh://).

If there are multiple repositories listed, without titles, tools should assume they are different repositories.

Producers

A website for a software package can use the rel=vcs-* microformat on its front page, and on any relevant download pages, to indicate the location of its VCS repository.

A VCS repository browser such as ViewVC or gitweb can use the rel=vcs-* microformat on pages it generates, to specify the location of the repository being browsed.

gitweb patch

A web site that is itself stored in a VCS repository can include the rel=vcs-* microformat on its pages to indicate the location of the repository.
ikiwiki repolist plugin
Debian's package tracker uses it to indicate the VCS of packages.
Request for support in launchpad

Consumers

webcheckout is a simple tool that downloads a URL and runs VCS programs to check out the repositories it references using this microformat. (webcheckout is included in the mr package.)

joey@gnu:~/tmp> webcheckout http://ikiwiki.info/
git clone git://github.com/joeyh/ikiwiki.git
Initialized empty Git repository in /home/joey/tmp/ikiwiki/.git/
remote: Counting objects: 52654, done.
remote: Compressing objects: 100% (12983/12983), done.
remote: Total 52654 (delta 39279), reused 51926 (delta 38578)
Receiving objects: 100% (52654/52654), 8.86 MiB | 225 KiB/s, done.
Resolving deltas: 100% (39279/39279), done.

An extension has been developed for the Semantic Radar firefox extension. It allows seeing which pages have rel-vcs information while browsing.

Related efforts and motivations

The Debian project added VCS-* fields to their source packages, indicating the repository used to develop each package, and many useful tools sprang up to take advantage of this information, such as debcheckout, which can automatically check out the source to a package from its VCS.

Joey discusses some of his other motivations in his introductory blog post.