SYNTAX

CheckOut ([file1[,rev] [file2][,rev]… | -a | -newer] [-b]
[-c | -n | -y] [-cancel] [-cf commentFile | -cs comment] [-d directory]
[-date date | -m] [-deleteObsolete] [-history] [-noTouch | -touchOnly]
[-noWarn] [-obsolete] [-open] [-p] [-project project] [-r] [-t task]
[-u user] [-update] [-verify]) | -close | -w

DESCRIPTION

The CheckOut command allows you to obtain copies of file revisions from Projector. You can specify the files Projector checks out by using one of the following methods:

• specifying files individually by using the file1[,rev] [file2][,rev]… parameter

• specifying all files in the project (-a)

• specifying only the most recent revisions of all files in the project (-newer or -update)

• specifying an old revision that you want to modify (-b)

Projector normally checks out read-only copies of the specified files; however, you can override this to check out files for revision by using -m. For each revision Projector allows you to check in your comments on the changes you plan to make to the files or the tasks you want to accomplish. To do this, specify either the -cf, -cst, or -t options.

Along with keeping track of the project to which each file belongs, Projector remembers its checkout directory and places it there upon checkout. By default, Projector sets a file's checkout directory to the current directory when the project is initially mounted. You can use the -d option or the CheckOutDir command to specify a different checkout directory.

INPUT

None

OUTPUT

None, unless you request progress and summary information (-p).

ALIAS RESOLUTION

This command does not resolve Finder aliases that occur at the end of a pathname. If you specify a pathname for a file when you check it out, Checkout resolves any embedded folder aliases. Finder alias files are not resolved by Projector. This allows Projector to act on the Finder alias file itself, rather than its target.

STATUS

CheckOut can return the following status codes:

PARAMETERS

file1[,rev] [file2][,rev]…

Specifies one or more files to be checked out. Projector allows you to specify filenames in the following ways:

• As a leafname (that is, the final portion of a full pathname; for example, file.c). In this case, Projector checks out the latest revision of the file from the current project. If file specifies a revision (for example, file.c,22), that revision is checked out.

• As a partial or full HFS pathname (for example, :work:file.c or HD:work:file.c). In this case, Projector checks out the file (that is, file.c) in the current project and places the copy in the specified HFS location (that is, in the :work: or HD:work: directory).

• As a symbolic name. Projector expands the name and checks out the corresponding revisions. See the NameRevisions command for more information about symbolic names.

Note
Projector does not recopy files that you have already checked out. This is useful, for instance, when you only want to change the mode of a file from read-only to write-privileged. •

OPTIONS

-a

Checks out all the files in the current project.

-b

Creates a branch from which a write-privileged copy of the file is checked out. When you check the file back in, it becomes a branch of the revision that was checked out. For example, if you check out revision 4 of a file on a branch, Projector checks the file back in as revision 4a1.

-c

Prevents the display of any confirmation dialog boxes by automatically responding Cancel. The CheckOut command can produce confirmation dialog boxes in the following two situations: The first dialog box occurs when there is already a file in the checkout directory with the same name as the one you are trying to check out. In this case, the dialog box asks if you would like to overwrite the file.

The second dialog box occurs only when you use -cancel to cancel the checkout of one or more files. As a safety feature, CheckOut notifies you if you attempt to cancel someone else's checkout and asks if you would like to cancel the checkout anyway.

-cancel

Cancels the checkout of the specified files. When you do this, Projector changes the file from modifiable to read-only.

If you try to cancel the checkout of a file you do not own, Projector produces an alert box stating the identity of the file's owner. (See the -log option for ProjectInfo to examine all canceled checkouts.)

Projector also warns you if it is unable to find the specified files in the current checkout directory.

-cf commentFile

Retrieves the changes you proposed from the text file commentFile instead of from a string on the command line (-cs comment). This comment is stored in the 'ckid' resource of the files being checked out and is stored in the project when the files are checked in.

-close

Closes the Check Out window. Note that this window remains open until it is explicitly closed. (See also -w.)

-cs comment

Describes the changes proposed for the files in a string on the command line rather than in their own file (-cf commentFile). This comment is stored in the 'ckid' resource of the files being checked out and is stored in the project when the files are checked in.

-d directory

Places the files in the specified directory, overriding the checkout directory for the current project. This option resolves Finder aliases that occur at the end of a pathname. (See also CheckOutDir.)

-date date

Checks out copies of all the files in the project that were current on the date specified. This excludes files that have been checked out for modification, modified read-only files, and files that are on branches. Note that you cannot use this option when checking out files for modification.

If any of these files cannot be checked out, Projector generates a warning message, indicating the reason for the failure. See the description of the -newer option.

-deleteObsolete

Deletes files in the checkout directory that are marked obsolete in the project. When this sequence is complete and all files marked obsolete are deleted from the destination directory, the normal checkout sequence is followed.

-history

Stores all of the project history information--author, checkin date, task, and comment--in the 'ckid' resource for the all files checked out with that particular CheckOut command. The information, when stored using this option, can later be displayed without first having to mount the project by using the command ProjectInfo. (See also the -comments option for ProjectInfo.)

-m

Checks out a write-privileged copy of the file for modification. This locks the revision, preventing other users from inadvertently changing the revision.

-n

Prevents the display of any confirmation dialog boxes by automatically responding No. The CheckOut command can produce confirmation dialog boxes in the following two situations. The first dialog box occurs when there is already a file in the checkout directory with the same name as the one you are trying to check out. In this case, the dialog box asks if you would like to overwrite the file.

The second dialog box occurs only when you use -cancel to cancel the checkout of one or more files. As a safety feature, CheckOut notifies you if you attempt to cancel someone else's checkout and asks if you would like to cancel the checkout file anyway.

