ViewVC 1.0 URL Reference

Introduction

This document describes the format of URLs accepted by ViewVC 1.0 and is intended to be useful to users and outside software developers who want to create links to ViewVC pages. It should also be useful to ViewVC developers as a way of tracking and documenting the many quirks of ViewVC's URL handling logic.

Future releases of ViewVC will support the URL formats described in this document. Certain URLs currently accepted by ViewVC, such as redirecting URLs that result from the submission of form elements on ViewVC pages, are not documented here and therefore may not be supported by future releases of ViewVC.

Table of Contents

URL Components

A ViewVC URL consists of 3 components: a Script Location, a Repository Path, and some optional Query Parameters. Some examples:

ViewVC Script Location Repository Path Query Parameters
http://example.org/viewvc.cgi /some/file ?view=log&revision=1.34
http://example.org/viewvc.cgi /*checkout*/some/other/file ?revision=1.10.2.5
http://example.org/viewvc.cgi /some/dir/ ?pathrev=BRANCH_2_3
http://example.org/viewvc.cgi /some/dir.tar.gz ?view=tar&pathrev=BRANCH_2_3
http://example.org/viewvc.cgi /yet/another/file ?view=diff?r1=1.12&r2=1.14

ViewVC Script Location

The script location is a common base for all ViewVC URL's pertaining to a particular installation. It's whatever location the web server is configured to serve ViewVC pages from.

Repository Path

Since ViewVC is essentially a file system browser for repositories, repository paths referring to the files and directories being browsed get their own section in ViewVC URLs immediately following the script location. Repository paths are always case sensitive and separated by forward slashes, regardless of the underlying filesystem.

Repository paths can be given certain "magic" prefixes and suffixes. For example, a "/*checkout*" prefix can be added to file views to force a checkout even without an explicit "view=co" query parameter. And a ".tar.gz" suffix is added to download tarball URLs so downloaded tarballs will be saved with sensible default names.

If the root_as_url_component configuration option is enabled, the first directory name in a repository path (after any magic prefix) is taken to be the name (from the ViewVC configuration) of the repository to browse rather than the name of an actual directory. The repository name can also be specified in a "root=" query parameter instead (see root parameter below).

Paths beginning with "/*docroot*/" are an exception the rules above. These paths are used to provide access to files in the ViewVC template directory: image files, static HTML pages, and the ViewVC stylesheet. For more information, see the Docroot View syntax below.

Query Parameters

Following the ViewVC and repository locations in URLs is an optional query string, a list of parameter/value pairs written like "?param1=value1&param2=value2..." Some parameters, like "revision", "pathrev", and "root", augment repository path information, specifying revisions and repositories. Other parameters like "logsort" and "diff_format" control ViewVC display options. Some parameters are also "sticky" and get embedded into links inside the generated pages, sticking around for future page views.

ViewVC provides a number of different views of repository data including a directory listing view, a log view, a file diff view, and others. (The views are listed and described in the help_rootview.html ViewVC help page). URLs for each of these views accept specific parameters described in the URL Syntax section, but some parameters are used by multiple views and they are described below:

Parameter Description
view The name of the view to display, does not need to be explicitly specified in many URLs. Possible values are shown in the URL Syntax section below.
revision The revision or tag to display information about, used by several different views.
pathrev The current sticky revision (Subversion) or sticky tag (CVS), as described in the help_rootview.html ViewVC help page. In Subversion, because path information is revision controlled, this value is also used to look up paths in the repository, providing a means of accessing paths that no longer exist in HEAD.
root The name of the repository to browse. When the default_root configuration option is set or the root_as_url_component option is enabled, it is not neccessary to to specify this parameter. When the root_as_url_component option is enabled, ViewVC URLs with root parameters redirect to locations with the root values embedded in the repository paths.

URL Syntax

This section lists URL syntax for each ViewVC view. Parts of URLs which may vary shown as variables in UPPERCASE.

Annotate View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/PATH required file path to annotate

