This document describes the format of URLs accepted by ViewVC 1.1 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.
view=rev' Parameter ⇒ 'view=revision'cvsroot' Parameter ⇒ 'root'only_with_tag' Parameter ⇒ 'pathrev'~checkout~' Magic Path Prefix ⇒ '*checkout*'*checkout*' Magic Path Prefix ⇒ 'view=co'root' Parameter ⇒ Root Path Componentrev' Parameter ⇒ 'revision' and 'pathrev'.diff' Suffix ⇒ Diff View.tar.gz' Suffix ⇒ 'view=tar'tarball=1' Parameter ⇒ 'view=tar'graph=1' Parameter ⇒ 'view=graph'graph=1&makeimage=1' Parameters ⇒ 'view=graphimg'content-type=text/vnd.viewcvs-markup' and 'content-type=text/x-cvsweb-markup' Parameters⇒ 'view=markup'
    Attic/FILE' Paths ⇒ 'FILE'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 | 
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.
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.
Following the ViewVC and repository locations in URLs is an optional query string, a list of parameter/value pairs written like "?param1=value1¶m2=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.htmlViewVC
        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_rootconfiguration option is set or theroot_as_url_componentoption is enabled, it is
        not neccessary to to specify this parameter. When theroot_as_url_componentoption is enabled, ViewVC
        URLs withrootparameters redirect to locations
        with the root values embedded in the repository paths. | 
This section lists URL syntax for each ViewVC view. Parts of URLs which may vary shown as variables in UPPERCASE.
| 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 | viewparameter. Not
        required when anannotateparameter is
        present | 
