# 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.

Query Parameters
Parameter | Opt/Req | Description
--- | --- | ---
`view=dir` | optional | `view` parameter
`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.