Cascade 1.2.0.1069 Manual: The Cascade Command Line Client

Introduction to the Command Line Client

Cascade provides a command line client called csc. This client is analogous to the command line clients like svn and p4 for the underlying repositories that Cascade communicates to. However, whereas each repository's own dedicated client has a slightly different set of commands, Cascade's csc client application is the same for all repository types.

csc does not aim to completely replace these other client applications. You may still want to make queries directly to the underlying repository for any number of reasons. Instead, csc aims to supply the basic "least common denominator" functionality that all repositories require, plus access to the added functionality that Cascade provides such as cloning and checkpointing.

Note that there is no Cascade equivalent to commands such as svn add or svn delete. As a file system driver, CFS automatically knows when files are being added or deleted; you don't have to tell it about these files.

Many of these commands apply to the "current" tree. This is determined by the working directory of the shell you launch the client from. For example, if you are currently in the /mnt/cfs/tree/svn/trunk directory, /mnt/cfs/tree would be the current tree.

You can also type cascade instead of csc. This longer alias is available in case another program earlier in your PATH is also named csc.

Authentication and Authentication Caching

The first time you set up a mount point for a particular repository, you will be prompted for credentials (username and password). The prompt looks like this:

Need credentials for URL 'svn-http://svn.collab.net/repos/svn': Username:

Some servers allow anonymous access, usually read-only; in this case, simply hitting Enter twice to provide an empty username and empty password will do. Note that you may not be allowed to commit with anonymous credentials, so if you have a real username and password, you should generally use it.

Once you've entered your credentials for a given repository, they will be remembered in a file under the directory .csc/auth in your home directory, e.g., ~/.csc/auth on Unix and C:\Documents and Settings\username\.csc\auth on Windows. Note that these files, which contain our usernames and passwords, are stored as plain text. On Unix-based systems like Linux and Macintosh, the .csc directory will be created with permissions such that other users cannot read it. On Windows, Cascade assumes is that you have properly secured your home directory by other means, either by being the only person with access to your computer or by having set up the correct permissions.

Sometimes Cascade will prompt for credentials for a repository whose name starts with csc-http://. This is a prompt for your Cascade Manager credentials.

The cached credentials do not time out. If you change your username or password, or if you want to use different credentials, you can delete the entire .csc/auth directory, e.g., rm -rf ~/.csc/auth.

csc apply

Applies a previously checkpointed changeset to a non-Cascade-based tree, e.g., a Subversion tree. This provides a way to move changes originally developed in Cascade back into other systems.

Usage:

csc apply -svn|-p4|-ab <id>

-svn: Apply to a Subversion tree.
-p4: Apply to a Perforce tree.
-ab: Apply to an Alienbrain tree.

<id>: The ID of the checkpointed changeset to apply.

csc blame

Shows the most recent change that modified each line in a file in a Cascade tree. The first column shows the revision number of the change, while the second column shows the change's author.

Usage:

csc blame <path>

csc checkpoint

Creates a checkpoint from the current tree and uploads it to Cascade Manager.

Usage:

csc checkpoint [-d <description>] [-n <name>] [<path> [<path2> ...]]

The optional -d argument specifies a description to use for the checkpoint. This description is persistent in any given tree, so a subsequent checkpoint, launch, or commit will pick up the same description if no -d argument is used.

The optional -n argument specified a symbolic name to use for the checkpoint. This name must be unique (no two checkpoints can have the same name) and can be used to clone from the checkpoint.

If no paths are specified, all modified files are checkpointed. If one or more paths are specified, only those files will be checkpointed.

csc clone

Clones a new Cascade tree rooted at <path> at a particular revision. The tree's revision can be explicitly specified as a number (which may be a checkpointed changeset, e.g., 5.1 for checkpoint 1 relative to revision 5), the name of a named checkpoint, or one of two automatically determined revisions, last_known_good and latest.

The last_known_good revision is the most recent revision where all tasks have completed and passed. Cloning from last_known_good ensures that the tree passes some minimum quality bar.

The latest revision is the most recent revision, regardless of its testing status.

Usage:

csc clone <path> [<revision>|last_known_good|latest]

csc commit

Creates a checkpoint from the current tree and uploads it to Cascade Manager, kicks off all tasks affected by the changes, waits for those tasks to complete, and then commits the change to the repository.

Usage:

csc commit [-d <description>] [-n <name>] [<path> [<path2> ...]]

The optional -n argument specified a symbolic name to use for the checkpoint. This name must be unique (no two checkpoints can have the same name) and can be used to clone from the checkpoint.

If no paths are specified, all modified files are checkpointed. If one or more paths are specified, only those files will be checkpointed.

csc diff

Shows what changes have been made to a file in a Cascade tree.

This command relies on an external diff program specified in the CSC_DIFF configuration variable. CSC_DIFF contains a template for a command line used to launch that program, where %B is replaced by the path to the "baseline" file and %Y is replaced by the path to "your" file. If CSC_DIFF is not set, its default value is diff -u %B %Y.

The Windows installer for Cascade sets CSC_DIFF to launch the TortoiseMerge diff program.

Usage:

csc diff <path>

csc help

Usage:

csc help [<command>]

csc help by itself will give you a list of supported commands. csc help <command> will give you more information about a specific command.

csc launch

Creates a checkpoint from the current tree and uploads it to Cascade Manager, then kicks off all tasks affected by the changes.

Usage:

csc launch [-d <description>] [-n <name>] [<path> [<path2> ...]]

The optional -n argument specified a symbolic name to use for the checkpoint. This name must be unique (no two checkpoints can have the same name) and can be used to clone from the checkpoint.

