When you are in a directory that is contained in the CVS repository, a file status will be shown by an icon next to each file. Checking the "Status Column" option causes the status to be displayed in text in its own column. The various statuses that can be shown are:

Up-to-date

The file is up to date with respect to the repository.

Locally Modified

The file has been modified in the current directory since being checked out of the repository.

Locally Added

The file has been added to the repository. This file will become permanent in the repository once a commit is made.

Locally Removed

You have removed the file with remove, and not yet committed your changes.

Needs Checkout

Someone else has committed a newer revision to the repository. The name is slightly misleading; you will ordinarily use update rather than checkout to get that newer revision.

Needs Patch

Like Needs Checkout, but the CVS server will send a patch rather than the entire file. Sending a patch or sending an entire file accomplishes the same thing.

Needs Merge

Someone else has committed a newer revision to the repository, and you have also made modifications to the file.

Unresolved Conflict

This is like Locally Modified, except that a previous update command gave a conflict. You need to resolve the conflict before checking in.

?

The file is not contained in the repository. You may need to add the file to the repository by pressing the "Add" button.

[directory:CVS]

The file is a directory which has been checked out from the CVS repository.

[directory:RCS]

The file is a directory which is maintained using RCS.

[directory:SCCS]

The file is a directory which is maintained using SCCS.

[directory]

The file is a directory.

If the option cvscfg(econtrol) has been set then an extra column will appear in the current directory display labeled "editors". This gives the edit status of each of the files in the current directory so it can be easily seen who is currently editing the file. Refer to the CVS documentation for details of how to set up the repository for using the "cvs edit" feature using "cvs watch on", etc.

You can specify file matching patterns to instruct TkCVS which files you wish to see. You can also specify patterns telling it which files to remove when you press the "Clean" button or select the File->Cleanup menu item.

"Hide" works exactly the way a .cvsignore file works. That is, it causes non-CVS files with the pattern to be ignored. It's meant for hiding .o files and such. Any file under CVS control will be listed anyway.

"Show" is the inverse. It hides non-CVS files except for those with the pattern.

The big button at the upper right opens the module browser.

Module Browse:

Opens a module browser window. PUSH THIS BUTTON! The module browser is useful and will teach you all kinds of things about CVS.

Go Up:

The button to the left of the entry that shows the current directory. Press it and you go up one level.

There are a number of buttons at the bottom of the window. Pressing on one of these causes the following actions:

Delete:

Press this button to delete the selected files. The files will not be removed from the repository. To remove the files from the repository as well as delete them, press the "Remove" button instead.

New Folder:

Creates a plain directory.

Edit:

Press this button to load the selected files in to an appropriate editor.

View:

Press this button to view the selected files in a Tk text window. This may be a lot faster then Edit, if your preferred editor is xemacs or something of that magnitude.

Refresh:

Press this button to re-read the current directory, in case the status of some files may have changed.

Status Check:

Shows, in a searchable text window, the status of all the files. By default, it is recursive and lists unknown (?) files. These can be changed in the Options menu.

Log (Branch) Browse:

This button will bring up the log browser window for each of the selected files in the window. This window is described later.

Directory Branch Browse:

Chooses a "representative" file in the current directory and diagrams only the branch tags. Useful for batch merging.

Diff:

This compares the selected files with the equivalent files in the repository. A separate program called "TkDiff" (also supplied with TkCVS) is used to do this. For more information on TkDiff, see TkDiff's help menu.

Merge Conflict:

If a file's status says "Needs Merge", "Conflict", or is marked with a "C" in CVS Check, there was a difference which CVS needs help to reconcile. This button invokes TkDiff with the -conflict option, opening a merge window to help you merge the differences.

Update:

This updates your sandbox directory with any changes committed to the repository by other developers.

Check In:

