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.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. |
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 | 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 |
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 |
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, and "f"
for a full 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 |
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 |
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 |
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 |
gflip=GFLIP |
optional | "1" if the revisions in the graph should run youngest-to-oldest; "0" for the reverse |
gbbox=GBBOX |
optional | "1" if the revision graph should contain branch boxes at the tip of each branch; "0" otherwise |
gleft=GLEFT |
optional | "1" if the revision graph should be orientated left-to-right; "0" otherwise |
gmaxtag=GMAXTAG |
optional | maximum number of per-revision tags to show in the revision graph |
gshow=GSHOW |
optional | "all", "inittagged", or "tagged" — user-selected classes of revision to show in the graph |
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 |
gflip=GFLIP |
optional | "1" if the revisions in the graph should run youngest-to-oldest; "0" for the reverse |
gbbox=GBBOX |
optional | "1" if the revision graph should contain branch boxes at the tip of each branch; "0" otherwise |
gleft=GLEFT |
optional | "1" if the revision graph should be orientated left-to-right; "0" otherwise |
gmaxtag=GMAXTAG |
optional | maximum number of per-revision tags to show in the revision graph |
gshow=GSHOW |
optional | "all", "inittagged", or "tagged" — user-selected classes of revision to show in the graph |
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 |
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 |
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 |
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 |
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
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 |
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 |
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
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_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 |
Path Components (in order of appearance in the URL) | ||
---|---|---|
Component | Opt/Req | Description |
Query Parameters | ||
---|---|---|
Parameter | Opt/Req | Description |
view=revision |
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 |
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. |
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 |
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.