| TkCVS(1) | General Commands Manual | TkCVS(1) |
TkCVS - a Tk/Tcl Graphical Interface to CVS and Subversion
tkcvs [-dir directory] [-root cvsroot] [-win workdir|module|merge] [-log file]
TkCVS is a Tcl/Tk-based graphical interface to the CVS and Subversion configuration management systems. It displays the status of the files in the current working directory, and provides buttons and menus to execute configuration-management commands on the selected files. Limited RCS functionality is also present. TkDiff is bundled in for browsing and merging your changes.
TkCVS also aids in browsing the repository. For Subversion, the repository tree is browsed like an ordinary file tree. For CVS, the CVSROOT/modules file is read. TkCVS extends CVS with a method to produce a browsable, "user friendly" listing of modules. This requires special comments in the CVSROOT/modules file. See "CVS Modules File" for more guidance.
TkCVS accepts the following options.
Browse the modules located in CVSROOT /jaz/repository
The working directory browser shows the files in your local working copy, or "sandbox." It shows the status of the files at a glance and provides tools to help with most of the common CVS, SVN, and RCS operations you might do.
At the top of the browser you will find:
* The name of the current directory. You can change directories by typing in this field. Recently visited directories are saved in the picklist.
* The relative path of the current directory in the repository. If it is not contained in the repository you may import it using the menu or toolbar button.
* A Directory Tag name, if the directory is contained in the repository and it has been checked out against a particular branch or tag. In Subversion, the branch or tag is inferred from the URL based on the conventional trunk-branches-tags repository organization.
* The CVSROOT of the current directory if it's under CVS control, or the URL of the Subversion repository if it's under Subversion control. If neither is true, it may default to the value of the $CVSROOT environment variable.
The main part of the working directory browser is a list of the files in the current directory with an icon next to each showing its status. You select a file by clicking on its name or icon once with the left mouse button. Holding the Control key while clicking will add the file to the group of those already selected. You can select a contiguous group of files by holding the Shift key while clicking. You can also select a group of files by dragging the mouse with the middle or right button pressed to select an area. Selecting an item that's already selected de-selects that item. To unselect all files, click the left mouse button in an empty area of the file list.
* The Date column (can be hidden) shows the modification time of the file is shown. The format of the date column may be specified with cvscfg(dateformat). The default format was chosen because it sorts the same way alphabetically as chronologically.
If the directory belongs to a revision system, other columns are present.
* The revision column shows which revision of the file is checked out, and whether it's on the trunk or on a branch.
* The status column (can be hidden) shows the revision of the file spelled out in text. This information is mostly redundant to the icon in the file column.
* The Editor/Author/Locker column (can be hidden) varies according to revision system. In Subversion, the author of the most recent checkin is shown. In CVS, it shows a list of people editing the files if your site uses "cvs watch" and/or "cvs edit". Otherwise, it will be empty. In RCS, it shows who, if anyone, has the file locked.
The optional columns can be displayed or hidden using the Options menu.
You can move into a directory by double-clicking on it.
Double clicking on a file will load the file into a suitable editor so you can change it. A different editor can be used for different file types (see Configuration Files).
When you are in a directory that is under CVS or Subversion control, the 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. Some possible statuses are:
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.
There are a number of buttons at the bottom of the window. Pressing on one of these causes the following actions:
The TkCVS Log Browser window enables you to view a graphical display of the revision log of a file, including all previous versions and any branched versions.
You can get to the log browser window in three ways, either by invoking it directly with "tkcvs [-log] <filename>", by selecting a file within the main window of TkCVS and pressing the Log Browse button, or by selecting a file in a list invoked from the module browser and pressing the Log Browse button.
If the Log Browser is examining a checked-out file, the buttons for performing merge operations are enabled.
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.
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.)
Once a file is loaded into the log browser, one or two version numbers may be selected. The primary version (Selection A) is selected by clicking the left mouse button on a version box in the main log display.
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.
You can search the canvas for tags, revisions, authors, and dates.
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.
\x 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
The log browser contains the following buttons:
The View Menu allows you to control what you see in the branch diagram. You can choose how much information to show in the boxes, whether to show empty revisions, and whether to show tags. You can even control the size of the boxes. If you are using Subversion, you may wish to turn the display of tags off. If they aren't asked for they won't be read from the repository, which can save a lot of time.
The Merge Tool chooses a "representative" file in the current directory and diagrams the branch tags. It tries to pick the "bushiest" file, or failing that, the most-revised file. If you disagree with its choice, you can type the name of another file in the top entry and press Return to diagram that file instead.
The main purpose of this tool is to do merges (cvs update -j rev [-j rev]) on the whole directory. For merging one file at a time, you should use the Log Browser. You can only merge to the line (trunk or branch) that you are currently on. Select a branch to merge from by clicking on it. Then press either the "Merge" or "Merge Changes" button. The version of the file in the current directory will be over-written, but it will not be committed to the repository. You do that after you've reconciled conflicts and decided if it's what you really want.
Operations that are performed on the repository instead of in a checked-out working directory are done with the Module Browser. The most common of these operations is checking out or exporting from the repository. The Module Browser can be started from the command line (tkcvs -win module) or started from the main window by pressing the big button.
Subversion repositories can be browsed like a file tree, and that is what you will see in the Module Browser. CVS repositories aren't directly browsable, but if the CVSROOT/modules file is maintained appropriately, TkCVS can display the modules and infer tree structures if they are present. See the "CVS Modules File" section.
Using the module browser window, you can select a module to check out. When you check out a module, a new directory is created in the current working directory with the same name as the module.
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 checkout called an export. This allows you to 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. In CVS, 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 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.
The module browser contains the following buttons:
Before importing a new module, first check to make sure that you have write permission to the repository. Also you'll have to make sure the module name is not already in use.
To import a module you first need a directory where the module is located. Make sure that there is nothing in this directory except the files that you want to import.
Press the big "Repository Browser" button in the top part of the tkcvs UI, or use CVS -> Import WD into Repository from the menu bar.
In the module browser, press the Import button on the bottom, the one that shows a folder and an up arrow.
In the dialog that pops up, fill in a descriptive title for the module. This will be what you see in the right side of the module browser.
OK the dialog. Several things happen now. The directory is imported, the CVSROOT/module file is updated, your original directory is saved as directory.orig, and the newly created module is checked out.
When it finishes, you should find the original Working Directory Browser showing the files in the newly created, checked out module.
Here is a more detailed description of the fields in the Import Dialog.
Importing a directory into Subversion is similar but not so complicated. You use the SVN -> Import CWD into Repository menu. You need supply only the path in the repository where you want the directory to go. The repository must be prepared and the path must exist, however.
Before importing to an existing module, first check to make sure that you have write permission to the repository.
To import to an existing module you first need a directory where the code is located. Make sure that there is nothing in this directory (including no CVS directory) except the files that you want to import.
Open up the Repository Browser by selecting File/Browse Modules from the menu bar.
In the Repository Browser, select File/Import To An Existing Module from the menu bar.
In the dialog that pops up, press the Browse button and select the name of an existing module. Press the OK to close this dialog box. Enter the version number of the code to be imported.
OK the dialog. Several things happen now. The directory is imported, your original directory is saved as directory.orig, and the newly created module is checked out.
When it finishes, you will find the original Working Directory Browser showing the original code. If you press the "Re-read the current directory" button you will see the results of the checked out code.
Here is a more detailed description of the fields in the Import Dialog.
Software development is sometimes based on source distribution from a vendor or third-party distributor. After building a local version of this distribution, merging or tracking the vendor's future release into the local version of the distribution can be done with the vendor merge command.
The vendor merge command assumes that a separate module has already been defined for the vendor or third-party distribution with the use of the "Import To A New Module" and "Import To An Existing Module" commands. It also assumes that a separate module has already been defined for the local code for which the vendor merge operation is to be applied to.
Start from an empty directory and invoke tkcvs. Open up the Repository Browser by selecting File/Browse Modules from the menu bar.
Checkout the module of the local code to be merged with changes from the vendor module. (Use the red icon with the down arrow)
In the Repository Browser, after verifying that the Module entry box still has the name the module of the local code to which the vendor code is to be merged into, select File/Vendor Merge from the menu bar.
In the Module Level Merge With Vendor Code window, press the Browse button to select the module to be used as the vendor module.
OK the dialog. All revisions from the vendor module will be shown in the two scroll lists. Fill in the From and To entry boxes by clicking in the appropriate scroll lists. Ok the dialog. Several things happens now. Several screens will appear showing the output from cvs commands for (1)checking out temp files, (2)cvs merge, and (3)cvs rdiff. Information in these screens will tell you what routines will have merge conflicts and what files are new or deleted. After perusing the files, close each screen. .TP (In the preceeding dialog box, there was an option to save outputs from the merge and rdiff operations to files CVSmerge.out and CVSrdiff.out.)
The checked out local code will now contain changes from a merge between two revisions of the vendor modules. This code will not be checked into the repository. You can do that after you've reconciled conflicts and decide if that is what you really want.
A detailed example on how to use the vendor merge operation is provided in the PDF file vendor5readme.pdf.
There are two configuration files for TkCVS. The first is stored in the directory in which the *.tcl files for TkCVS are installed. This is called tkcvs_def.tcl. You can put a file called site_def in that directory, too. That's a good place for site-specific things like tagcolours. Unlike tkcvs_def.tcl, it will not be overwritten when you install a newer version of TkCVS.
Values in the site configuration files can be over-ridden at the user level by placing a .tkcvs file in your home directory. Commands in either of these files should use Tcl syntax. In other words, to set a variable name, you should have the following command in your .tkcvs file:
for example:
The following variables are supported by TkCVS:
If your SVN repository has a structure similar to trunk, branches,
and tags but with different names, you can tell TkCVS about it by setting
variables in tkcvs_def.tcl:
set cvscfg(svn_trunkdir) "elephants"
set cvscfg(svn_branchdir) "dogs"
set cvscfg(svn_tagdir) "ducklings" The branch browser depends on
the convention of having a trunk, branches, and tags structure to draw the
diagram. These variables may give you a little more flexibility.
Most colors and fonts can be customized by using the options database. For example, you can add lines like these to your .tkcvs file:
You should have the CVSROOT environment variable pointing to the location of your CVS repository before you run TkCVS. It will still allow you to work with different repositories within the same session.
If you wish TkCVS to point to a Subversion repository by default, you can set the environment variable SVNROOT. This has no meaning to Subversion itself, but it will clue TkCVS if it's started in an un-versioned directory.
It is possible to extend the TkCVS menu by inserting additional commands into the .tkcvs or tkcvs_def.tcl files. These extensions appear on an extra menu to the right of the TkCVS Options menu.
To create new menu entries on the user-defined menu, set the following variables:
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:
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:
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.
If you haven't put anything in your CVSROOT/modules file, please do so. See the "Administrative Files" section of the CVS manual. Then, you can add comments which TkCVS can use to title the modules and to display them in a tree structure.
The simplest use of TkCVS's "#D" directive is to display a meaningful title for the module:
A fancier use is to organize the modules into a tree which will mimic their directory nesting in the repository when they appear in the module browser. For example, suppose we have a directory called "chocolate" which is organized like this:
To display its hierarchy, as well as make the deepest directories more accessible by giving them module names, we could put this in the modules file:
When you are installing TkCVS, you may like to add these additional lines to the modules file (remember to check out the modules module from the repository, and then commit it again when you have finished the edits).
These extension lines commence with a "#" character, so CVS interprets them as comments. They can be safely left in the file whether you are using TkCVS or not.
"#M" is equivalent to "#D". The two had different functions in previous versions of TkCVS, but now both are parsed the same way.
Del (del@babel.babel.com.au): Maintenance and Subversion support: Dorothy Robinson
| Release | 8.2.3 |