This button commits your changes to the repository. This includes adding new files and removing deleted files. When you press this button, a dialog will appear asking you for the version number of the files you want to commit, and a comment. You need only enter a version number if you want to bring the files in the repository up to the next major version number. For example, if a file is version 1.10, and you do not enter a version number, it will be checked in as version 1.11. If you enter the version number 3, then it will be checked in as version 3.0 instead. It is usually better to use symbolic tags for that purpose. If you use rcsinfo to supply a template for the comment, you must use an external editor. Set cvscfg(use_cvseditor) to do this.

Update with Options:

Allows you to update from a different branch, with a tag, with empty directories, and so on.

Add Files:

Press this button when you want to add new files to the repository. You must create the file before adding it to the repository. To add some files, select them and press the Add Files button. The files that you have added to the repository will be committed next time you press the Check In button. It is not recursive. Use the menu CVS -> Add Recursively for that.

Remove:

This button will remove files. To remove files, select them and press the Remove button. The files will disappear from the directory, and will be removed from the repository next time you press the Check In button. It is not recursive. Use the menu CVS -> Remove Recursively for that.

Tag:

This button will tag the selected files. The -F (force) option will move the tag if it already exists on the file.

Branch Tag:

This button will tag the selected files, creating a branch. The -F (force) option will move the tag if it already exists on the file.

Set Edit Flag:

This button sets the edit flag on the selected files, enabling other developers to see that you are currently editing those files (See "cvs edit" in the CVS documentation).

Reset Edit Flag:

This button resets the edit flag on the selected files, enabling other developers to see that you are no longer editing those files (See "cvs edit" in the CVS documentation). As the current version of cvs waits on a prompt for "cvs unedit" if changes have been made to the file in question (to ask if you want to revert the changes to the current revision), the current action of tkcvs is to abort the unedit (by piping in nothing to stdin). Therefore, to lose the changes and revert to the current revision, it is necessary to delete the file and do an update (this will also clear the edit flag). To keep the changes, make a copy of the file, delete the original, update, and then move the saved copy back to the original filename.

Close:

Press this button to close the Current Directory Browser. If no other windows are open, TkCVS exits.

The log browser window has three components. These are the file name and version information section at the top, the log display in the middle, and a row of buttons along the bottom.

The main log display is fairly self explanatory. It shows a group of boxes connected by lines indicating the main trunk of the file development (on the left hand side) and any branches that the file has (which spread out to the right of the main trunk).

Each box contains the version number, author of the version, and other information determined by the menu View -> Revision Layout.

Once a file is loaded into the log browser, up to two version numbers may be selected. The primary version (Version A) is selected by clicking the left mouse button on a version box in the main log display.

The secondary version (Version B) is selected by clicking the right mouse button on a version box in the main log display.

Operations such as "View" and "Merge Branch to Current" always operate only on the primary version selected.

Operations such as "Diff" and "Merge Changes to Current" require two versions to be selected.

The log browser contains the following buttons:

Refresh:

Re-reads the revision history of the file.

View:

Pressing this button displays a Tk text window containing the primary version of the file.

Diff:

Pressing this button runs the "tkdiff" program to display the differences between version A and version B.

Merge to Current:

To use this button, first select a branch version of the file as the primary version. The changes made along the branch up to that version will then be merged into the current version, and stored in the current directory. The version of the file in the current directory will be auto-merged, but no commit will occur. Then you inspect the merged files, correct any conflicts which may occur, and commit when you are satisfied. Optionally, TkCVS will tag the version that the merge is from. It suggests a tag of the form "mergefrom_<rev>_date." If you use this auto-tagging function, another dialog containing a suggested tag for the merged-to version will appear. You can leave the dialog up until you are finished, and copy-and-paste the suggested tag into the "Tag" dialog. It is a good practice to use these tags when doing merges.

Merge Changes to Current:

