VERSION LIBRARY VERSION LIBRARY VERSION LIBRARY UTILITIES UTILITIES UTILITIES Release 1.0 _______ ___ Jim Leth Lillipute ZNODE (312) 649-1730 (312) 664-1730 Version Library Utilities 1.0 Page 1 Version Libraries provide a simple but flexible approach to version Version Libraries Version Libraries management. 1. Motivation 1. Motivation 1. Motivation It is often necessary or desirable to keep multiple versions of a file or set of files. This is important in software development because it ensures that future changes to the software can be backed out, if necessary, to return to the current performance of the system. In other words, no matter how lost you get in making changes, you can at least get back to here. Version libraries also ____ help in finding the cause of bugs, since you can compare any two versions and determine exactly what changes were made. They are essential in software maintenance, since previous releases may still need to be supported while new releases are being developed. A version history is useful for text files, as well. Technical documentation, contracts, resumes, reports, as well as all forms of creative writing are frequently revised. Often what gets excised in one revision gets put back later. A version library allows the writer to retrieve pieces of earlier work, or to trace the history of changes. 2. Version Libraries 2. Version Libraries 2. Version Libraries In this approach, a version library is a normal library (.LBR) file .LBR .LBR whose members are distinct versions of one or more source files. Note that the term "source file" refers to a specific version of a file to be recorded in the version library; these files do not have to be source code or even text files, but can be any type of file, including object code, executable programs, and other libraries. Each member's name consists of a user-assigned version identifier in the filename field, with the same extension as the original source file. The version identifier can be in any form acceptable as a CP/M filename. The extension does not have to be specified, but is automatically taken from the extension of the source file (any other extension is ignored). This allows a single version library (e.g. SOURCE.LBR) to include versions of different files SOURCE.LBR SOURCE.LBR with the same filename part but different extensions (e.g. ________ __________ SOURCE.C, SOURCE.H, and SOURCE.DOC). SOURCE.C SOURCE.H SOURCE.DOC SOURCE.C SOURCE.H SOURCE.DOC Version identifiers may be chosen on any basis, but should provide a meaningful identification of the significance of that version. Good choices would be release numbers (REL-101, V-01-01), dates REL-101 V-01-01 REL-101 V-01-01 (86-09-16, SEP16-86), development status (PROTOTYP, BETATEST), or 86-09-16 SEP16-86 PROTOTYP BETATEST 86-09-16 SEP16-86 PROTOTYP BETATEST simply notes to yourself about the status of that version (1STDRAFT, COMPILES, CRASHES). Note that if version identifiers 1STDRAFT COMPILES CRASHES 1STDRAFT COMPILES CRASHES are the dates of development of each version, encoded in the form: 86-09-16, then the normal practice of displaying library 86-09-16 86-09-16 directories in alphabetical order will display the versions entered in chronological order. Version Library Utilities 1.0 Page 2 3. Command Interface: ALIAS.CMD 3. Command Interface: ALIAS.CMD 3. Command Interface: ALIAS.CMD The file ALIAS.CMD included in this package provides the following ALIAS.CMD ALIAS.CMD aliases for use with ARUNZ.COM and NULU.COM: ARUNZ.COM NULU.COM ARUNZ.COM NULU.COM putv put a new version of a file into its version library; putv putv getv extract a specific version (or the latest revision) of a getv getv file from its version library; lv list all the versions of a file; lv lv difv display differences between different versions of a difv difv file; delv delete a version of a file from its version library; delv delv renv rename a version of a file (change its version renv renv identifier). To use these aliases, copy the file ALIAS.CMD into one of the ALIAS.CMD ALIAS.CMD directories in the PATH (usually ROOT:), or merge these aliases PATH ROOT: PATH ROOT: with your own ALIAS.CMD file. ALIAS.CMD ALIAS.CMD 3.1. PUTV [du|dir-name:]source-file [version] 3.1. PUTV [du|dir-name:]source-file [version] 3.1. PUTV [du|dir-name:]source-file [version] Putv puts a new version of a file into its version library. If the Putv Putv version library does not yet exist, it creates one. Its filename is the same as that of the source file, but its extension is .LBR. .LBR .LBR All version libraries are kept in the directory BACKUP:. BACKUP: BACKUP: If a version identifier is specified, the new library member will have that identifier as its filename, but will keep the same extension as the original source file (ignoring any extension specified with the version identifier). This ensures that different source files (differing only in extension) will generate unique entries in the version library, even if they are given the same version identifiers. If no version identifier is given, putv will name the new library putv putv member the same as the original source file. Subsequent versions added without any explicit version identifier will replace this member. This provides a simple convention for keeping track of the "last saved revision" while the source file is changing frequently (e.g. a program under development). Library members with explicit version identifiers can also be updated by putting a new version into the library under the same version identifier. Consider the following example. A C program might consist of the C C following source files: main.c reader.c reader.h Version Library Utilities 1.0 Page 3 While the first draft of each file is under development, "snapshots" of the current state of each file may be entered into version libraries whenever a significant amount of progress has been made. These transient versions are entered into version libraries with the putv alias: putv putv putv main.c putv reader.c putv reader.h The first command will enter the current version of MAIN.C into a MAIN.C MAIN.C library named BACKUP:MAIN.LBR, creating it if necessary. The BACKUP:MAIN.LBR BACKUP:MAIN.LBR member name will be MAIN.C. MAIN.C MAIN.C The last two commands will build the library BACKUP:READER.LBR, BACKUP:READER.LBR BACKUP:READER.LBR containing members READER.C and READER.H. READER.C READER.H READER.C READER.H When each program reaches the point where it compiles, the programmer may wish to enter a named version that can be kept around even after other versions are saved. The following commands might be used: putv main.c compiles putv reader.c compiles putv reader.h compiles Here, the word "compiles" is chosen as the version identifier for all three files. The libraries would now contain the following members: MAIN.LBR READER.LBR ________ __________ COMPILES.C COMPILES.C COMPILES.H Note that the transient versions previously entered into the libraries (MAIN.C, READER.C, and READER.H) have been deleted by MAIN.C READER.C READER.H MAIN.C READER.C READER.H entering named versions. This is normally reasonable, since the transient versions are supposed to identify the "latest revision", but you've just entered a newer one. Transient versions can still be entered until the next named version is entered. For example: putv reader.c READER.LBR __________ COMPILES.C COMPILES.H READER.C 3.2. GETV [du|dir-name:]source-file [version] 3.2. GETV [du|dir-name:]source-file [version] 3.2. GETV [du|dir-name:]source-file [version] The alias getv extracts a specific version of a file, overwriting getv getv the current version of the source file (if one exists) with the extracted version. If no version identifier is specified, the "current revision" is extracted (the entry with the same name as the source file). Otherwise, the filename part of the version identifier (ignoring any extension) and the extension of the source file are used to form the entry name to be extracted. Version Library Utilities 1.0 Page 4 Continuing with the above example, the following command will extract the entry named "COMPILES.C" from the library BACKUP:READER.LBR, renaming the extracted file "READER.C" and BACKUP:READER.LBR BACKUP:READER.LBR placing it on drive C:, user area 3. C: 3 C: 3 getv c3:reader.c compiles The following command extracts the latest revision of READER.C from the library, placing it in the current drive and user area. getv reader.c 3.3. LV source-file 3.3. LV source-file 3.3. LV source-file The alias lv lists all versions of the specified source file stored lv lv in the version library. The program LDIR.COM is used to display LDIR.COM LDIR.COM all members of the relevant version library with the same extension as the source file. Other members of the library will be versions of other source files (with the same filename but different extensions); these other members are not shown. 3.4. DIFV [du|dir-name:]source-file [version1 [version2]] 3.4. DIFV [du|dir-name:]source-file [version1 [version2]] 3.4. DIFV [du|dir-name:]source-file [version1 [version2]] The alias difv is used to display the changes between any two difv difv versions of the specified source file. Two other aliases, difv0 difv0 difv0 and difv1 are used by difv, based on which of the three modes of difv1 difv difv1 difv operation (shown below) are invoked. The following command compares the existing source file READER.C READER.C READER.C with the last version that was saved in the version library under the name READER.C. READER.C READER.C difv reader.c The following command compares the existing source file READER.C READER.C READER.C with the version saved under the identifier COMPILES. COMPILES COMPILES difv reader.c compiles The following command compares the version saved under the identifier COMPILES with the version saved under the name COMPILES COMPILES READER.C. READER.C READER.C difv reader.c compiles reader.c In all cases, the required versions are extracted from the version library to temporary filenames (or to the directory BACKUP:), BACKUP: BACKUP: compared using the program DIF, then erased. The current copy of DIF DIF the source file, whether involved in the comparison or not, is left untouched after this command. Version Library Utilities 1.0 Page 5 3.5. DELV source-file [version] 3.5. DELV source-file [version] 3.5. DELV source-file [version] The alias delv deletes a specific version of the source file from delv delv its version library. If no version identifier is specified, then the version saved under the same name as the source file is used. The source file itself is not deleted, if it exists. 3.6. RENV source-file version1 [version2] 3.6. RENV source-file version1 [version2] 3.6. RENV source-file version1 [version2] The alias renv renames a specific version of the source file, renv renv giving that version a new version identifier. There are two forms of this command, as shown in the examples below. The following command will rename the last version of READER.C that READER.C READER.C was stored under that name, giving it the new version identifier 86-12-21. 86-12-21 86-12-21 READER.LBR __________ COMPILES.C COMPILES.H READER.C renv reader.c 86-12-21 READER.LBR __________ COMPILES.C COMPILES.H 86-12-21.C The following command renames version COMPILES of source file COMPILES COMPILES READER.H to the version identifier REL-0100. READER.H REL-0100 READER.H REL-0100 renv reader.h compiles rel-0100 READER.LBR __________ COMPILES.C REL-0100.H READER.C 3.7. V [[du|dir-name:]file-spec] 3.7. V [[du|dir-name:]file-spec] 3.7. V [[du|dir-name:]file-spec] The alias v starts up a menu interface to the aliases described v v above. If no file specification is given, all files in the designated (or current) drive and directory are displayed. Otherwise, only those files that match the file-spec are displayed. The operations that can be performed within the menu system are described below. 4. VMENU Interface: VERSIONS.VMN 4. VMENU Interface: VERSIONS.VMN 4. VMENU Interface: VERSIONS.VMN The file VERSIONS.VMN provided with these utilities is intended for VERSIONS.VMN VERSIONS.VMN use with VMENU.COM. If this menu file is placed somewhere along VMENU.COM VMENU.COM the PATH, the alias v will start VMENU using the menu definition in PATH v VMENU PATH v VMENU VERSIONS.VMN. VERSIONS.VMN VERSIONS.VMN Version Library Utilities 1.0 Page 6 When VMENU starts, the top of the screen will show the files in the VMENU VMENU current directory, or those that match the file-spec, if given. A file can be selected from this display by moving the cursor to its name using the standard VMENU keys. (Briefly, '+' and '-' moves VMENU VMENU the window through the file list, and the spacebar and arrow keys move the cursor within that window.) The following menu is displayed: VERSIONS -- VMENU Interface to Version Libraries Rel. 1.0 VERSIONS -- VMENU Interface to Version Libraries Rel. 1.0 VERSIONS -- VMENU Interface to Version Libraries Rel. 1.0 Use space bar or arrow keys to move cursor to select file, then choose command from menu: M change MENU H Help M H M H L List versions of file D Delete a version L D L D G Get a version P Put a new version G P G P K Keep file under new = Rename file K = K = name and get version R Rename a version R R C Compare versions C C B Browse file E Edit file B E B E ? file size ? ? F Find file(s) I Inquire directory names F I F I Z Invoke ZCPR3 command V chain to VFILER Z V Z V The menu operations are as follows. M -- prompts for the name of a menu file (without the .VMN M .VMN M .VMN extension), and changes to that menu. H -- prompts for a help topic and invokes the HELP program. H HELP H HELP L -- invokes the lv alias on the pointed-to file. L lv L lv D -- prompts for a version identifier, then deletes that D D version from the version library for the pointed-to file (if no version identifier is supplied, the last version with the same name as the source file is deleted). Note that this command does not delete the pointed-to file. ___ G -- prompts for a version identifier and extracts that version G G of the source file, overwriting the current source file (if no version identifier is supplied, the last version with the same name as the source file is extracted). P -- prompts for a version identifier, then puts the current P P source file into its version library under that identifier (if no version identifier is supplied, then the new version is entered with the same name as the source file). K -- prompts for a new name for the current source file and K K renames it, then acts as G above. G G = -- prompts for a new name for the current source file and = = renames it. R -- prompts for two version identifiers, then invokes renv R renv R renv with the pointed-to file name and the user's input as parameters. If the second prompt is answered with only a Version Library Utilities 1.0 Page 7 carriage return, then the version entered with the same name as the source file is renamed to the version identifier input at the first prompt. If version identifiers are input to both prompts, then the input to the first prompt is the name of the version to be renamed, and the input to the second prompt is the new name for that version. C -- prompts for two version identifiers, then invokes difv C difv C difv with the pointed-to file name and the user's input as parameters. If both prompts are answered with only carriage returns, then the pointed-to file is compared with the last version entered in its version library under that same name. If only one version identifier is input, then the pointed-to file is compared with the version specified. If both version identifiers are input at the prompts, then the two specified versions of the pointed-to file are compared; in this case, the actual source file that is pointed to is not used in the comparison. B -- browses through the pointed-to file by invoking the B B program SCAN.COM. SCAN.COM SCAN.COM E -- edits the pointed-to file (in the file ALIAS.CMD, replace E ALIAS.CMD E ALIAS.CMD the name "EDIT" with the name of your editor of choice). ? -- invokes DIR.COM on the pointed-to file, showing its size ? DIR.COM ? DIR.COM and the space left on the disk. F -- prompts for a file specification, then invokes FINDF.COM F FINDF.COM F FINDF.COM to search the user's disks for matching file names. I -- invokes the program PWD.COM to display the names of all I PWD.COM I PWD.COM directories in the current named directory package. Z -- prompts for a command line and executes it. Z Z V -- aborts the VMENU shell, replacing it on the shell stack V VMENU V VMENU with VFILER. This is different than invoking VFILER from VFILER VFILER VFILER VFILER within the shell; when the VFILER shell is terminated, control VFILER VFILER will not return to this VMENU session. I find it convenient to ___ VMENU VMENU be able to switch back and forth between VFILER and one or more VFILER VFILER menu systems, without having to worry about getting nested deeper and deeper in the shell stack. 5. Limitations And Potential Improvements 5. Limitations And Potential Improvements 5. Limitations And Potential Improvements As distributed, the maximum number of members is set to 63 for all version libraries. This default can be changed by editing the alias script, ALIAS.CMD. ALIAS.CMD ALIAS.CMD Since these commands operate as aliases, they are somewhat slow. I do not find them intolerably slow, even on a floppy-based system (I use four 96tpi floppies -- 800K each -- on an Ampro Little Board). With a hard disk or RAM disk, speed should not be a problem. Version Library Utilities 1.0 Page 8 The major drawback to this system is that complete copies of all versions are stored in the library. In some more sophisticated version control systems, only the differences between versions are stored (and at least one "base version"). Alternatively, the versions entered into the library could be squeezed or crunched first, and unsqueezed or uncrunched when extracted. This would be a lot easier to do if NULU supported a NULU NULU "squeeze on entry" option, and if the original file extension could be retained when squeezing (instead of automatically changing .xxx .xxx .xxx to .xQx.). .xQx .xQx If there is interest, I may try to develop compiled, non-alias versions of these tools, which would allow for more powerful operation. 6. Requirements 6. Requirements 6. Requirements The following programs are used or assumed by the version aliases. The exact versions shown may not be necessary, but those are the versions I currently use with this system. ARUNZ.COM version 1.09B ARUNZ.COM ARUNZ.COM DIF.COM version 2.00 DIF.COM DIF.COM LDIR.COM version 2.3 LDIR.COM LDIR.COM NULU.COM version 1.51 NULU.COM NULU.COM VMENU.COM version 2.3 VMENU.COM VMENU.COM The following programs are used by the menu operations. These are not strictly required, as you may want to customize the menu system to your own preferences. DIR.COM DIR.COM DIR.COM EDIT -- replace with your preferred editor EDIT EDIT FINDF.COM FINDF.COM FINDF.COM HELP.COM HELP.COM HELP.COM PWD.COM PWD.COM PWD.COM SCAN.COM SCAN.COM SCAN.COM SETFILE.COM SETFILE.COM SETFILE.COM SHCTRL.COM SHCTRL.COM SHCTRL.COM