Checking files in and out

Although Razor was designed in part to help avoid the drudgery of command line efforts in favor of a GUI, it is often handy to use the command line for special tasks. For example, some people may want to generate Emacs extensions which bring files in and out of the version control system. Another common need is to write a shell script which would do some mass edit of files under control. For example, by using the command line options, a script could check dozens of files out for edit, modify them all, and put them back without requiring a human to click around with a mouse.

Getting a read-only copy of a file

# razor -c get -f <file> -g <group> [-v version] \
[[-d dir] [-o] | [-z]]

If the optional -o flag is present, it forces an overwrite of any files that may already be there. If it is not present, and a file of the same name is already in the suggested directory, then the program will stop to query whether you want to overwrite the existing file.

If the -d flag is present, then files will be placed in the specified directory. However, the folder hierarchy is not reproduced as would otherwise be done. This has the same effect as selecting `path is absolute' when using the versions GUI.

To force output to stdout, use the optional -z flag.

Checking a file out for edit &
checking it back in again

# razor -c co -f <file> -g <group> [-d <dir>]\
   [[-i <issue[:<issue group>]>] ...] [-p <file>] \
   -t <title> [-o]
# razor -c ci -f <file> -g <group> [-d <dir> \
   [[-i <issue[:<issue group>]>] ...] [-p <file>] \
   -t <title>

Note that the primary difference between these two commands is the option for the -c flag. The string "co" is used to check the file out from version control, and the string "ci" is used to check the file back in again. Checking in a file from the command line always takes the file. If a readonly copy is required or the file is to be checked back out for edit, then an additional razor command must be executed. If a readonly copy is required, the command "razor -c get" must be executed.

The -f flag specifies the file name to be checked out/in, including the appropriate directory path, e.g. lib/os_funcs.c. If a branch is being checked out, separate the branch version (x.y.z) from the file name with an at-sign (@), e.g. server/status.cpp@1.12.1

In both cases, the -t flag is required. The quoted string which follows it is entered into the History file for the effort as the title. It's an opportunity to note why the file is being operated on. Additionally, an optional -p flag pair can be offered. If present, the contents of the named file are entered as the description prose in the history file. This allows for a more robust commenting mechanism.

If the optional -o flag is present on the check-out command, it forces an overwrite of any files that may already be in the specified directory. If the flag is not present and a file of the same name is already in the suggested directory, then the program will stop to query whether you want to overwrite the existing file.

It is also possible to associate any number of issues to either of the above check-in/checkout activities. To do so, simply put "-i <issue[:<issue group>]>" flag pairs onto the command line. The <issue> can be in either its fully annotated form (i.e. I..1-234) or as a simple integer value. Use ":<issue group>" to specify issues from other than the default issues group. You may have as many -i flag pairs as necessary.

Introducing a new file

Just as you can check files out or in, you may also need to introduce new files into the database using the command line interface. The following command will perform the file introduction:

# razor -c intro -f <file> -g <group> [-b] [-k] \
[-d folder] [-i <issue[:<issue group>]>]

The <file> and <group> parameters must be specified, with <file> being the path, absolute or relative, to the file being introduced. You may use the flag, -b, to introduce this file as a binary file; if not present, the file will be introduced as text. The file will be introduced into the database at the top-level of the group, unless you specify the -d <folder> flag; that option will specify an alternate destination in the database.

The -k flag is used to set the file property to "disable keyword expansion" by your selected archiving engine. You might set this if you're using SCCS as your file control archiving engine and you need to disable SCCS Keyword expansion, to avoid having a format string in your source code, such as, "%H%M%S" expanded to "07/24/98M%S" when you perform a check-out readonly operation or browse a file. By default, keyword expansion is enabled for all files.

It is also possible to associate any number of issues to the above activity. To do so, simply put "-i <issue[:<issue group>]>" flag pairs onto the command line. The <issue> can be in either its fully annotated form (i.e. I..1-234) or as a simple integer value. Use ":<issue group>" to specify issues from other than the default issues group. You may have as many -i flag pairs as necessary.

Un-checking a file

It is also possible to uncheck-out a file by command line. As with the commands above you need to specify the filename and group that it came from.

# razor -c un_co -f <file> -g <group>

Only the person who checked the file out to begin with, or those listed in the RAZOR_ADMIN role¹, are allowed to un-check it. Also note that the writable copy of the file that was obtained during the original check-out effort will remain available; it is not affected by this operation.

Creating a folder

There may be an occasion when it is necessary to create a folder in a file control group, possibly as preparation for a command line file introduction or the injection of existing SCCS/RCS archives. You may perform this operation with the command:

# razor -c new_folder -f <folder> -g <group>

where <folder> is the name of the new folder, or the folder path and new folder name, when creating a sub-folder.

Renaming a file or folder

Files or folders can be renamed within a file control group with the command:

# razor -c rename -f <file> -g <group> -n <new_name>

where <file> can be either a file or folder. If renaming to a folder, the folder path in <new_name> must be an existing location in <group>. Just as in the versions GUI, this command cannot rename a file that is currently checked-out for edit, a branch, or a trunk file with one or more branches. If renaming a folder, there cannot be any files checked-out for edit within the folder or any of its sub-folders. Also, this command cannot be used to rename issues, threads or projects.

Incrementing the major version of a file

When making major releases, some users like to be able to bump the major version number of all files. The easiest way to do this may be via a script. The Razor command line interface supports this via the following command:

# razor -c bump -f <file> -g <group> -t <title> \
[-r <new major>] [-i <issue[:<issue group>]>]

This operation will be treated as a file check-in and will execute any check-in before or after scripts that may be configured in the Actions file. The RAZOR_ACTION environment variable available to these scripts will be set to BUMP_BEFORE and BUMP_AFTER.² The major version can be set as well as associating the bump action to an issue.

Obtaining a full text copy of an issue

# razor -c get_issue -f <issue> [-v version] [-d dir] \
[-g <issue group>] [-z] [-o]

Issues are represented on disk as ASCII files which are managed by an archival engine to provide full change histories for the information on the form. It is possible to get a read only copy of this raw data for any incarnation of the issue form.

If the optional -v flag is not specified, then the program will get the most recent incarnation of the issue information. If the optional -d flag is provided, the output will be placed in the indicated directory, otherwise it will appear in the directory where the command was executed. The optional -o flag will force an overwrite of any pre-existing files. Use the -g option to retrieve issues from other than the default issues group.

To force output to stdout, use the optional -z flag.

Branching a file

You may branch a file from the command line with the following command,

# razor -c branch -f <file> -g <group> -t <title> \
[-v <version>] [-p <file>] [-i <issue[:<group>]>]

The current version of the file will be branched unless the optional -v flag is used, e.g. -v x.y, to branch version x.y of <file> that is currently at version, x.zz. A title is required to describe the branch action. A more lengthy description may be added with the -p option for the recorded history. And finally, an issue can be associated with this action with the optional -i option.

Comparing file attributes

There might be an instance where you have a need to compare the attributes of different Info files, possibly in scripts you've written where you wish to check changes in different versions of the same issue. You can perform a comparison of attributes or the state attribute values for different Info files by running the command


# razor compare <file1> <file2> \
<ATTRIBUTE | STATE <Attributes file>>

where <file1> and <file2> are the Info files to be compared (paths to the files may be either absolute or relative). You must specify which parameters you wish compared; either the ATTRIBUTE(s) or simply the STATE attribute values. If comparing the STATE attribute values, you must include the path to the Attributes file for the group. The output from this command will be directed to your terminal (or stdout).

¹ See "Roles" on page 267.
² See "Writing Your Own Shell Scripts" on page 219.


(Part 5 of 12 for this section) (Generated 09/13/99 at 18:01:58)