ViewVC: Frequently Asked Questions (FAQ)



General Usage

Where does the installation documentation, if any, live?

ViewVC's installation how-to documentation lives in the INSTALL file located in the root of the ViewVC source code distribution. The most recent version of this document (which may cover unreleased ViewVC versions) can be found at*checkout*/viewvc/trunk/INSTALL. If you are upgrading an existing ViewVC instance, you'll also want to read the upgrade documentation, found at*checkout*/viewvc/trunk/docs/upgrading-howto.html.

How can I expose ViewVC at the root of a virtual host on my webserver?

If you want to dedicate a virtual host on your server just to ViewVC, such the root directory of that host maps to ViewVC's root display, you can do so by placing the following lines inside the VirtualHost Apache configuration:

Alias /docroot /usr/local/viewvc/templates/docroot
ScriptAlias / /usr/local/viewvc/bin/cgi/viewvc.cgi/

The trick appears to be the presence of the trailing slash character on the ScriptAlias directive.

Does ViewVC support path-based authorization, such as Subversion's authz-file mechanism?

Yes, ViewVC 1.1.0 introduced this feature, and did so in a way that allows folks with Python programming skills to (relatively) easily drop in their own custom path-based authorization implementation modules.

What causes "Error: OSError: [Errno 2] No such file or directory: '/tmp/tmpGc-Ztj'"?

This is tracked in issue #282. While we haven't figured out how to make the error message more graceful or helpful, the basic problem seems to generally boil down to a misconfiguration of ViewVC. Make sure your helper applications are in the program search path ($PATH, e.g.) on your ViewVC server, or accurately specified in viewvc.conf.

Why does SOME-FEATURE work under, but not under Apache (or IIS or …)?

