File Status

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]

A directory which has been checked out from a CVS repository.

[directory:SVN]

The file is a directory which has been checked out from a Subversion repository. In Subversion, directories are themselves versioned objects.

[directory:RCS]

A directory which contains an RCS sub-directory or some files with the ,v suffix, presumably containing some files that are under RCS revision control.

[directory]

The file is a directory.

File Filters

"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.

Buttons

Module Browser:

The big button at the upper right opens the module browser. Opens a module browser window which will enable you to explore items in the repository even if they're not checked out. In CVS, this requires that there be entries in the CVSROOT/modules file. Browsing can be improved by using TkCVS-specific comments in CVSROOT/modules.

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.

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 can be a lot faster then Edit, in case 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.

Directory Branch Browse:

For merging the entire directory. In Subversion, it opens the Branch Browser for "." In CVS, it chooses a "representative" file in the current directory and opens a graphical tool for directory merges.

Log (Branch) Browse:

This button will bring up the log browser window for each of the selected files in the window. See the Log Browser section.

Annotate:

This displays a window in which the selected file is shown with the lines highlighted according to when and by whom they were last revised. In Subversion, it's also called "blame."

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.

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. For checking in to RCS, an externel editor is always used.

Update:

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

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 Files:

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. In CVS, 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. In CVS, the -F (force) option will move the tag if it already exists on the file.

Lock (CVS and RCS):

Lock an RCS file for editing. If cvscfg(cvslock) is set, lock a CVS file. Use of locking is philosophically discouraged in CVS since it's against the "concurrent" part of Concurrent Versioning System, but locking policy is nevertheless used at some sites. One size doesn't fit all.

Unlock (CVS and RCS):

Unlock an RCS file. If cvscfg(cvslock) is set, unlock a CVS file.

Set Edit Flag (CVS):

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 (CVS):

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 Working Directory Browser. If no other windows are open, TkCVS exits.

Log Browser Window

Log Display

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

Constructing the branch diagram from Subversion is inefficient, so the Log Browser counts the tags when doing a Subversion diagram and pops up a dialog giving you a chance to skip the tag step if there are too many tags (where "many" arbitrarily equals 10.)

Version Numbers

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

Operations such as "View" and "Annotate" operate only on the primary version selected.

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

Searching the Diagram

The following special characters are used in the search pattern:

* Matches any sequence of characters in string, including a null string.

? Matches any single character in string.

[chars] Matches any character in the set given by chars. If a sequence of the form x-y appears in chars, then any character between x and y, inclusive, will match.

Matches the single character x. This provides a way of avoiding the special interpretation of the characters *?[] in pattern.

If you only enter "FOO" (without the

Log Browser Buttons

Refresh:

Re-reads the revision history of the file.

View:

Pressing this button displays a Tk text window containing the version of the file at Selection A.

Annotate:

This displays a window in which the file is shown with its lines highlighted according to when and by whom they were last revised. In Subversion, it's also called "blame."

Diff:

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

Merge:

To use this button, select a branch version of the file, other than the branch you are currently on, as the primary version (Selection A). The changes made along the branch up to that version will be merged into the current version, and stored in the current directory. Optionally, select another version (Selection B) and the changes will be from that point rather than from the base of the branch. The version of the file in the current directory will be 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. It's suggested to leave the dialog up until you are finished, then copy-and-paste the suggested tag into the "Tag" dialog. It is always a good practice to tag when doing merges, and if you use tags of the suggested form, the Branch Browser can diagram them. (Auto-tagging is not implemented in Subversion because, despite the fact that tags are "cheap," it's somewhat impractical to auto-tag single files. You can do the tagging manually, however.)

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.

The View Options Menu

Tagging and Branching (cvs rtag)

Exporting

Importing

When the Module Browser displays a CVS repository, 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. The right mouse button will perform a secondary selection, which is used only for Subversion diff and patch. To clear the selection, click on the item again or click in an empty area of the module column. There can only be one primary and one secondary selection.

Repository Browser 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 Working 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 Repository Browser. If no other windows are open, TkCVS exits.

Startup

cvscfg(startwindow)

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

CVS

cvscfg(cvsroot)

If set, it overrides the CVSROOT environment variable.

Subversion

GUI

cvscfg(picklist_items)

Maximum number of visited directories and repositories to save in the picklist history

Log browser

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(toomany_tags)

Number of tags in a Subversion repository that's "too many", ie. will take longer to proecess for the branch diagram than you're willing to wait. (Building a branch diagram for Subversion is very inefficient.) If there are more than that number and cvscfg(confirm_prompt) is true, a dialog will appear asking whether to process the tags or to draw the diagram without them.

cvscfg(tagcolour,tagstring)

Colors for marking tags. For example:

Module browser

cvscfg(aliasfolder)

In the CVS 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.

User preferences

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(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(cvslock)

Set to true to turn on the ability to use cvs-admin locking from the GUI.

cvscfg(econtrol)

Set this to true to turn on the ability to use CVS Edit and Unedit, if your site is configured to allow the 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. By doing this, your site's commit template (rcsinfo) can be used.

File filters

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)

System

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

Portability

cvscfg(aster)

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

cvscfg(null)

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)

Debugging

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

cvsmenu(command)

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).

usermenu(command)

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.