If no paths are specified, all modified files are checkpointed. If one or more paths are specified, only those files will be checkpointed.

csc lock

Locks one or more files <path>, <path2>, etc., preventing other users from committing changes to them. Only one user can hold a lock to any given file at a time. Only administrators can forcibly break locks, i.e., unlock a file locked by another user.

Usage:

csc lock [-m <message>] <path> [<path2> ...]

The optional -m argument specifies a lock message explaining to other users why the files were locked.

csc log

Shows the history of changes to a file in a Cascade tree.

Usage:

csc log <path>

csc merge

Merges your changes to a file in a Cascade tree with other people's changes to the same file. This is often required after running csc update.

This command relies on an external diff program specified in the CSC_MERGE configuration variable. CSC_MERGE contains a template for a command line used to launch that program, where %B is replaced by the path to the "baseline" file, %Y is replaced by the path to "your" file, %T is replaced by the path to "their" file, and %O is replaced by the path to the output file. If CSC_MERGE is not set, its default value is diff3 -m %Y %B %T >%O.

The Windows installer for Cascade sets CSC_MERGE to launch the TortoiseMerge diff program.

If the -s option is specified, marks a file as not needing to be merged, without launching an external merge utility. This effectively wipes out the other users' changes to the file in favor of your own changes.

Usage:

csc merge [-s] <path>

csc mode

Gets or sets the mode (text or binary, executable or not, various other flags) of a file in a Cascade tree.

chmod can also be used to set the executable mode of a file on Unix operating systems. This command provides a portable means of setting the executable mode for systems that do not have a chmod command. It also provides a portable means of discovering that a file is a symbolic link on platforms not supporting symbolic links.

Usage:

csc mode <path> csc mode <path> text|binary|+executable|-executable|+needs_lock|-needs_lock

The first form gets the various mode flags of file <path>. This is a comma-separated list of strings, which may include any of the following:

directory: The file is a directory symlink: The file is a symbolic link text: The file is a text file binary: The file is a binary file executable: The file is executable read_only: The file is read-only hidden: The file is a special "hidden" file needs_lock: The file must be locked in order to edit it locked: The file is locked in this tree

The second form sets the mode of file <path>. text sets it to being text, and binary sets it to being binary. +executable sets it to being executable, and -executable sets it to not being executable. +needs_lock sets it to requiring a lock in order to edit it, and -needs_lock sets it to not require a lock.

csc mount

Gets, creates, or updates mount points in a Cascade tree.

Usage:

csc mount csc mount <path> <URL> <revision>

The first form prints all the mount points in the current tree. Each line in the output has three fields: the path to the mount point, the URL of the repository the mount point refers to, and the revision that mount point is set to.

The second form creates a new mount point at <path> or updates an existing mount point at <path>. If <path> does not exist, it will be created and pointed at repository <URL> at revision <revision>. If it already exists, <URL> is ignored and its revision is updated to <revision>.

<revision> may be latest, in which case the mount point's revision is set to the repository's most recent revision.

Using csc clone and csc update is recommended over setting up mount points manually with csc mount.

csc newline

Gets or sets the newline mode of a Cascade tree.

Two newline modes are supported: unix and windows. Only those files marked as text files using csc mode are affected by newline translation. (By default, newly created files are considered binary.)

In unix mode, when a text file is uploaded as part of a checkpoint, its newlines are translated from Windows style (CR LF) to Unix style (LF). No newline translation is performed when files are downloaded.

In windows mode, when a text file is downloaded, its newlines are translated from Unix style (LF) to Windows style (CR LF). When it is uploaded, they are translated from Windows style (CR LF) to Unix style (LF).

Usage:

csc newline csc newline <mode>

The first form prints the newline mode of the current tree.

The second form sets the newline mode of the current tree.

csc revert

Backs out unwanted changes to a Cascade tree.

Usage:

csc revert <path> [<path2> ...]

This command reverts one or more edited files <path>, <path2>, etc. back to their original state in the repository. If <path> is a directory, the revert is recursive, applying to all files and subdirectories underneath <path> as well.

csc status

Shows what files and directories have been modified in the current Cascade tree, including information on which ones the user needs to merge to make the tree consistent. Also shows the human-readable description of the changes, if one has been provided.

If a path is specified, only changes under that path are listed.

Usage:

csc status [<path>]

csc unlock

Unlocks one or more files <path>, <path2>, etc., allowing other users to commit changes to them again. Only administrators can forcibly break locks, i.e., unlock a file locked by another user.

Usage:

csc unlock <path> [<path2> ...]

csc update

Updates the current (previously cloned) Cascade tree to a new revision. The revision can be explicitly specified as a number, or it can be one of two automatically determined revisions, last_known_good and latest. The meaning of these revisions is the same as the meaning used by the clone command.

This command can only be used on trees created via csc clone. It does not support trees created manually via csc mount. If you want to update a tree created via csc mount, you can reissue the csc mount command with a new revision number.

Usage:

csc update <revision>|last_known_good|latest

Comments or questions about the manual? Please email info@conifersystems.com with your feedback.

Cascade contains valuable trade secrets and other confidential information belonging to Conifer Systems LLC. This software and its associated documentation may not be copied, duplicated or disclosed to third parties without the express written permission of Conifer Systems LLC.

Cascade 1.2.0.1069 Manual: The Cascade Command Line Client

Table of Contents:

Introduction to the Command Line Client

Authentication and Authentication Caching

csc apply

csc blame

csc checkpoint

csc clone

csc commit

csc diff

csc help

csc launch

csc lock

csc log

csc merge

csc mode

csc mount

csc newline

csc revert

csc status

csc unlock

csc update