This is the documentation for SVMS (Source Version Management System).

SVMS Documentation

SVMS Overview

svms command_name command_arguments ...

Every project has a project nickname that is assigned to the project when it is created. While there is no way to guarantee that project nicknames are unique, it is very desirable that they be unique. For this reason, most projects used for individual development should have the user's login name in the nickname (e.g. "gramlich-home1".)

Any project can have at most one parent project. This parent project is used by the svms bringover and svms putback commands.

Many of the svms commands take a file_list in addition to some command specific options. A file_list is a space/tab separated list of one or more of the following:

Files

Each file can be one of the following:

Binary File

A binary file is an uninterpreted sequence of raw bytes. Byte files are represented the same on all operating systems.

Text File

A text file consists of lines of printable ASCII/Latin-1 characters separated by an appropriate operating system specific line separator sequence, which for UNIX is a single line-feed (new-line) character and for Microsoft is a carriage-return followed by a line-feed character.

SVMS will keep track of whether a file has the executable bit set or not; thus, both binary executables and executable shell scripts can be directly stored in SVMS delta files.

Symbolic Links

Symbolic links can be directly stored in SVMS delta files. A symbolic link can be partitioned into either well behaved or ill behaved ones. A well behaved symbolic link has the following characteristics:

• it is relative to the directory it is located in; in other words, it does not start with a slash (`/'.)
• its path never extends outside of the project.
• it points to another text/binary file or symbolic link in the project; it does not point to a directory on non-existent location.

Any symbolic link that is not well behaved is by definition ill behaved (i.e. it does not meet one of the characteristics listed above.) SVMS delta files can store both well behaved and ill behaved symbolic links, but it takes a little more effort to store an ill behaved one.

Directory

Directories are storable in SVMS delta files. Unlike text/binary files and symbolic links, the contents of directory delta files are automatically managed by SVMS. Thus, the only operations permitted on directories are create, rename, and delete; these three operations are sufficient for SVMS to keep track of the inevitable directory reorganizations that occur as a project evolves over time.

Directory Trees

A directory tree is a short hand notation for a list of all the binary/text files and symbolic links in a specified directory and all of its descendant subdirectories. The notation for a directory tree is to name a directory and follow it by (`/...'.) It is

Slice Files

A slice file is a file that lists a sub-set (i.e. a slice) of the the files in a project. A slice file is indicated in an file_list preceding the slice file name with an at sign character (`@'). Slice files contain lines of file_list entrys or comment lines, where a comment line starts with a sharp character (`#'); blank lines are permitted as well. Slice files can refer to other slice files, provided no infinite recursion loop is introduced by doing so.

• A colon (`:') at the beginning of a file name is an indication that the file name is relative to a project root, rather than relative to the current working directory. The following colon syntax is supported:

  :/file_name

  file_name is relative to the current project root.

  ::/file_name

  file_name is relative to the parent project root. Each additional colon in the list causes an additional ancestor to be named; Thus, :::/file_name, specifies a file_name relative to the grand parent project directory.

  :project_nickname/file_name

  file_name is relative to the project_nickname project directory. This is very similar to the ~user syntax that many Unix shells implement.

• If a file name does not begin with a colon, it is relative to the current working directory. The `../' syntax can be used to reference as many parent directories as appropriate. Warning messages are issues if a sequence of `../' exits the files covered by the project root.
• File names that start with slash (`/') or tilde (`~') are relative to the file system root or some user's login directory. In general, such file names are discouraged since they are unlikely to reference files in the current project.
• The percent character ('%') is used to introduce characters into file names that are typically used for other purposes (e.g. the `@'.) The percent character is followed by two hexadecimal digits that specify the desired character. A percent character can be introduced into a file name via `%25' and an at sign character (`@') can be introduced via `%40'. Since many Unix shells use percent for job control purposes, it many be necessary to quote each percent character in order to specify it in a file name.

SVMS Commands

bringover [ -l ] [ file_list ]

This command merges all files, directories, directory trees and symbolic links specified by file_list from the parent project into the current project. Conflicts are resolved as automatically as possible. Any unresolved conflicts are listed to the user for subsequent resolution.

If no file_list is specified, `/...' is used as a default file_list, thereby causing all files from the parent project to be brought over.

The -l option will perform a lazy bringover from the parent. This is quite efficient in terms of disk space, but it does require that the parent project always be accessible. The svms parent command can be used after a lazy bringover, but it may cause substantial numbers of files to be brought over. Cascaded lazy bringovers are supported.

cd file_list

This command will ensure that each directory and directory tree in file_list has been made. Any necessary svms.mk files are constructed as a side-effect of this command (see svms make.)

close [ -f | -h history_file ] [ file_list ]

This command will close the deltas for each file, directory, directory tree, and symbolic link specified by file_list. The user is prompted for a history comment to be recorded in each delta. The history comment is terminated by a blank line. If no file_list is specified, `./...' is used by default, thereby closing all files in the current directory and below.

The close command disallows symbolic links that do not point to existing regular files somewhere in the project via a relative path, unless it overridden via the -f option.

The -h option causes history_file to be used as the history file, thereby suppressing the prompting for a history comment.

copy old_file new_file

This command will copy old_file to new_file.

create [ -R | -b | -t ] [ -f ] file_list

This command will create a delta file for each file, directory, or symbolic link listed in file_list. Directory trees may not be specified in file_list for this command.

The -R option will create any necessary directory delta files to store each text/binary file or symbolic link.

In general, heuristics are used to determine the file type for regular files. The -b and -t options are used to override the heuristics for choosing between binary files and text files respectively. There is no way to selectively override heuristics on a file by file basis from the command line; instead, multiple svms create commands are needed.

The -f option is used to force the create of symbolic links that do not point to regular files within the project via a relative path.

The execute bit is preserved for both text and binary files so that both shell scripts and binary executables can be stored under SVMS.

delete [ -R | -r ] file_list

This command will mark each file, directory, directory tree, or symbolic link listed in file_list as deleted in the corresponding delta files.

In general, directories and directory trees will only be deleted if they contain no files. The -R option will recursively delete directory trees even if they are not empty. The -r option will recursively delete only any empty directories in a file tree. Thus, `svms delete -r /...' will clean up any unused directories in the entire project.

filter

This command will read standard input and convert all occurrences of %xx them to the appropriate character. This command is meant to be used in conjunction with the svms history -m command.

get [ -n project_nickname.delta_number | -d yyyy/mm/dd@hh:mm:ss-ZZZ | -r release_name ] [ file_list ] [ -o output_file_name ]

This command will fetch read-only versions of each file, directory, directory tree, or symbolic link listed in file_list. In order to work reasonably well with make, this command attempts to get files in an order that preserves the relative order of modification times. If no file_list is specified, `./...' is used by default thereby causing all files in the current directory an below to be gotten. The command `svms get /...' will cause all of the files in a project to be gotten.

The -n option is used to explicitly get an older version named by project_nickname.delta_number.

The -r option is used to get relased named release_name.

The -d option is used to fetch an older version via a date and time yyyy/mm/dd@hh:mm:ss-ZZZ

yyyy

A four digit decimal year.

mm

A decimal month between 1 and 12 inclusive.

dd

A decimal day between 1 and 31 inclusive as appropriate for the month.

hh

A decimal hour between 0 and 23 inclusive.

mm

A decimal minute between 0 and 59 inclusive.

ss

A decimal second between 0 and 59 inclusive.

ZZZ

a A time-zone like GMT, EST, PST, or PDT.

If file_list consists of a single file, the -o option will cause the file to be stored in output_file_name. If output_file_name is a single hyphen character (`-'), the file will be output to the standard output.

help [ command_name ]

This command will list help for command_name. If command_name is not present, a list of all commands is provided.

history [ -m ] file_list

This command will list the history information for each file, directory, directory tree, and symbolic link in file_list.

If the -m option causes the history to be output with one line per delta for subsequent machine processing. In this mode, spaces are used exclusively to separate fields. All other spaces and new-lines are represented in %xx format.

list [ -a | -c | -d | -o ] [ file_list ]

This command will provide lists of files than meet certain characteristics. Only files in file_list will be eligible for the list. In no file_list is specified, ./... is used by default.

If the -a all files are listed irrespective of whether they are open, closed, or deleted.

If the -c option is specified, all closed files are listed.

If the -d option is specified, all deleted files are listed.

If the -o option is specified, all open files are listed.

If no options are specified, the -o option is used by default.

make [ -d ] [ file_list ]

This command causes a file named svms.mk to be created for each directory in file_list. For each file in file_list, implicit dependency tracking (i.e. header file dependencies) is enabled. This command is `sticky' in the sense that any time a directory is created by an svms command, it will create the corresponding svms.mk file as well.

The -d option undoes the effect of this command.

If no file_list is present, . is used by default.

new [ -R ] new_project_directory project_nickname

This command will create a new SVMS project at new_project_directory. The new project is given a nickname of project_nickname. The project nickname is used to identify individual deltas inside of delta files.

The -R option will recursively create any directories needed prior to creating the SVMS project directory.

open file_list

This command will open each file and symbolic link in file_list for editing.

parent [ -a user_account | -r | -u parent_project_url ]

If no options are specified, this command will print out the parent project for the current project.

The -p option will set the parent project to parent_project_url. parent_project_url can be a URL of the following two forms:

http://host[:port]//path/

where host is a DNS name of a host machine, port is an optional port number, and path is an appropriate path to a SVMS project directory.

file:/path/

where path is the path to the parent directory on the current machine.

The -u option will unparent the current project.

putback [ file_list ]

This command merges all files, directories, directory trees and symbolic links specified by file_list from the current project into the parent project. This command will only succeed if there are no conflicts between the parent and current project.

If no file_list is specified, `/...' is used as a default file_list, thereby causing all files from the current project to be put back to the parent directory.

release release_name

This command will create a named release for the project. This named release can be used in the get command to fetch a previous version of a command.

reroot new_project_directory

This is a really expensive command that moves the current project root to a new location. Rerooting moves the SVMS directory and rewrites every delta file in the project; hence, this command can be quite expensive.

Moving the project root up the directory hierarchy is fairly easy; moving it down requires that creating a child project and bringing over just those portions of the project that are needed in the new rerooted project.

REMOVE project_directory

This command will delete project_directory. Needless to say, this is a pretty dangerous command; hence, this is the only command that capitalized so that it does not get confused with the svms delete command.

rename old_file new_file

This command will rename old_file to new_file. The rename is conceptually done by copy old_file to new_file and then deleting old_file. By doing renames this way, it is possible to fetch earlier versions of a project and still have them be consistent.

changes
convert
identifiers