| annotate=REVISION | optional | revision or tag to annotate | 
| pathrev=PATHREV | optional | pathrevparameter | 
| root=ROOT | depends | rootparameter | 
| Path Components (in order of appearance in the URL) | ||
|---|---|---|
| Component | Opt/Req | Description | 
| /*checkout* | optional | magic prefix. If specified when the checkout_magicconfiguration 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 | viewparameter, not
        needed if thedefault_file_viewconfiguration
        variable is set toco, since that makes the
        checkout view the default view for file paths. Also not needed
        if the/*checkout*magic prefix or therevisionparameter 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 | revisionparameter | 
| pathrev=PATHREV | optional | pathrevparameter | 
| root=ROOT | depends | rootparameter | 
| 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 | viewparameter | 
| r1=R1 | required | starting revision or tag or the string "text" to indicate that TR1value (below) should override this
        one | 
| r2=R2 | required | ending revision or tag or the string "text" to indicate that TR2value (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 PATHvalue to allow files at two different
        paths to be compared | 
| p2=P2 | optional | ending file path that can override the PATHvalue 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, and "f"
        for a full human readable diff. If no value is specified the
        default depends on the diff_formatconfiguration
        option. | 
| pathrev=PATHREV | optional | pathrevparameter | 
| root=ROOT | depends | rootparameter | 
| 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 | viewparameter | 
| hideattic=HIDEATTIC | optional | "0" to show dead files in CVS directory listings or "1" to
        hide dead files. Default depends on the hide_atticconfiguration value. | 
| search=SEARCH | optional | regular expression to search files in the directory with if use_re_searchconfiguration option is enabled | 
| sortby=SORTBY | optional | "file" "rev" "date" "author" or "log" to indicate how the
        directory listing should be sorted. Default depends on sortbyconfiguration 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 | pathrevparameter | 
| root=ROOT | depends | rootparameter | 
| 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 thedocrootsubdirectory of the directory specified in
        thetemplate_dirconfiguration option. | 
| Query Parameters | ||
|---|---|---|
| Parameter | Opt/Req | Description | 
| 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 | viewparameter | 
| root=ROOT | depends | rootparameter | 
| 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 | viewparameter | 
| root=ROOT | depends | rootparameter | 
| 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 | viewparameter, does
        not need to be specified for file paths when thedefault_file_viewconfiguration option is set tolog. However it is recommended that the parameter be
        passed anyway for consistency with directory log URLs and
        compatibility with ViewVC installations that setdefault_file_viewtoco. | 
| logsort=SORT | optional | "rev" to sort log entries by revision number or "date" to sort
        by date. Default depends on the log_sortconfiguration 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 | pathrevparameter | 
| root=ROOT | depends | rootparameter | 
| 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 | viewparameter | 
| revision=REVISION | optional | revisionparameter | 
| pathrev=PATHREV | optional | pathrevparameter | 
| root=ROOT | depends | rootparameter | 
| 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 | viewparameter | 
| r1=R1 | required | starting revision or tag or the string "text" to indicate that TR1value (below) should override this
        one | 
| r2=R2 | required | ending revision or tag or the string "text" to indicate that TR2value (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 PATHvalue to allow files at two different
        paths to be compared | 
| p2=P2 | optional | ending file path that can override the PATHvalue 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_formatconfiguration
        option. | 
| pathrev=PATHREV | optional | pathrevparameter | 
| root=ROOT | depends | rootparameter | 
| 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 | viewparameter | 
| 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 | 
| comment=COMMENT | optional | log message query string | 
| comment_match=COMMENT_MATCH | optional | "exact" "like" "glob" "regex" or "notregex" determining type of log message 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 DATEis "hours" | 
| mindate=MINDATE | optional | earliest date to include results from when DATEis "explicit" | 
| maxdate=MAXDATE | optional | latest date to include results from when DATEis "explicit" | 
| limit_changes=LIMIT_CHANGES | optional | maximum number of files to list per commit in query
        results. Default is value of limit_changesconfiguration option | 
| root=ROOT | depends | rootparameter | 
| 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 | viewparameter | 
| 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 | 
| comment=COMMENT | optional | log message query string | 
| comment_match=COMMENT_MATCH | optional | "exact" "like" "glob" "regex" or "notregex" determining type of log message 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 DATEis "hours" | 
| mindate=MINDATE | optional | earliest date to include results from when DATEis "explicit" | 
| maxdate=MAXDATE | optional | latest date to include results from when DATEis "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_changes=LIMIT_CHANGES | optional | maximum number of files to list per commit in query
        results. Default is value of limit_changesconfiguration option | 
| root=ROOT | depends | rootparameter | 
| Path Components (in order of appearance in the URL) | ||
|---|---|---|
| Component | Opt/Req | Description | 
| Query Parameters | ||
|---|---|---|
| Parameter | Opt/Req | Description | 
| view=revision | required | viewparameter | 
| revision=REVISION | optional | revisionparameter | 
| limit_changes=LIMIT_CHANGES | optional | maximum number of files to list per commit. Default is value
        of limit_changesconfiguration option | 
| root=ROOT | depends | rootparameter | 
| Path Components (in order of appearance in the URL) | ||
|---|---|---|
| Component | Opt/Req | Description | 
| Query Parameters | ||
|---|---|---|
| Parameter | Opt/Req | Description | 
| view=roots | depends | viewparameter. Not
        required if theroot_as_url_componentconfiguration
        is enabled or thedefault_rootoption is not
        set. | 
| 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 parentparameter 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 | viewparameter | 
| parent=1 | optional | If the parentparameter is specified, the last
        component of thePATHis discarded before
        it is ever looked up in the repository. This feature is used when
        theroot_as_url_componentconfiguration option is
        disabled to allow root tarball URLs to be saved with names like
        "ROOT-root.tar.gz". | 
| pathrev=PATHREV | optional | pathrevparameter | 
| root=ROOT | depends | rootparameter | 
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.
view=rev' Parameter ⇒ 'view=revision'URLs with a view=rev parameter will automatically be
   redirected to URLs with a view=revision parameter
   instead.
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 ComponentWhen 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 ViewWhen 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.  Other values of the content-type
   parameter, which were used to dictate the MIME type of files
   displayed in the checkout/download view prior to ViewVC 1.0.6, are
   ignored.
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.