-newer

Checks out the latest copy of all files in the project. This excludes files that have been checked out for modification, are modified read-only, or are on branches.

You cannot use this option when checking out files for modification.

Projector generates error messages if it fails to check out one or more files under -newer or -update. These messages explicitly indicate the reason for the failure and, except for the following two, are self-explanatory.

NOT checked out: Your file <name> is a modified read-only file.

WARNING: Your file <name> is not part of the project.

Projector issues the first of the above warnings only if the modified read-only file is not the latest revision.

The second warning message occurs when a DeleteRevisions command has completely removed all revisions of your file from the Projector database and another file bearing the same name has been checked into the project.

-noTouch

Does not reset the modification date of files to the current date before checking them out. Projector normally sets the modification date of the file to the current date when they are checked out. Note that this option is incompatible with the -touchOnly option. (See -touchOnly.)

-noWarn

Prevents the "no files in project" warning from being reported.

-obsolete

Checks out a read-only version of an obsoleted file. If a specific revision number is required, you must specify it as part of the filename, for example, file.c,27.

-open

Opens the files after checking them out. This works only on 'TEXT' files.

-p

Writes progress information to standard output. If you specify -verify in conjunction with -p, Projector confirms that the verification succeeded.

-project project

Checks files out of the specified project. This overrides the default in which Projector automatically checks files out of the current project. (The current project is analogous to the current working directory; you can determine it or set it with the Project command.)

-r

Executes CheckOut recursively on the current project and all of its subprojects.

-t task

Describes briefly in the string task the task proposed for the revisions (for example, "Fix Bug 7").

-touchOnly

Checks out and resets the modification date to the current date of only those members of a named set of revisions (previously defined using the NameRevisions command) that are not already in the checkout directory. This condition would exist if they had been already checked out when you checked out the rest of the set. Note that this option is incompatible with the -noTouch option. (See -noTouch.)

-u user

Identifies the name of the current user. You must use this option if the MPW Shell variable {User} is not set or is a null string. Using this option allows you to override this variable's definition.

-update

Updates all read-only copies of files in the project that are in the checkout directory (or the -d directory) to the latest revision. Files that are not in the checkout directory or are not read-only files are not updated.

This excludes files that have been checked out for modification, modified read-only files, and files that are on branches. Note that you cannot use this option when checking out files for modification.

If any of these files cannot be checked out for updating, Projector generates a warning message, indicating the reason for the failure. See the description of the -newer option.

-verify

Verifies the checkout and alerts you in the case of any loss of data (due, for instance, to a data transmission error). If you specify this option, CheckOut compares the original files with the files that were checked out. If there are any differences, CheckOut writes an error message to diagnostic output, and returns a status of 2.

If you specify -p in conjunction with this option, Projector emits a message confirming that the verification succeeded.

-w

Opens the Check Out window shown below. You can use this window as an alternative to specifying the file1[,rev] [file2][,rev]… parameters and CheckOut options on the command line.

Note that this window remains open until it is explicitly closed and that it can be resized and moved to any position on the screen. The -close option can be used to close this window from the command line.

-y

Prevents the display of any confirmation dialog boxes by automatically responding Yes. The CheckOut command can produce confirmation dialog boxes in the following two situations: the first dialog box occurs when there is already a file in the checkout directory with the same name as the one you are trying to check out. In this case, the dialog box asks if you would like to overwrite the file. The second dialog box occurs only when you use -cancel to cancel the checkout of one or more files. As a safety feature, CheckOut notifies you if you attempt to cancel someone else's checkout and asks if you would like to cancel the checkout anyway.

EXAMPLES

The following command line checks out the latest revision of file.c for modification from the current project and places the file in the checkout directory for the project. If you already happen to have the latest revision of file.c in the checkout directory, Projector updates only the 'ckid' resource of file.c to indicate that it is now a modifiable file.

CheckOut file.c -m

The command line below checks out a write-privileged copy of the latest revision of file.c from the ProjectSubProjectSources project. Projector places the file in the checkout directory for the project.

CheckOut file.c -m -project Project∫SubProject∫Sources

The following command checks out a read-only copy of revision 22 of file.c from the ProjectSubProjectSources project. Projector places the file in the checkout directory for the project.

CheckOut file.c,22 -project Project∫SubProject∫Sources

Setting the current project with the Project command allows you to execute Projector commands without specifying the project. The following script sets the current project to ProjectSubProjectSources before placing file.c in the {MPW} Projects: directory. Setting the task lets other users see why you have checked out file.c.

Project Project∫SubProject∫Sources
CheckOut file.c -t "Fix Bug 7" -m -d "{MPW}Projects:"

The following command line checks out read-only copies of all the files in the current project and places the copies in the {MPW}Projects: directory:

CheckOut -a -d "{MPW}Projects:"

By using the -r option to perform recursive checkouts, the following command line checks out read-only copies of all files in myProject and all of its subprojects.

CheckOut -a -project myProject∫ -r

Its behavior is the same as if you executed the following commands individually:

CheckOut -a -project myProject∫
CheckOut -a -project myProject∫SubProjectA
CheckOut -a -project myProject∫SubProjectB
CheckOut -a -project myProject∫SubProjectB∫SubSubProjectA

You can conveniently update the read-only files (from the current project) in the current directory without affecting any files checked out for modification. To do this, use -update or -newer:

CheckOut -update -d :

You can keep a copy of all the project information in the 'ckid' resource for the specified file by using the -history option.

CheckOut -history file.c

Storing the project history in the 'ckid' resource of file.c subsequently allows Projector to display information for that file without having to mount the project first.

SEE ALSO

CheckIn

CheckOutDir

NameRevisions

Project

ProjectInfo