Screenshots

Home page of CvsGui

Download latest version

Checkout the mirrors of CvsGui

Latest information about CvsGui development

Some tiny documentation

Development page

mirror location

LogoCvsGui
SourceForge Logo


Frequently Asked Questions (draft)

FAQ of CvsGui.
(last reviewed for WinCvs 1.3.24)

Please keep in mind that this page is not yet completed.

If you are experiencing a problem, look here:

If your question is not answered in this document, try to search one of the following:

Before you read on:

You have probably come here because you've got a question about either WinCvs, MacCvs or gCvs. However, if you're still new to both CVS and CvsGui please make sure you read and understand What is the difference between WinCvs and CVS ? first. It might turn out your question could better be answered on a general CVS list or FAQ.

Table Of Contents

General topics
What is the difference between WinCvs and CVS ?
Is there a CVS-server on Windows NT/2000/XP ?
Where can I find Tutorials or other Getting Started type of material ?
What info should I supply when posting about a problem on a support forum (such as the CVSGUI mailing list)?
Using WinCvs
I have got Cygwin 1.5.7 or later installed and WinCvs hangs or crashes right on startup. What should I do?
It appears that in WinCvs 1.3 neither the "RSA private key file (identity)" nor the "Additional SSH options" settings have any effect at all. What's going on?
I just upgraded to WinCvs 1.3.18 or later and can no longer find a place to enter my CVSROOT. Where has the General tab gone?
WinCvs tells me Warning: Using remote (network) drive may cause file system errors and performance decrease
Use local fixed drives for best safety and high performance
What are the reasons for this discouragement?
Yet unclassified topics
I want to add a file to CVS but I get: cannot open CVS/Entries for reading... What's going on ?
How can I recursively add a complete file/folder hierarchy to CVS ?
When should I use import instead of add? What are the differences ?
Why do I have to specify the Vendor branch and Release tags on import ?
What could/should I do with them ? How do I get rid of them ?
How can I add a new root-level module without using the Import command ?
When I try to lock a file I get: 'admin -l' is a deprecated option... What now ?
What are reserved edits ? How can I use them ?
When should I use locking / reserved edits and why ?
WinCvs often hangs when one of my sandboxes is on a remote machine (via UNC or shared drives). What can I do ?
It's nice that WinCvs remembers all the entries I ever made into a combobox, but how can I purge the by-now obsolete items ?
I have changed my username / CVSROOT in the preferences but WinCvs still seems to use the old one. What should I do ?
What CVSROOT settings should I use for my repository ?
I get the following message: move away MyFile.h; it is in the way What's going on?
How am I supposed to manage projects with WinCvs ?
Can I handle multiple repositories with WinCvs ? How ?
ActiveTCL is properly installed but WinCvs 1.2 still says TCL not available. What now ?
What are Python and/or TCL needed for ? Do I really need to install both ?
My files are always displayed as modified although they're not - even after commit. What's going on ?
I cannot see any of the files in my sandbox unless I modify them. What the heck is going on ?
How am I supposed to use the file filters ?
What exactly is a Sandbox, a Working Copy or, while we're at it, a Browse Location ?
How can I revert changes, i.e. return to a previous revision and continue development based on it ?
How can I resurrect a file that was removed using cvs remove ?
What does the "P" in the output of Update mean ?
How can I have automatic mail notification on Commit ?
How can I see what's in the repository ?
When I run the "List modules on server" / "Get cvs modules" macro, nothing happens. Is it broken ?
Can WinCvs do visual diffs ? How ?
How can I really delete a revision ?
I accidentally checked in garbage and want to hush it up.
Should I consult an expert from the NSA for advice on such matters ?
Is there a GUI to the cvs admin -o command ? Where ?
How is the modules file supposed to be used ?
When and how should I use branches ?
How do I tell when a specific tag was set on a module or file ?
Why can't I see merges in the Graph view ?
When I try to execute commands from WinCvs' console view, I get Traceback [...] NameError: name 'cvs' is not defined What have I done wrong ?
Whenever I merge a branch more than once I always have to resolve a lot of conflicts. Could I somehow avoid this ?
I cannot commit my changes. CVS tells me sticky tag `someTag' is not a branch What now ?
I have tagged a file / module but the tag isn't displayed in the "Tag" column. Is this a bug ?

General topics
What is the difference between WinCvs and CVS ?

WinCvs is not a replacement for CVS. Instead, WinCvs is a GUI front-end for a CVS commandline client. WinCvs versions prior to the 1.3 cycle used a modified cvs exectuable which was recompiled as a wrapper dll. WinCvs 1.3.x and later bundle the executable (and protocol libraries) from the most recent stable CVSNT distribution. You are however free to choose any other cvs exectuable via the Alternate CVS executable option on the Admin|Preferences/CVS tab, as long as it supports the cvsgui protocol. This latter requirement is planned to be loosened in the future, too.

An important thing to understand here is that WinCvs itself never ever manipulates either your sandbox files nor your repository directly. All access to those files happens strictly by invoking the CVS commandline client. Therefore you cannot really do anything with WinCvs that you couldn't do with the commandline client as well (even though it should usually be easier to do it via the GUI). Note that this is only true for the "core" application. There are some macros that will manipulate your sandbox data directly, e.g. to cleanup Missing file entries after an incomplete Release or to emulate repository browsing for servers that do not support it natively.

Otherwise, there often is a 1:1 relation between the available commands and options of the commandline client and the respective dialogs and their options in WinCvs. Some options and commands are not (yet) exposed in the GUI though, so you will occasionally have to go to the commandline console to get certain tasks done. The CVSGUI team is however continually working on exposing all of the commandline client's functionality.

There's another thing inherent with these facts: WinCvs is not a CVS server! It can be used to run the client in :local: mode, so you could manage a single-user repository on your local machine all from within the WinCvs GUI, but as soon as your repository is going to be accessed by more than a single local user and/or from a different machine, you should look for a "real" CVS server. Currently the most advanced one is the CVSNT project, which is available also for Windows, MacOSX and various Unix-based operating systems. The "original" GNU CVS project is maintained at www.cvshome.org, where you could also find CVS servers and documentation for a plethora of other operating systems as well.

Now, once you have understood the role of WinCvs you might want to consider, whether your question or problem is really one with the WinCvs frontend or rather with underlying CVS system (either client or server). There are of course many grey areas and overlaps so there's usually no harm in asking on the CVSGUI list anyway, but you should be aware that you will get a broader and potentially more knowledgeable audience for basic CVS questions on the CVSNT list (alternatively its usenet relay) or the various lists and groups on the CVS homepage.

Is there a cvs server on Windows NT/2000/XP ?
Yes, thanks to Tony Hoyle who did a great work. WinCvs will try to keep in touch with this project in order to provide a valid cvs server support on NT/2000/XP for WinCvs. Check-it out at http://www.cvsnt.org. Initial support for CVSNT-specific features is in WinCvs 1.1b9 and later while recent 1.3.x builds support almost the full featureset.
Where can I find Tutorials or other Getting Started type of material ?
Aside from the on-line help documentation that comes with WinCvs you could check the following links:

Most of the above mentioned docs assume that you are already familiar with CVS itself. Thus before starting with WinCVS (or other GUI clients), for CVS documentation you can check the following links:

What info should I supply when posting about a problem on a support forum (such as the CVSGUI mailing list)?
In order to get the best possible support on your problem, make sure you supply the following:
  • the version of your WinCvs (shown in the About screen)
  • the operating system you're running WinCvs on
  • the type (GNU CVS or CVSNT) and version of CVS server you are trying to connect to (unless you're using :local: mode)
  • the operating system of the machine your CVS server is running on
  • the CVSROOT string you are using to connect including the authentication method/protocol prefix
  • the physical location of your repository
  • the names and versions of any third-party software potentially involved in the problem, e.g. SSH clients/tunnels, Python, TCL, Firewalls, Anti-virus-software, etc.

Never just write "this or that doesn't work". Please describe what you were doing in as much detail as possible. Also tell what you were expecting to happen as a result of your actions and what happened instead. If you get any error messages or other output that might be relevant to the situation, do supply this in full or, if there's any confidential information contained in those messages, at least in as verbose an edited form as possible.

Also make sure you've searched the available archives for possible precedence:
  1. Mailing list archives
  2. NNTP mirror of the mailing list
Now, you are ready to get support (requires registration with Yahoogroups). Good luck!
Using WinCvs
I have got Cygwin 1.5.7 or later installed and WinCvs hangs or crashes right on startup. What should I do?

This is a known issue that is caused by the TCL DLL distributed with Cygwin which also affects a few other Windows applications which attempt to load the TCL interpreter DLL, e.g. WinGaim. Apparently the Cygwin flavour of tcl84.dll depends on the Cygwin environment being loaded as well which is not the case for WinCvs and shouldn't have to be. This causes the host application (in this case WinCvs) to crash or hang while trying to load the DLL. Other than not even trying to load the DLL there isn't really anything sensible that could be done about this from WinCvs' point of view (see below).

The workaround is to make sure that WinCvs either finds a different tcl84.dll first or none at all. This could be accomplished by any of the following:

  • Rearrange your PATH environment variable so a folder that contains a non-Cygwin tcl84.dll (recommended is the one included in the standard Python distribution) comes before the Cygwin one.
  • Uninstall the Tcltk package from your Cygwin installation.
  • Rename or delete the tcl84.dll in your Cygwin bin directory.
  • Remove the Cygwin bin directory from your PATH altogether.

Note that this problem only applies when you have put your Cygwin bin directory on your PATH as that is where WinCvs will by default search for a TCL DLL to use. This could not really be recommended even if this particular issue did not exist (even though it seems that the Cygwin people are actually recommending to do so...). Cygwin effectively creates its own sub-Operating System environment so "letting it out in the open to mix and match" with the Windows-native applications could lead to unpredictable results.

Recent releases of WinCvs have implemented a partial remedy: When a hang or crash occurred while loading DLLs they will detect this and on next startup will offer the option to not load any external DLLs. This will allow users to start WinCvs without crash or hang and then simply go to the preferences to specify a different DLL (on the WinCvs tab of Admin|Preferences.

You can read more about this issue in this thread from the Cygwin mailing list and this report in the CVSGUI bug tracker. Furthermore, the archives of the CVSGUI mailing list are full of posts on the issue as well.

It appears that in WinCvs 1.3.x neither the "RSA private key file (identity)" nor the "Additional SSH options" settings have any effect at all. What's going on?

This is indeed a known legacy issue. WinCvs 1.2 used to use a specially patched version of CVS which read the additional options and the keyfile location from the environment (which is where WinCvs puts those entries). No other cvs.exe acts this way! WinCvs 1.3.x however no longer uses that cvs.exe but a regular CVSNT executable instead. Therefore, as you have found out, the SSH options are not effective when using the out-of-the-box cvs.exe .

The reason why these options still remained on the dialog are A. they were still useful if you downgraded your cvs.exe and B. as you can see in WinCvs 1.3.18 and later the SSH options dialog has by now been completely removed in the course of a major overhaul of the whole CVSROOT and connection setup handling (it has been rewritten almost from scratch - also see here) which rendered an effort to redesign that "doomed" dialog rather pointless.

If you don't want to use the new versions yet the workarounds are to either:

  1. append the additional options directly to the entry given in the field labeled "SSH client" (this does not work for some SSH clients) or
  2. in case you're using PuTTY/Plink you should create a named session for the CVS server in PuTTY first and set all the options there. They will be stored in the registry and will be read by plink.exe when you connect via CVS.
  3. (Instructions for other SSH clients to follow)
I just upgraded to WinCvs 1.3.18 or later and can no longer find a place to enter my CVSROOT. Where has the General tab gone?

The global CVSROOT setting has been removed from WinCvs, mainly because it was pretending to be something which it wasn't, namely a global CVSROOT setting that would automatically apply to all your work within WinCvs. In practice however this setting was silently ignored about 95% of the time, possibly more.

What used to happen when you entered something on the General tab of WinCvs was that it put the value entered there into the CVSROOT environment variable when calling the CVS client. The problem with this is that CVS will only so much as look at this variable if there is absolutely no other way to determine a CVSROOT for the current operation. Most of the time however, there is another place to get this information from, namely the meta information stored within your existing sandbox directories. Also see this FAQ item about changing your CVSROOT which explains about this sandbox meta info.

Now, what was done was move the CVSROOT setting where it would really be honored by CVS, i.e. those commands that (could) work outside of a sandbox context: Init, Import, Login, Checkout and RTag. On the command dialogs for these commands (as well as the Admin|Command Line... dialog) you will find a new setting labeled CVSROOT which will allow you to enter the CVSROOT to use for the current operation. This will end up being passed as an explicit commandline option instead of the rather meaningless CVSROOT environment variable as before. WinCvs will also remember the CVSROOT you used the last time you invoked a particular command in a particular directory so you usually won't have to enter it again on subsequent invokations.

Furthermore, there is a new UI for creating/editing your CVSROOT string, dubbed the "CVSROOT wizard", available by pressing the ellipsis ("...") button right next to abovementioned entry box. This new UI is much more flexible than the old General tab, as it uses meta information supplied by the CVS client itself, e.g. which protocols are supported and which options are expected/allowed by each protocol.

WinCvs tells me
Warning: Using remote (network) drive may cause file system errors and performance decrease
Use local fixed drives for best safety and high performance
What are the reasons for this discouragement?

This is an often discussed issue. Fact is that both CVS(NT) and WinCvs were never built to operate on network shares. There are numerous issues caused by such a setup:

CVS(NT):
bandwidth
all data has to travel twice: once from the server to your machine and back to the machine which holds the sandbox - only the first part of this journey will be compressed (given that you enabled compression in the first place). On some occasions it has to travel even more oftenthan that, as the CVS client will write/rename/copy/delete temporary backup copies of your files to avoid loss of data.
security
only the first part of above-mentioned journey will be encrypted (given that you turned on encryption in the first place).
data integrity
there are close to no built-in precautions to handle network-related loss of data. Also, accessing network shares via CVS from different platforms can seriously mess up your repository as the whole line-ending auto-magic mechanism will simply fall over (it's based on the OS of the machine running the client process not that of the machine holding the sandbox)
accuracy
an often observed problem with Samba-shared sandboxes is that suddenly all files are identified by CVS as locally modified because of a slightly above-average discrepancy between reported timestamps
feasibility
Recently some changes to CVSNT broke the ability to connect to Samba shares for good. Due to all the other issues depicted here this is officially an unsupported configuration and there are therefore no plans to fix it. Put short: You cannot use WinCvs with a recent CVSNT binary to access a Samba share.
support
as mentioned above, accessing network shares via CVS is unsupported, i.e. in case you are experiencing problems with this setup you cannot expect any help from the (Win)CVS(NT) teams unless you could reproduce the same problem with a local sandbox.
WinCvs:
performance
WinCvs uses the standard OS-supplied ShellNotification API to keep its file views up-to-date - for network shares this means that the OS will continually poll the network which on slow or badly configured networks could bring the entire client machine to a grinding halt at times - furthermore it also impacts overall network performance.
Not yet classified topics
I want to add a file to CVS but I get:
cvs add: cannot open CVS/Entries for reading: No such file or directory
cvs [add aborted]: no repository
What's going on ?
CVS needs some context information when adding a file, namely which repository it should add the files to and most of all where in that repository. Therefore, you cannot add a file on its own. You have to add the directory it is located in first. If the parent folder of that directory also isn't in CVS yet you will probably have to add that, too. In general, the Add command works only when invoked somewhere inside a working copy, i.e. if you follow the folder ancestry upwards you should eventually reach one that was once checked out of a CVS repository.
If however your intention is to create a new "root-level" module then you should either use the Import command or apply the technique described here. For a comparison of Import and Add read the "When should I use import instead of add?" topic.
How can I recursively add a complete file/folder hierarchy to CVS ?

Currently such a command does not exist in native CVS. Since WinCvs 1.3.11 however there is a Python macro available captioned Macros|Add|Recursive Add (autocommit)... (or Macros|CVS|Recursive Add (autocommit)... in WinCvs releases 1.3.20 and earlier) which will do the job just fine. Inspired by the native Import dialog it offers to select the keyword substitution mode (e.g. binary/text/unicode) based on file extension. You can also optionally commit the added files in the same step, supplying a log comment along the way.

For older WinCvs releases there also is a TCL macro captioned Add all to Cvs which could be used to accomplish this. The major drawback to this macro is that it can not distinguish between text- and binary files.
Guy Rouillier wrote an alternative TCL-macro which deals with this issue. It is available via the CVSGUI list's Files section. The posts that accompanied this macro could be found here and here.
To access these links you will currently have to be registered with Yahoogroups and subscribed to the CVSGUI mailing list (both free).

When should I use import instead of add? What are the differences ?
Sorry, not yet.
Why do I have to specify the Vendor branch and Release tag on import ? What could/should I do with them ? How do I get rid of them ?
Sorry, not yet. (CVSNT 2.0.11/WinCvs 1.3.14 supports cvs import -n to import without vendor branch and release tag)
How can I add a new root-level module without using the Import command ?

There are various reasons why you might not want to use the Import command (also read here). If you're using a CVSNT server version 2.0.9 or later and a corresponding CVSNT client binary (already bundled with WinCvs 1.3.14 and later) and all you want to avoid is having to specify the Vendor Branch and Release name there's a new option available for the Import command which will allow to import to the trunk without release tag. This option is available from WinCvs 1.3.14 onwards and could be found on the Import dialog labeled Don't create vendor branch or release tags (the corresponding commandline option is -n in case you were wondering).

However, if you're not using a recent CVSNT server or have other reasons for not using the Import command, then you might be interested that since WinCvs 1.3.12 there's a Python macro available via Macros|CVS|Add Root Module... which will take care of this task. If you're still using an older version of WinCvs or simply want to know, here's what you have to do:

  1. If the to-be added files already exist on your machine, change your WinCvs browse location to the parent directory of the one they are in. Otherwise create a new directory anywhere outside any existing sandboxes and change your WinCvs browse location to it.
  2. Bring up the Checkout dialog via Remote|Checkout module...
  3. Enter "." (that is a single period) as the Module name and check the "Do not recurse" option.
  4. Make sure you have the correct CVSROOT set either via the appropriate option or, in older WinCvs releases, on the General tab.
  5. Hit "OK".
  6. If the to-be added files do not yet exist, create a new directory below the one you created in the first step.
  7. Select the new directory in WinCvs.
  8. You should now be able to add the new directory using the Add command. The new directory will be added as a new root-level module.
When I try to lock a file I get:
cvs [admin aborted]: 'admin -l' is a deprecated option.
Use 'edit -c' instead.
What now ?
Sorry, not yet.
What are reserved edits ? How can I use them ?
Sorry, not yet.
When should I use locking / reserved edits and why ?
Sorry, not yet.
WinCvs often hangs when one of my sandboxes is on a remote machine (via UNC or shared drives). What can I do ?

In general, it is not advisable to put sandboxes on remote machines. WinCvs relies on the Windows API to provide a realtime view on the directories it displays. For local drives this works pretty well using a notification scheme but for remote directories the underlying WinAPI falls back to polling the remote machine in regular intervals and thus significantly increases the overall network traffic. Especially for large directories or when you enable the "flat view" this constant polling could slow down WinCvs (and in extreme cases the entire network) beyond use.

What's even more annoying is when for some reason the connection to the remote sandbox fails. In that case you will notice a significant slowdown in all WinCvs operations even when the disconnected sandbox is not the currently selected browse location!

Yet another aspect of the problem occurs when the remote machine isn't even a Windows box but a Samba share on a Linux server. In the latter case, there have also been numerous observations of another variation of the infamous "red-file-phenomenon" because somehow timestamps are off by a few seconds too many.

Here are only some suggestions to overcome such a setup and keep your sandbox files on your local machine:

  • use the Export command to transfer the files to the remote machine before testing there.
  • make use of server-side loginfo or postcommit triggers to automatically export newly committed files to the testing server.
  • write a WinCvs macro which syncs your working files with the testing server with a single mouse-click so you don't have to do this manually.

Note, that only the last option allows you to test files which have not yet been committed.

It's nice that WinCvs remembers all the entries I ever made into a combobox, but how can I purge the by-now obsolete items ?
In recent releases (1.3.x) you could simply press the [DEL] key, when on the item you want to delete. Removing the items from earlier versions requires some registry hacking as described in the following post from Bo Berglund regarding the combobox used for browse locations:
It is a bit tricky since you have to do it in the registry, but if you are willing to do it here is a stepthrough:
0) Close WinCvs if it is running!
1) Open RegEdit and go to HKEY_CURRENT_USER\Software\WinCvs\wincvs\CVS settings
2) open item P_BrowserLocs. It is a set of null terminated strings with the list of locations.
3) In the hex window mark the string you want to delete starting with the drive letter and ending with the NULL char.
4) Hit the delete button.
5) Edit the first byte in the item by decrementing by one (for each string deleted)
6) Click the OK button
7) Start WinCvs again and check that the offending location is gone.

Be careful when editing the registry!

/Bo

The same technique could be applied for several other comboboxes as well. The trick is finding the right value to edit. As most of them are pretty self-explanatory and most of all because this hacking is no longer necessary in recent builds of WinCvs, I'm not going to list them here in detail. If you're stuck with WinCvs 1.2 you'll have to figure out for yourself or ask on the list.
I have changed my username / CVSROOT in the preferences but WinCvs still seems to use the old one. What should I do ?

CVS stores meta information such as the CVSROOT (which includes the username) or the repository module a working directory relates to or the currently checked out branch inside the sandbox itself. You might already have noticed the hidden .\CVS subdirectories that are created below every checked out directory in your sandbox. This is where CVS keeps that meta info.

The problem in your case is that the CVSROOT that was stored in the .\CVS subdirectory when you checked out your sandbox always has precedence over the one that's set in the WinCvs preferences (or the CVSROOT environment variable). Therefore you either have to checkout your repository again or, and this is of course the easier solution, modify the meta info to reflect your new CVSROOT.

As you may have guessed from this lenghty introduction, there is no "native" way of doing so. Since WinCvs 1.3.11 there is a Python macro available via Macros|CVS|Change CVSROOT which can tackle this for you. It will first ask you to confirm (or enter) the old root that you want to change and then ask you for the new CVSROOT. After that just hit OK and all occurrences of the old root will be replaced with the new one.

For older WinCvs versions there also exists a TCL macro called "Change Root" or the slightly more convenient "Change CVSRoot (GUI)". While the latter provides a GUI for entering the new CVSROOT, it is not included in even older releases of WinCvs and there also is a (very) slight chance that it might not work with some versions of TCL. The former requires you to manually insert the new CVSROOT string into the source code of the macro (called ChangeRoot.tcl found in the Macros subdirectory of your WinCvs installation).

Yet another alternative (e.g. in case you don't want to install TCL or Python) is to simply use some search and replace tool. The CVSROOT is stored in all files called "Root" inside said .\CVS subdirectories. Replace it with the new one and you're set.

What CVSROOT settings should I use for my repository ?
Sorry, not yet.
I get the following message:
cvs update: move away MyFile.h; it is in the way
What's going on?
Sorry, not yet.
How am I supposed to manage projects with WinCvs ?
Sorry, not yet. (-> modules)
Can I handle multiple repositories with WinCvs ? How ?

The functionality you are looking for actually is a combination of the two WinCvs features dubbed "Browse Locations" and "Saved Settings". The confusing bit for most of those who ask the above question is that WinCvs tackles the task from the reverse point of view, namely the working copy. As every working copy relates to exactly one repository this really isn't that different a concept at all. In other words, all you have to do is create a working copy, make it known to WinCvs by selecting it as a Browse Location and have it save its settings.

Here's what you have to do:

  1. Invoke the Checkout dialog via Remote|Checkout module.
  2. Enter the name of the module to checkout or "." if you want to check out the complete repository.
  3. Enter the checkout target directory. This will be the root of your new working copy.
  4. Specify the correct CVSROOT, either using the appropriate option or, in older WinCvs releases, the "General" tab.
  5. If necessary, set any other checkout options, e.g. enter a branch name.
  6. Press OK.
  7. Now, change your "Browse Location" to the directory you entered in 3. You can do so either via View|Browse Location|Change... or the button with the two little folder icons right next to the Browse Location combobox on the toolbar.
  8. If this is the first time you have chosen that directory as a Browse Location you might at this point be presented with a dialog titled "Save settings". The name for the Saved Settings is pretty irrelevant as it is only used to generate the file name for the settings file. You will never be confronted with it again when using WinCvs. There is also no existing setting to copy the new one from, so you could just hit OK.
    If the dialog does not pop up automatically, you could also invoke it manually via View|Browse Location|Save Settings...
  9. That was it really. From now on, WinCvs will remember all the preferences you make while working with this specific sandbox, i.e. whenever you make it the active Browse Location WinCvs will restore them.
ActiveTCL is properly installed but WinCvs 1.2 still says TCL not available . What now ?
Originally TCL was distributed by an organisation named Scriptics and that is what WinCvs 1.2 is looking for. Since the release of WinCvs 1.2 TCL has been taken over by ActiveState and is no longer available via Scriptics. Therefore you have to apply some trickstery to get WinCvs 1.2 working with the ActiveState distribution of TCL, namely create the following registry key and have it point to your TCL installation directory:

HKLM\Software\Scriptics\TCL\8.3\Root

What are Python and/or TCL needed for ? Do I really need to install both ?

First off: There's no implicit requirement at all to install either TCL or Python in order to run WinCvs. Early Python-enabled builds (WinCvs 1.3.4 up to and including 1.3.6) however crashed on startup without Python when being installed freshly (i.e. not over an existing previous version). This could be worked around by copying the registry settings of an older WinCvs installation before starting up. It is however not recommended to use these outdated builds anyway.

Now for the beef: TCL and Python are used to extend WinCvs by ways of macros. WinCvs versions before 1.3.4 used TCL for this only. From that version onwards the preferred macro language has become Python and as a result TCL macros are internally only supported via Python wrappers, i.e. you will have to have Python installed in order to be able to run TCL macros. Since WinCvs 1.3.11 it is however no longer necessary to perform a separate installation of TCL as from that version on, WinCvs is capable of utilizing the TCL-interpreter that comes bundled with the standard Python distribution (given you didn't uncheck "TCL/Tk" when you installed Python). The only exception is when you are intending to write your own TCL macros and want to use packages that are not part of the Python distribution. In that case you will still need to install TCL separately.

Once you've got the appropriate scripting language(s) for your version of WinCvs installed, macros should become available below the top-level Macros menu and the Admin|Macros admin submenu (also read this FAQ item about a common TCL installation problem). Macros in the Macros menu usually work on the active file or folder selection while the macros in the Admin|Macros admin submenu perform more global operations, such as displaying CVS version information or listing the contents of the current repository's modules file.

Currently TCL also serves one additional purpose on top of mere scripting support: Without TCL you would not be able to execute CVS commands from WinCvs' console pane (also see this related item) .

Now, if you're still somewhat reserved against installing an additional scripting engine, consider these two points:

  • Judging by what has been stated by the development team in the past, the WinCvs executable will always be a mere GUI frontend for the commandline client, i.e. without the macros it will most likely always require the same number of steps to do anything regardless of whether you use the GUI or the commandline client (although these steps should of course be easier and quicker to take when using the GUI).
    All functionality that would require more than a single CVS command invokation will most likely never be implemented in the main executable but only via macros. Once you start using CVS for everyday work you will see that there are quite a lot of routine tasks that will fall into this category.
  • Most modern applications support scripting in one form or another (think of VBA, JScript et al.). As the CVSGUI project, which WinCvs belongs to, is a cross-platform effort they had to choose a scripting solution that was also cross-platform. Therefore native Windows-scripting/automation was out of the equation. IMHO Python has been an exceptionally good choice in this respect. It's a very powerful state-of-the-art object-oriented language which is also quite easy to jump into.
My files are always displayed as modified although they're not - even after commit. What's going on ?
There are currently two known situations where this occurs:

The first and most common one is related to a bug in the stat WinAPI which will report the wrong timestamp for a file on an NTFS partition during Daylight Saving Time (DST). WinCvs 1.3.x and later implement a workaround to this OS bug. This has the side-effect that the problem also occurs when you upgrade from WinCvs 1.2 to 1.3.x. For this specific situation there is a Python macro written by Johnathan M. Gilligan available via Macros|Search|Fix red icon for '<selection>'.

To work around the problem in WinCvs 1.2 and earlier it is usually sufficient to run a Status or Update on your sandboxes everytime the DST change takes place. If this does not work, you will either have to do a clean checkout or write a script/program that syncs the timestamps in the ./CVS/Entries files with the timestamps reported by the operating system, which is what Johnathan's Python macro does.

For more detailed information on the DST problem and some more possible remedies as well as the "official Red Icon FAQ" please refer to DevGuy's CVS Information page.
For those interested, Johnathan has also written an even more detailed article about the DST bug for The Code Project without the specific focus on CVS.

The other known situation where the "red file phenomenon" occurs is when the sandbox is on a remote machine accessed via a network share, most notably a Samba share on a *ix box. There is currently no known workaround to this situation apart from moving your sandbox to your local machine which is strongly advisable anyway (also read "WinCvs often hangs when one of my sandboxes is on a remote machine...").

I cannot see any of the files in my sandbox unless I modify them. What the heck is going on ?
The most common cause for this problem are accidentally activated view filters. The filters could be manipulated either via View|File Filter>... or the respective toolbar buttons. Just make sure that all filters are deactivated. There have been quite few reports where the filters were all initially activated after a fresh install for a yet unresolved reason. The effect of this is that you only see committable, missing, unknown and ignored files, but no regular, unmodified CVS files.
For a detailed explanation of the filters, read "How am I supposed to use the file filters ?".
How am I supposed to use the file filters ?

Filters are unfortunately often a source of confusion for many people who are just getting started with WinCvs. Click at the buttons in the screenshot below to get a detailed description of what each filter does and you will see that it really isn't as complicated as it may seem at first:

WinCvs 1.3.14 and later:
Filter toolbar

WinCvs 1.3.12 and earlier:
Filter toolbar in WinCvs 1.3.12 and earlier

The default state, i.e. when no filters are activated (as displayed above), is to show all files except ignored files and folders.

Flat Mode
This is not exactly a filter but it is definitely of most use in combination with filters. Flat mode lets you see all files inside and below the selected directory at once. Folders are not displayed in this mode. Instead there is an additional column "Path" which displays the path information for each file relative to the selected root folder.
A very common task where this could be used is to quickly locate modified/committable files within your project. To do so, you would first(!) activate the Show Committable filter, then change into the root directory of your project and then switch to Flat Mode and voilà: You will now have a list of all the committable files in your project.
You should always take care of the order in which you operate filters and the Flat Mode. You should usually never activate Flat Mode without having set a filter first. Otherwise it might well take some considerable time for WinCvs to assemble the list of all files below the selected directory.
File Mask(s)
This combobox allows you to enter file masks using wildcards, such as*.pas;*.dp? (separate multiple masks with semicolons). After you entered them press the Return key to activate the filter mask. The combobox will keep a history list of all filter masks you enter during a WinCvs session, so you will not have to enter them once more if you need them again later.
To deactivate the filter again for the first time you have to manually delete the current entry character by character using the Backspace key and then press Return again. Later on you could simply select this empty entry from the history dropdown. It has also been observed that you sometimes need to refresh the display to make a changed mask filter take effect. Both this and the issue about deactivating the mask filter has been fixed in later WinCvs versions.
The file mask filter could be combined with all other filters.
Enable Filter Bar
Activating this button displays and enables the so-called "Filter Bar" which is the successor to the Filter Mask(s). It allows not only to use masks on file names but on any column that WinCvs could display. Once activated each column header will be enhanced with a small entry field which you could use to enter wildcard masks into. The view will immediately be filtered to entries matching the given masks. You could filter as many columns as you like.
The filter bar could be combined with all other filters.
Clear Filter Bar
This is a single-click shortcut for clearing all masks in the Filter Bar. It is only enabled when at least one filter mask is currently active.
Clear All Filters
This is a single-click shortcut for turning off all filters (apart from the File Mask or Filter bar filters) that have been activated. It is therefore only enabled when at least one of those filters is currently active.
Show Committable
This is a shortcut for manipulating the following four items (i.e. Show Changed, Show Added, Show Removed and Show Conflicts) in unison, i.e. it has the same effect as individually toggling the state of those four filters manually.
This filter could be combined with all other filters except Hide Unknown, which is implicitly activated with this filter unless Show Unknown is activated as well.
Show Changed
When activated on its own this filter will show only files that have been locally modified. When combined with other filters it will show these files in addition to those made visible by the other filters.
This filter could be combined with all other filters except Hide Unknown, which is implicitly activated with this filter unless Show Unknown is activated as well.
Show Added
When activated on its own this filter will show only files that have been recently added using the Add command but were not yet committed. When combined with other filters it will show these files in addition to those made visible by the other filters.
This filter could be combined with all other filters except Hide Unknown, which is implicitly activated with this filter unless Show Unknown is activated as well.
Show Removed
When activated on its own this filter will show only files that have been recently removed using the Remove command but were not yet committed. When combined with other filters it will show these files in addition to those made visible by the other filters.
This filter could be combined with all other filters except Hide Unknown, which is implicitly activated with this filter unless Show Unknown is activated as well.
Show Conflicts
When activated on its own this filter will show only files that reported conflicts during the last update (regardless of whether they have been manually resolved already or not). When combined with other filters it will show these files in addition to those made visible by the other filters.
This filter could be combined with all other filters except Hide Unknown, which is implicitly activated with this filter unless Show Unknown is activated as well.
Show Missing
When activated on its own this filter will show only files that have been deleted from the local file system but are still known to CVS. When combined with other filters it will show these files in addition to those made visible by the other filters.
This filter could be combined with all other filters except Hide Unknown, which is implicitly activated with this filter unless Show Unknown is activated as well.
Hide Missing
This filter only has any perceivable effect at all when activated on it's own. When activated it hides all missing files from the current view. Except for Show Ignored and (obviously) Show Missing, all other filters implicitly activate this filter as well.
Show Unknown
When activated on its own this filter will show only non-CVS files (but no ignored files!). When combined with other filters it will show these files in addition to those made visible by the other filters.
This filter could be combined with all other filters except, quite obviously, Hide Unknown.
Hide Unknown
This filter only has any perceivable effect at all when activated on it's own. When activated it hides all unknown and ignored(!) files from the current view. Except for Show Ignored and (obviously) Show Unknown, all other filters implicitly activate this filter as well.
Show Ignored
This filter is special in several ways:
  • Unlike the other filters, Show Ignored does not limit the view to only show the files it filters. As ignored files are hidden by default, you have to activate this filter to see them at all in the first place.
  • It is the only filter that does not only affect files but also folders. By deactivating Show Ignored ignored folders will be hidden from view as well as ignored files.
  • As ignored files are intrinsically also Unknown files you have to explicitly activate Show Unknown as well when combining this filter with any of the other filters. This also means that there is currently no way to see only ignored files. You will always see Unknown files, too.

For more information on how to ignore files or folders please refer to the Cederqvist or the WinCvs online help.

You might find some of this behaviour inconsistent and maybe confusing at first but over time you will probably discover that this design really allows for very efficient work indeed. It was obviously designed with the most common tasks in mind rather than behavioural consistency. If you're still doubtful, try to think of a more consistent design and then use it to play through some common tasks, such as locating committable files or hiding all unknown files and making them visible again. My personal experience is that the current filters allow me to accomplish these tasks much faster than any of the "better designed" setups I came up with so far.

What exactly is a Sandbox, a Working Copy or, while we're at it, a Browse Location ?

Often these terms are used interchangeably. There are however some subtle differences. Both a sandbox and a working copy are usually the result of a checkout operation. They identify a local copy of files from the repository which you could work on, hence "working copy". Also, the term "Sandbox" usually refers to the complete checked out folder hierarchy, while there could well be a "working copy" of an individual file.

A Browse Location could be virtually identical to a sandbox. This is not a requirement however. In contrast to the two terms described above, Browse Location is not a CVS term, but one specific to WinCvs. It really describes the currently selected root element of the folder view (the one labeled "Modules"). This view could in theory be composed of many different sandboxes or none at all. There are some special semantics related to Browse Locations, namely Saved Settings.
Most of the settings you could make under Admin|Preferences could be bound to a specific Browse Location via View|Browse Location>Save Settings.... Whenever you switch Browse Locations, settings previously saved for that location will be restored (also read "Can I handle multiple repositories...").
To define a new Browse Location, use either the "Change location" speedbutton ("binoculars" icon in WinCvs 1.2, "two folders" icon in WinCvs 1.3.x) or the View|Browse Location|Change... menu item. Once defined you could easily switch between Browse Locations using the combo box right next to the Update/Commit buttons.

How can I revert changes, i.e. return to a previous revision and continue development based on it ?
The easiest way to do this is described in Karl Fogel's CVS Book. Let me paraphrase the steps for the GUI environment of WinCvs:
  1. Select the file(s) or module(s) you want to revert in the file view
  2. Invoke the Update dialog.
  3. Activate the Merge options tab.
  4. Choose Merge Type "Merge with differences between two rev./tags" and enter the revision number or tag of the latest revision on the current branch into the first entry field (if you're still using WinCvs 1.3.18 or earlier, enter this into the field labeled Only this rev./tag).
    For simplicity you could just use HEAD instead of the actual revision number if you are working on the trunk or the respective branch tag if you're working on a branch.
  5. Enter the revision number or tag of the revision you want to revert into the second entry (Plus with this rev./tag in WinCvs 1.3.18 and earlier).
  6. Hit "OK"
You should now have your files ready to be committed as new revisions whose contents are identical to the revisions you reverted to.
How can I resurrect a file that was removed using cvs remove ?

Spoken from a technical level, resurrecting a file is nothing else than "reverting" to the last revision known to be alive. There's a catch however, which stops us from simply reusing the technique detailed in the previous item: The file(s) we want to revert could not be selected, as they do not exist in our sandbox.

Since WinCvs 1.3.11 there is a Python macro available via Macros|CVS|Resurrect File which will take care of this. Just select the directory the file was in, run the macro and enter the file name. This will even work on branches if the complete directory is checked out on that branch.

For older WinCvs versions you have to fall back to the commandline procedure of reverting as described by Fogel. All you need to know is the name of the file and the revision number of the last "live" revision. If you don't know the latter you could query for it using the Log command, i.e. cvs log -N filename . Once you've got that revision number, switch to the directory where you want to resurrect the file and enter the following on the console:

cvs update -jdeadrevision -jaliverevision filename

Deadrevision in this case identifies the latest revision on the current branch (i.e. the "dead" one). As with reverting, you could use HEAD or the respective branch tag as a placeholder here.

What does the "P" in the output of Update mean ?
It means "Patched", which in effect is exactly the same as "Updated". The only difference is that the server did not send the complete file but only a diff (aka patch). All of the letters used in the Update output are explained in detail here.
How can I have automatic mail notification on Commit ?
Sorry, not yet. (See CVSNT Third Party Tools page)
How can I see what's in the repository ?

Standard CVS does not provide a mechansim to really "browse" the repository like many other VCS's do. CVSNT introduced the ls command however, which you could use to explore the repository in a similar way as you would a local file system. The recent builds of WinCvs (1.3.9 and later) introduced a GUI to this command, which is available via a Browse button, everywhere a module name needs to be entered. Note that this will only work against a CVSNT server!

Since WinCvs 1.3.11 there is also a very simple macro available via Admin|Admin macros|List Module Contents... which emulates CVSNT's ls command for servers that do not natively support it using quite a dirty hack involving faking CVS meta data on-the-fly and non-recursive checkouts with the global -n option. It is currently not especially user-friendly (yet) however.

A slightly more usable macro based on the same algorithm is included as of WinCvs 1.3.14 via Admin|Admin macros|Browse Repository Folders.... This one presents the repository contents in a list box control and allows to "drill down" into sub-modules by double-clicking entries. It also provides rudimentary Checkout functionality. It could however not display repository files and it also could not filter the output by tags or branches like the former macro does.

Alternatively there are web-based solutions, like ViewCVS and the nowadays commercial CVSWeb which require a http-server and some scripts to be installed at the server.

The recommended practice however is to set up the modules file. This is tedious work which has to be done manually but allows for flexible workflow management.

When I run the "List modules on server" / "Get cvs modules" macro, nothing happens. Is it broken ?

No, it's not. These two macros are easily overrated. All they do in effect is beautify the output of cvs checkout -c, which in turn simply strips the comments from the repository's modules file and dumps the remaining lines in alphabetical order. This file has to be maintained manually by the repository's admin however. Unfortunately many admins don't bother to do so, so that's very probably the reason, why "nothing happens" in your case.

You might want to take a look at the previous item "How can I see what's in the repository?" which is probably closer to what you're looking for.

Can WinCvs do visual diffs ? How ?

WinCvs itself cannot do visual diffs. It is however possible to use an external diff program. A few are listed on the CVSGUI homepage. Look for the "File comparison and merge tools" section near the bottom of the page.

Once you have chosen and installed a diff program just go to Admin|Preferences/WinCvs and enter it as the "External diff program". Now the next time you invoke Diff selection, just tick the Use the external diff checkbox (This setting will be remembered, so you don't have to check it again).

How can I really delete a revision ?
Sorry, not yet. (cvs admin -o)
I accidentally checked in garbage and want to hush it up. Should I consult an expert from the NSA for advice on such matters ?
Sorry, not yet. (cvs admin -o)
Is there a GUI to the cvs admin -o command ? Where ?

Yes, there is. It's available via the Graph's context menu. Just select a file, invoke Graph Selection, select one or more revisions in the Graph view and look for Admin>Delete revisions on the right-click menu.

Note that with most CVS servers you could only execute admin commands if you've got administrative privileges on the repository. See your server's docs on how to configure this as the methodology may vary slightly.

How is the modules file supposed to be used ?
Sorry, not yet. (see modules and modules2 documentation)
When and how should I use branches ?
Sorry, not yet.
How do I tell when a specific tag was set on a module or file ?
The only timestamped record of a tagging operation could be found in the repository's history file, which could be queried using the cvs history command. There's some major drawbacks to this technique however:
  • Only tags set using the cvs rtag command (aka Remote|Create a tag by module...) are logged in the history file. Tags which were set using Modify|Create a tag on selection... are not traceable via the history command.
  • The history file could get quite large, so the administrator of the repository server might decide to purge it from time to time.
  • Server-side logging could optionally be disabled altogether.
Why can't I see merges in the Graph view ?
Standard CVS keeps no record of merging operations hence it could not be visualized. However, CVSNT introduced the concept of "mergepoints", which could be used to do just that. From WinCvs 1.3.15 onwards you are able to see merge operations visualized in the Graph View by an arrow connecting the source and target of the merge. Note however that both client and server have to be using at least CVSNT 1.11.1.3b68 for this work and even then only merges done after the upgrade could be visualized.
When I try to execute commands from WinCvs' console view, I get this:
Traceback (most recent call last):
File "<string>", line 1, in ?
NameError: name 'cvs' is not defined
What have I done wrong ?
The WinCvs console could be toggled between Python and TCL. To be able to enter commands as you would on a command prompt, you have to switch the shell to TCL via Edit|Shell>TCL.
In theory CVS commands could be run from the Python shell as well by typing stuff like
import cvsgui.Cvs; cvsgui.Cvs.Cvs().Run( '-q', 'status')
but this is obviously quite tiresome...
Whenever I merge a branch more than once I always have to resolve a lot of conflicts. Could I somehow avoid this ?
Sorry, not yet. (see the Cedeqvist; no longer applies to recent CVSNT servers that support mergepoints)
I cannot commit my changes. CVS tells me:
cvs commit: sticky tag `someTag' for file `blah.txt' is not a branch
What now ?
You have previously updated or checked out the file or module in question using a so called "sticky tag". This happens when you use any of the options found either on the "Sticky options" tab of the Update dialog or the "Checkout options" tab of the Checkout dialog. The only kind of sticky tag that allows you to commit changes based on it is a branch tag (hence the message). Otherwise you will first have to undo the sticky tag. There are several different scenarios for this:
  • The revision you based your modifications on is on the tip of the trunk. This is the easiest case. All you have to do is run the Update command with the "Reset any sticky date/tag/'-k' options" option (aka cvs update -A) turned on. After this you will be able to commit again.
  • The revision you based your modifications on is outdated (i.e. someone else has already committed a newer revision). In this case you have to chose whether you first want to merge in the newer changes (and maybe resolve conflicts produced by this) before committing your own changes on top of these or whether you want your changes to live on on a branch of their own, effectively forking the development.
    In the former case you could simply follow the instructions from the first scenario. The merging will happen when you remove the sticky tag.
    In the latter case instead of resetting the sticky tag you will first have to create the new branch and then update to that new branch before you could commit.
  • The revision you based your modifications on is already on a branch. The steps for this scenario are very similar to the ones above. The only difference is that instead of removing the sticky tags altogether you update to a different one, namely that of the branch your base revision resides on.
I have tagged a file / module but the tag isn't displayed in the "Tag" column. Is this a bug ?
No, the "Tag" column really displays the "sticky tag" of a checked out revision, i.e. your new tag will only show up in that column if you actually make it sticky by specifying it on the "Sticky Options" tab of the Update dialog. However, if you want to do development based on that revision you should not do this (also see "I cannot commit my changes...") unless your tag is really a branch tag.
WinCvs 1.3.14 and later include two macros called Macros|CVS|Tag and Update and Macros|CVS|Branch and Update respectively which will perform the branch/tag operation and the following update to the new tag/branch in a single step.
How can I rename a tag ?
There is no native command for renaming tags. You therefore have to first place the new tag on all files that carry the old tag and then remove the old tag. To put down the new tag, use the Remote|Create a tag by module... menu item and enter the new tag name and the module to apply to on the first tab and the old tag name on the "RTag options" tab under "Rev./tag/branch". Once the new tag is set, you could use Remote|Delete a tag to remove the old tag.

That's all folks. If you have comments or suggestions email CvsGui mailing list.
$Date: 2005/03/09 23:10:08 $