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.
<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>
rel=vcs-* microformat can only appear in the html
<link> element in
<head> of the page, or in an
<a> element in its body.
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.
Since many version control systems use one URI form (such as
http://) for anonymous access, and another form (such as
svn+ssh://) for authenticated access, multiple
<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.
<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
http://, and finally
If there are multiple repositories listed, without titles, tools should assume they are different repositories.
A website for a software package can use the
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
microformat on pages it generates, to specify the location of the
repository being browsed.
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
is a simple tool that downloads a URL and runs VCS programs
to check out the repositories it references using this microformat.
webcheckoutis 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.
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.