Most of the time folks run, they do so as a regular system user, from a shell running with any and all the environmental customizations present in their shell startup scripts. But most web server packages (like Apache) run as a different, often underprivileged, user, whose environment is stripped down to just the system-wide default state. This can cause problems for ViewVC's various helper applications, which might reside in a location that's included as part of your (and thus's) $PATH, but not that of the user as whom the web server package runs. The solution might be as simple explicitly configuring the paths of the helper applications in viewvc.conf, or as complex as expanding the program search path used by your web server software.

How do I enable ViewVC's RSS feed capabilities?

ViewVC generates its RSS feeds from repository data mirrored in a database as part of its MySQL integration. Follow the steps in ViewVC's INSTALL file to setup and configure the MySQL integration and begin mirroring your commit metadata in the database — the RSS feed feature will then be enabled with no additional configuration.

When I try to download a Microsoft Word 2007 (.docx) document, ViewVC tells me that it is a .zip file. How can I make files such as this open in Word?

As it turns out, .docx files are essentially just structured ZIP archives. Of course, you don't want them handled on the client side as ZIP archives, but as a Office OpenXML documents. The key to making this happen lies in having the server tell the user agent (or "web browser") precisely what kinds of files these are.

First, you'll want to make sure that ViewVC is configured to consult a MIME types mapping file. You do this via the options/mime_types_files option in viewvc.conf (or options/mime_types_file for ViewVC 1.0.x). Then, ensure the the MIME types mapping file you've told ViewVC to consult actually contains mappings for the various standard OpenXML file extensions:

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet           xlsx
application/vnd.openxmlformats-officedocument.spreadsheetml.template        xltx
application/vnd.openxmlformats-officedocument.presentationml.presentation   pptx
application/vnd.openxmlformats-officedocument.presentationml.slideshow      ppsx
application/vnd.openxmlformats-officedocument.presentationml.template       potx
application/vnd.openxmlformats-officedocument.wordprocessingml.document     docx
application/vnd.openxmlformats-officedocument.wordprocessingml.template     dotx

How does ViewVC determine a versioned file's MIME content type?

A file's MIME type is determined by consulting various sources of information. Here are those sources, ordered from highest to lowest priority:

  1. (for Subversion-versioned files where svn_ignore_mimetype = 0 in viewvc.conf) the svn:mime-type property set on the file.
  2. the mime type mapping files listed in viewvc.conf's mime_types_files configuration option, in the order listed. (In the recommended configuration, ViewVC's own mimetypes.conf file is the first of those in the list, but admins can change that if they so desire.
  3. any system mime type mapping files that Python's "mimetypes" module consults by default.

CVS Browsing

Why can I navigate only those CVS directories that have no files in them?

ViewVC can generally display CVS directories without the use of any external tools. But unless configured to use the incomplete, experimental rcsparse module (via the use_rcsparse configuration option), it relies on either the RCS toolchain or the CVSNT tool (on Windows) to get information about versioned files. If the system is missing both of these, you'll need to remedy that. If ViewVC simply cannot find the installed tools, ensure that they are available in the system $PATH, or specify their location in the viewvc.conf file using the utilities/rcs_dir or utilities/cvsnt options. (Note that prior to ViewVC 1.1.0, these options were found at general/rcs_path and general/cvsnt_exe_path.)

What causes "Error: Rlog output ended early. Expected RCS file "/opt/cvs/project/file,v""?

This is another symptom of the basic problem described here.

What causes "Error: COMalformedOutput: Unable to find filename in co output stream"?

This is another symptom of the basic problem described here.

What causes "Error: error during rlog: 0x100"?

### TODO ###

Why do my directories have no files in them?

There are a few reasons why this can happen. Here are some of the most common ones:

  • Some folks mistakenly point ViewVC's configuration bits to their CVS working copies. But ViewVC isn't a working copy browser — it's a repository browser. If you don't know the difference, here's a tip that might help: CVS repositories are directories trees filled with files that end with ",v". If your directory isn't filled with "comma vee" files, it probably is not a CVS repository.

ViewVC doesn't show files I'm looking for, and instead displays the message "NOTE: There are N files, but none match the current selection criteria". How can I fix this?

From time to time, CVS and CVSNT add support for new keywords to the RCS backend used to house repository data. If you're running a version of ViewVC or ViewCVS that hasn't yet learned to handle those new keywords, you might get the error you're seeing. The solution is to try to get versions of CVS/CVSNT and ViewVC which are better aligned, which generally means upgrading ViewVC (which is probably less disruptive than downgrading your version control system).

Why am I getting a stack trace with a "CreateProcess" error of "The system cannot find the file specified"?

The stack trace which ends with error: (2, 'CreateProcess', 'The system cannot find the file specified.') indicates that some program that ViewVC was trying to execute doesn't exist. Unfortunately, the error message and stack trace don't reveal which program ViewVC was trying to execute at the time. Usually it's the RCS or CVSNT executables that it employs to harvest your repository information, or perhaps one of the syntax coloration tools (enscript, highlight, etc.). If you are using ViewVC 1.1 or higher, review the settings in the [utilities] section of your viewvc.conf file; for older versions, these settings are scattered throughout viewvc.conf with names such as rcs_path, cvsnt_exe_path, enscript_path, and highlight_path.

Subversion Browsing

What causes "Error: ImportError: No module named svn"?

ViewVC uses Subversion's Python bindings to interact with and pull information out of your Subversion repositories. The error you see is Python being asked to import the Subversion Python bindings and being unable to do so. This is a common situation. These bindings are not generally provided as part of the ViewVC distribution — you have to install them yourself some other way.

In general, using the search term "python" with either "svn" or "subversion" in your system's package management tool will very likely point you to the package you require. For example, on Ubuntu Linux use the following command to install the Subversion Python bindings via the system's package management tool:

$ sudo apt-get python-svn

For more information, contact the Subversion community.

Can I use ViewVC with remote Subversion repositories?

ViewVC prefers to have direct access to the repository (and in fact, must have that for CVS repositories), but there does exist experimental support for remote Subversion repositories. Enabling this is a fairly simple — just use the URL of the repository where you would use its path in the svn_roots configuration options (sorry, you can't use root_parents for remote repositories because Subversion doesn't expose a repository-listing repository access API).

What you should expect:

  • Near parity with local-access Subversion in terms of functionality.

  • Known shortcomings:

    • file sizes aren't reported everywhere
    • the "revision" view lacks/botches some information
    • she ain't the fastest horse on the track…
  • Lack of configury for dealing with the intricacies of remote access. If the auth credentials and such you need to access the remote repository aren't cached in ~VIEWVC_USER/.subversion (where VIEWVC_USER is the system user as whom ViewVC runs), stuff won't work.