To use this button, first select two versions anywhere in the file log (although two adjacent branch versions are more commonly selected). It is expected that in most cases version B will be later than version A. CVS will then calculate the changes made between the two versions selected and merge the differences to the current version. Note that if version A is later (higher on the trunk or further along the branch) than version B, a "reverse diff" will be created. This will have the effect of removing the changes from the current version. For example, if the current version is 1.6, version A is 1.5, and version B is 1.3, this button will remove all of the changes made between versions 1.3 and 1.5 from the current version. It may not make sense to select two branch versions on different branches for this function. Optional tagging of the merged-from and merged-to revisions is the same as for the "Merge to Current" function.

View Tags:

This button lists all the tags applied to the file in a searchable text window.

Close:

This button closes the Log Browser. If no other windows are open, TkCVS exits.

You can tag particular versions of a module or file in the repository, with plain or branch tags, without having the module checked out.

Once a software release has been tagged, you can use a special type of check out called an export. This allows you to more cleanly check out files from the repository, without all of the administrivia that CVS needs to have while working on the files. It is useful for delivery of a software release to a customer.

TkCVS contains a special dialog to allow users to import new files into the repository. New modules can be assigned places within the repository, as well as descriptive names (so that other people know what they are for).

When the browser is displayed, it shows two columns. The first column is a tree showing the module codes and directory names of all of the items in the repository. The icon shows whether the item is a directory (which may contain other directories or modules), or whether it is a module (which may be checked out from TkCVS). It is possible for an item to be both a module and a directory. If it has a red ball on it, you can check it out. If it shows a plain folder icon, you have to open the folder to get to the items that you can check out.

To select a module, click on it with the left mouse button. Only one module can be selected at a time. To clear the selection, click on the item again or click in an empty area of the module column.

The second column shows descriptive titles of the items in the repository, if you have added descriptions to the modules file with the #M syntax.

The module browser contains the following buttons:

Who:

Shows which modules are checked out by whom.

Import:

This item will import the contents of the current directory (the one shown in the Current Directory Display) into the repository as a module. See the section titled Importing for more information.

File Browse:

Displays a list of the selected module's files. From the file list, you can view the file, browse its revision history, or see a list of its tags.

Check Out:

Checks out the current version of a module. A dialog allows you to specify a tag, change the destination, and so on.

Export:

Exports the current version of a module. A dialog allows you to specify a tag, change the destination, and so on. Export is similar to check-out, except exported directories do not contain the CVS or administrative directories, and are therefore cleaner (but cannot be used for checking files back in to the repository). You must supply a tag name when you are exporting a module to make sure you can reproduce the exported files at a later date.

Tag:

This button tags an entire module.

Branch Tag:

This creates a branch of a module by giving it a branch tag.

Patch Summary:

This item displays a short summary of the differences between two versions of a module.

Create Patch File:

This item creates a Larry Wall format patch(1) file of the module selected.

Close:

This button closes the Module Browser. If no other windows are open, TkCVS exits.

cvscfg(startwindow)

Which window you want to see on startup. (workdir or module)

cvscfg(cvsroot)

If set, it overrides the CVSROOT environment variable.

Most colors and fonts can be customized by using the options database. For example, you can add lines like these to your .tkcvs file:

option add *Canvas.background #c3c3c3 option add *Menu.background #c3c3c3 option add *selectColor #ffec8b option add *Text.background gray92 option add *Entry.background gray92 option add *Listbox.background gray92 option add *ToolTip.background LightGoldenrod1 option add *ToolTip.foreground black

cvscfg(colourA) cvscfg(colourB)

Hilight colours for revision-log boxes

cvscfg(tagdepth)

Number of tags you want to see for each revision on the branching diagram before it says "more..." and offers a pop-up to show the rest

cvscfg(tagcolour,tagstring)

Colors for marking tags. For example: set cvscfg(tagcolour,tkcvs_r6) Purple

cvscfg(aliasfolder)

In the module browser, if true this will cause the alias modules to be grouped in one folder. Cleans up clutter if there are a lot of aliases.

cvscfg(allfiles)