Query Parameters
Parameter Opt/Req Description
view=annotate depends view parameter. Not required when an annotate parameter is present
annotate=REVISION optional revision or tag to annotate
pathrev=PATHREV optional pathrev parameter
root=ROOT depends root parameter

Checkout View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/*checkout* optional magic prefix. If specified when the checkout_magic configuration option is disabled, ViewVC will redirect to a URL without the prefix.
/PATH required file path to check out

Query Parameters
Parameter Opt/Req Description
view=co depends view parameter, not needed if the default_file_view configuration variable is set to co, since that makes the checkout view the default view for file paths. Also not needed if the /*checkout* magic prefix or the revision parameter is present.
content-type=TYPE optional MIME type to send with checked out file, default is a guess based on file extension
revision=REVISION optional revision parameter
pathrev=PATHREV optional pathrev parameter
root=ROOT depends root parameter

Diff View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/PATH required file path to display diff of

Query Parameters
Parameter Opt/Req Description
view=diff optional view parameter
r1=R1 required starting revision or tag or the string "text" to indicate that TR1 value (below) should override this one
r2=R2 required ending revision or tag or the string "text" to indicate that TR2 value (below) should override this one
tr1=TR1 depends starting revision or tag, used if r1 parameter is present and set to "text"
tr2=TR2 depends ending revision or tag, used if r2 parameter is present and set to "text"
p1=P1 optional starting file path that can override the PATH value to allow files at two different paths to be compared
p2=P2 optional ending file path that can override the PATH value to allow files at two different paths to be compared
diff_format=DIFF_FORMAT optional value specifying the type of diff to display. Can be "u" for unified diff, "c" for context diff, "s" for side by side diff, "h" for human readable diff, "l" for long human readable diff. If no value is specified the default depends on the diff_format configuration option.
pathrev=PATHREV optional pathrev parameter
root=ROOT depends root parameter

Directory Listing View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/PATH/ required directory path to view. If the trailing slash is omitted, ViewVC will redirect to a URL that has a trailing slash.

view parameter
Query Parameters
Parameter Opt/Req Description
view=dir optional
hideattic=HIDEATTIC optional "0" to show dead files in CVS directory listings or "1" to hide dead files. Default depends on the hide_attic configuration value.
search=SEARCH optional regular expression to search files in the directory with if use_re_search configuration option is enabled
sortby=SORTBY optional "file" "rev" "date" "author" or "log" to indicate how the directory listing should be sorted. Default depends on sortby configuration option.
sortdir=SORTBY optional "up" to sort directory in ascending order or "down" for descending order. Default is "up".
dir_pagestart=PAGE optional item number to start listing at if paging is enabled
pathrev=PATHREV optional pathrev parameter
root=ROOT depends root parameter

Docroot View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/*docroot* required magic prefix
/PATH required file path to retrieve. ViewVC will return the contents of the file located at PATH, relative to the docroot subdirectory of the directory specified in the template_dir configuration option.

Query Parameters
Parameter Opt/Req Description

Graph View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/PATH required file path to generate CvsGraph page for

Query Parameters
Parameter Opt/Req Description
view=graph required view parameter
root=ROOT depends root parameter

Graph Image View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/PATH required file path to generate CvsGraph image for

Query Parameters
Parameter Opt/Req Description
view=graphimg required view parameter
root=ROOT depends root parameter

Log View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/PATH required file or directory path to generate log for

Query Parameters
Parameter Opt/Req Description
view=log depends view parameter, does not need to be specified for file paths when the default_file_view configuration option is set to log. However it is recommended that the parameter be passed anyway for consistency with directory log URLs and compatibility with ViewVC installations that set default_file_view to co.
logsort=SORT optional "rev" to sort log entries by revision number or "date" to sort by date. Default depends on the log_sort configuration value.
log_pagestart=PAGE optional item number to start listing at if paging is enabled
r1=R1 optional current revision selected for diffs
diff_format=DIFF_FORMAT optional currently selected diff format
pathrev=PATHREV optional pathrev parameter
root=ROOT depends root parameter

Markup View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/PATH required file path to mark up

Query Parameters
Parameter Opt/Req Description
view=markup required view parameter
revision=REVISION optional revision parameter
pathrev=PATHREV optional pathrev parameter
root=ROOT depends root parameter

Patch View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/PATH required file path to display patch of

Query Parameters
Parameter Opt/Req Description
view=patch required view parameter
r1=R1 required starting revision or tag or the string "text" to indicate that TR1 value (below) should override this one
r2=R2 required ending revision or tag or the string "text" to indicate that TR2 value (below) should override this one
tr1=TR1 depends starting revision or tag, only used if r1 parameter is present and set to "text"
tr2=TR2 depends ending revision or tag, only used if r2 parameter is present and set to "text"
p1=P1 optional starting file path that can override the PATH value to allow files at two different paths to be compared
p2=P2 optional ending file path that can override the PATH value to allow files at two different paths to be compared
diff_format=DIFF_FORMAT optional value specifying the type of patch to display. Can be "u" for unified diff or "c" for context diff. If no value is specified the default depends on the diff_format configuration option.
pathrev=PATHREV optional pathrev parameter
root=ROOT depends root parameter

Query Form View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/PATH required file path to display query results from

Query Parameters
Parameter Opt/Req Description
view=queryform required view parameter
branch=BRANCH optional branch query string
branch_match=BRANCH_MATCH optional "exact" "like" "glob" "regex" or "notregex" determining type of branch match
dir=DIR optional directory query string
file=FILE optional file query string
file_match=FILE_MATCH optional "exact" "like" "glob" "regex" or "notregex" determining type of file match
who=WHO optional author query string
who_match=WHO_MATCH optional "exact" "like" "glob" "regex" or "notregex" determining type of author match
querysort=SORT optional "date" "author" or "file" determining order of query results
date=DATE optional "hours" "day" "week" "month" "all" or "explicit" to filter query results by date
hours=HOURS optional number of hours back to include results from when DATE is "hours"
mindate=MINDATE optional earliest date to include results from when DATE is "explicit"
maxdate=MAXDATE optional latest date to include results from when DATE is "explicit"
limit_changes=LIMIT_CHANGES optional maximum number of files to list per commit in query results. Default is value of limit_changes configuration option
root=ROOT depends root parameter

Query View

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/PATH required file path to display query results from

Query Parameters
Parameter Opt/Req Description
view=query required view parameter
branch=BRANCH optional branch query string
branch_match=BRANCH_MATCH optional "exact" "like" "glob" "regex" or "notregex" determining type of branch match
dir=DIR optional directory query string
file=FILE optional file query string
file_match=FILE_MATCH optional "exact" "like" "glob" "regex" or "notregex" determining type of file match
who=WHO optional author query string
who_match=WHO_MATCH optional "exact" "like" "glob" "regex" or "notregex" determining type of author match
querysort=SORT optional "date" "author" or "file" determining order of query results
date=DATE optional "hours" "day" "week" "month" "all" or "explicit" to filter query results by date
hours=HOURS optional number of hours back to include results from when DATE is "hours"
mindate=MINDATE optional earliest date to include results from when DATE is "explicit"
maxdate=MAXDATE optional latest date to include results from when DATE is "explicit"
format=FORMAT optional "rss" or "backout" values to generate an rss feed or list of commands to back out changes instead showing a normal query result page
limit=LIMIT optional maximum number of file-revisions to process during a query. Default is value of row_limit configuration option
limit_changes=LIMIT_CHANGES optional maximum number of files to list per commit in query results. Default is value of limit_changes configuration option
root=ROOT depends root parameter

Revision View

Path Components (in order of appearance in the URL)
Component Opt/Req Description

Query Parameters
Parameter Opt/Req Description
view=rev required view parameter
revision=REVISION optional revision parameter
limit_changes=LIMIT_CHANGES optional maximum number of files to list per commit. Default is value of limit_changes configuration option
root=ROOT depends root parameter

Repository Listing

Path Components (in order of appearance in the URL)
Component Opt/Req Description

Query Parameters
Parameter Opt/Req Description
view=roots depends view parameter. Not required if the root_as_url_component configuration is enabled or the default_root option is not set.

Tarball Download

Path Components (in order of appearance in the URL)
Component Opt/Req Description
/PATH required directory path to download
.tar.gz depends magic suffix. Only required when the name of the directory being downloaded ends in ".tar.gz" and the parent parameter not is present. But it is recommended to add the magic suffix to all tarball URLs to avoid this special case and give the downloaded files sensible default names.

Query Parameters
Parameter Opt/Req Description
view=tar required view parameter
parent=1 optional If the parent parameter is specified, the last component of the PATH is discarded before it is ever looked up in the repository. This feature is used when the root_as_url_component configuration option is disabled to allow root tarball URLs to be saved with names like "ROOT-root.tar.gz".
pathrev=PATHREV optional pathrev parameter
root=ROOT depends root parameter

Backwards Compatibility

ViewVC's URL format has changed a lot over time, but ViewVC goes out of its way to support URLs using older formats so there aren't broken links when an installation of ViewVC is upgraded. The support is implemented as a set of URL transformations that recognize elements of old-style URLs and convert them to newer equivalents. If any transformations are applied (with some exceptions, mentioned below), ViewVC will issue a single redirect to the transformed URL. Descriptions of the transformations follow.

'cvsroot' Parameter ⇒ 'root'

URLs with a cvsroot parameter will automatically be redirected to URLs with a root parameter instead.

'only_with_tag' Parameter ⇒ 'pathrev'

URLs with an only_with_tag parameter will automatically be redirected to URLs with a pathrev parameter instead.

'~checkout~' Magic Path Prefix ⇒ '*checkout*'

URLs with a ~checkout~ path prefix get interpreted just like URLs with a '*checkout*' prefix. There is currently no redirect, but there could be in the future.

'*checkout*' Magic Path Prefix ⇒ 'view=co'

When the checkout_magic configuration option is disabled, URLs with a *checkout* magic prefix will redirect to an equivalent URL that does not use the prefix.

'root' Parameter ⇒ Root Path Component

When the root_as_url_component configuration option is enabled, URLs with a root parameter will redirect to an equivalent URL with the root name embedded in the path.

'rev' Parameter ⇒ 'revision' and 'pathrev'

CVS URLs with a rev parameter will redirect to URLs with a revision parameter instead. Subversion URLs with a rev parameter will redirect to URLs with a pathrev parameter, in order to account for the how the Subversion backend used to look up paths before pathrev was introduced.

'.diff' Suffix ⇒ Diff View

When ViewVC encounters a invalid repository path that ends in .diff, and stripping that ending yields a valid file path, it will redirect to a diff view of the file.

'.tar.gz' Suffix ⇒ 'view=tar'

When ViewVC encounters a invalid repository path that ends in .tar.gz, /root.tar.gz, or /REPOS-root.tar.gz, and stripping the ending yields a valid directory path, it will redirect to a URL to download a tarball of the directory.

'tarball=1' Parameter ⇒ 'view=tar'

A tarball=1 parameter is treated pretty much like a view=tar parameter. There is no redirect when it is encountered, but there could be in the future.

'graph=1' Parameter ⇒ 'view=graph'

A graph=1 parameter is treated like a view=graph parameter. There is currently no redirect when it is encountered, but there could be one in the future.

'graph=1&makeimage=1' Parameters ⇒ 'view=graphimg'

A graph=1&makeimage=1 parameter is treated like a view=graph parameter. There is currently no redirect when it is encountered, but there could be one in the future.

'content_type=text/vnd.viewcvs-markup' and 'content_type=text/x-cvsweb-markup' Parameters⇒ 'view=markup'

content_type=text/vnd.viewcvs-markup and content_type=text/x-cvsweb-markup parameters are treated like a view=markup parameter. There is currently no redirect when it is encountered, but there could be one in the future.

'Attic/FILE' Paths ⇒ 'FILE'

When ViewVC encounters an invalid repository path whose last or second-to-last component is named Attic, and stripping the component yields a valid path, it will redirect to a URL with that path.