Set this to false to see normal files only in the directory browser. Set it to true to see all files including hidden files.

cvscfg(auto_status)

Set the default for automatic status-refresh of a CVS controlled directory. Automatic updates are done when a directory is entered and after some operations.

cvscfg(auto_tag)

Whether to tag the merged-from revision when using TkCVS to merge different revisions of files by default. A dialog still lets you change your mind, regardless of the default.

cvscfg(checkrecursive)

Report Check recursively (onvalue {}, offvalue -l)

cvscfg(confirm_prompt)

Ask for confirmation before performing an operation(true or false)

cvscfg(dateformat)

Format for the date string shown in the "Date" column, for example "%Y/%m/%d %H:%M"

cvscfg(econtrol)

Set this to true to turn on an extra column in the directory browser showing the current editors of each file. Set to false to turn off this feature.

cvscfg(editor)

Preferred default editor

cvscfg(editors)

String pairs giving the editor-command and string-match-pattern, for deciding which editor to use

cvscfg(editorargs)

Command-line arguments to send to the default editing program.

cvscfg(ldetail)

Detail level for status reports (latest, summary, verbose)

cvscfg(mergetoformat)

cvscfg(mergefromformat)

Format for mergeto- and mergefrom- tags. The _BRANCH_ part must be left as-is, but you can change the prefix and the date format, for example "mergeto_BRANCH_%d%b%y". The date format must be the same for both. CVS rule: a tag must not contain the characters `$,.:;@'

cvscfg(rdetail)

Detail for repository and workdir reports (terse, summary, verbose)

cvscfg(recurse)

Whether reports are recursive (true or false)

cvscfg(savelines)

How many lines to keep in the trace window

cvscfg(status_filter)

Filter out unknown files (status "?") from CVS Check and CVS Update reports.

cvscfg(use_cvseditor)

Let CVS invoke an editor for commit log messages rather than having tkcvs use its own input box.

cvscfg(file_filter)

Pattern for which files to list. Empty string is equivalent to the entire directory (minus hidden files)

cvscfg(ignore_file_filter)

Pattern used in the workdir filter for files to be ignored

cvscfg(clean_these)

Pattern to be used for cleaning a directory (removing unwanted files)

cvscfg(print_cmd)

System command used for printing. lpr, enscript -Ghr, etc)

cvscfg(shell)

What you want to happen when you ask for a shell

cvscfg(terminal)

Command prefix to use to run something in a terminal window

cvscfg(aster)

File mask for all files (* for Unix, *.* for windows)

cvscfg(n)

The null device. /dev/null for Unix, nul for windows

cvscfg(tkdiff)

How to start tkdiff. Example sh /usr/local/bin/tkdiff

cvscfg(tmpdir)

Directory in which to do behind-the-scenes checkouts. Usually /tmp or /var/tmp)

cvscfg(log_classes)

For debugging: C=CVS commands, E=CVS stderr output, F=File creation/deletion, T=Function entry/exit tracing, D=Debugging

cvscfg(logging)

Logging (debugging) on or off

Setting a variable with this name to a value like "commandname" causes the CVS command "cvs commandname" to be run when this menu option is selected. For example, the following line:

set cvsmenu(update_A) "update -A"

Causes a new menu option titled "update_A" to be added to the user defined menu that will run the command "cvs update -A" on the selected files when it is activated.

(This example command, for versions of CVS later than 1.3, will force an update to the head version of a file, ignoring any sticky tags or versions attached to the file).

Setting a variable with this name to a value like "commandname" causes the command "commandname" to be run when this menu option is selected. For example, the following line:

set usermenu(view) "cat"

Causes a new menu option titled "view" to be added to the User defined menu that will run the command "cat" on the selected files when it is activated.

Any user-defined commands will be passed a list of file names corresponding to the files selected on the directory listing on the main menu as arguments.

The output of the user defined commands will be displayed in a window when the command is finished.