******************************************* * SOURCEOFFSITE COMMAND LINE CLIENT 3.5 * ******************************************* 1. OVERVIEW =========== The SourceOffSite Command Line Client provides remote source code control for use in scripts. It supports all the major operations required for source control, and is designed primarily for use by configuration managers or developers writing build scripts for automated source control processing. It is possible to use soscmd as a generic remote access utility, but its command line interface and inability to process more than one command at a time will likely limit its effectiveness in being more than a scripting tool. Soscmd processes a single command at a time, and all input parameters must be specified for each command. It does not save any state information or have a session interface. Since it is primarily a scripting tool, it never prompts for needed information, and sends all output messages to standard out. However, this also means that passwords must be entered at the command line in the clear. Therefore, it is necessary to ensure that script files containing soscmd commands have appropriate permissions. Since soscmd is a scripting tool that never prompts, it will happily overwrite existing files with the same name without prompting, even if the files are read-only. This is normally the desired behavior for a scripting tool, since files are extracted as read-only. 2. SPECIFYING THE "SOURCEOFFSITE HOME DIRECTORY" ================================================ Some abilities of the Version 3.5 Command Line Client depend on the presence of the SourceOffSite GUI Client on the machine. If using the Command Line Client with encryption, the GUI Client must be installed on the same machine (please see the Encryption section below for more details). The SourceOffSite home directory is created when the GUI Client is installed. This is the directory where imported encryption keys are stored along with file and project information. If the SourceOffSite home directory is specified, the Command Line Client will use the same cache file (databaseX.sos) as the GUI Client to determine file status and working directories. Specifying the SourceOffSite home directory will speed up large file retrieval operations, such as GetProject and CheckOutProject, as only files that need to be updated will be retrieved. Files that you have locally that have not changed in the database will not be retrieved. If a SourceOffSite home directory is not specified, the Command Line Client will retrieve ALL files during project retrieval operations. If the SourceOffSite home directory is specified, the Command Line Client will also look to the cache file to determine working directories. In such a case, by default the working directories set up in the GUI Client will be used by the Command Line Client. The path to the SourceOffSite home directory can be specified using the -soshome parameter on a command by command basis or the path can be specified by setting a SOSHOME environment variable. The default location for the SourceOffSite home directory on Windows is Program Files > SourceOffSite. On Unix, the name of the SourceOffSite home directory is ".sos", and its default location is in the user's Unix home directory. - IMPORTANT NOTE ON USING THE SOURCEOFFISTE HOME DIRECTORY - In order for proper functioning, if you will be specifying the path to the SourceOffSite home directory when using the Command Line Client, the SourceOffSite GUI Client must be upgraded to Version 3.5. Also, since both the GUI Client and the Command Line Client will be writing to the same SourceOffSite home directory, both Clients should not be run simultaneously. 3. ENCRYPTION ============== In order to enable the Command Line Client to connect to the Secure port and use encryption, the SourceOffSite GUI Client must be installed on the same machine. The Command Line Client will use the same User Key that has been imported into the GUI Client to authenticate the secure connection. Information on creating and importing User Keys can be found in our on-line documentation at the following links: http://www.sourcegear.com/SOS/Doc/Server#USER KEYS http://www.sourcegear.com/SOS/Doc/Installing#RUN SOS CLIENT The Command Line Client will use encryption or not depending on the port that it connects to. Please contact your SourceOffSite Administrator to find out which ports are being used for secure and unsecure connections. If the Command Line Client connects to the secure port, it will look for a User Key in the SourceOffSite GUI Client's home directory. In order to use encryption, the path to this directory must be specified using the -soshome parameter or by setting a SOSHOME environment variable. If the Command Line Client connects to the unsecure port, no encryption will be used and all data will be sent in the clear. 4. SOSCMD PARAMETERS ===================== Soscmd takes a large number of parameters in order to specify a complete SourceOffSite transaction. The parameters accepted by soscmd are listed below. It is not necessary to enter full parameter names, but the parameters need to be specified fully enough to be unique. For example, -p will randomly choose either -password or -project as the parameter entered. Parameter Value -------- ----- -command The SourceOffSite command to process. Commands are listed in the next section of this document. -soshome The path to the SourceOffSite home directory (if the SourceOffSite GUI Client is installed). -nocompress Turns off compression. By default, the Command Line Client will use compression for all data transfers. -nocache If present, prevents the Command Line Client from using the SourceOffSite cache file (databaseX.sos) when retrieving files when SOSHOME is specified. Use of this parameter will force the Command Line Client to retrieve ALL files, regardless of whether the files have changed or not. -server The domain name or IP address and port of a running SourceOffSite server in the form "servername:port" -database A valid SourceSafe database that the SOS Server has access to. This path is specified under the Databases tab of the SourceOffSite Server Manager utility. -name The SourceSafe user name used for logging into the SourceOffSite Server. -password The SourceSafe password corresponding to the user name specified by the -name parameter. -project A valid SourceSafe project in the database specified by the -database parameter. -file A valid SourceSafe file in the project specified by the -project parameter. -revision A version number of the file specified. -verbose If present, outputs verbose status messages, such as connections, server responses, etc. to standard out. -log Text used for comments. -workdir The working directory where the Command Line Client places a fetched SourceSafe file or project. This parameter is also used to specify where on the local machine the Command Line Client looks for a file or project to add or check in to the database. The local working directory can be an absolute or relative path. -label A label that can be associated with a particular project version. -recursive If present, the project level command will be performed recursively. -newname Used with the Rename command. The new name of a project or file that is being renamed. -shareto Used with the ShareFile and ShareProject commands. The project into which a file or project will be shared. -branch Used with the ShareFile and ShareProject commands. If present, will perform a branch operation immediately after the share. -permanent Used with the delete command. Permanently deletes a file or project from the database. 5. SOSCMD COMMANDS ================== The commands below are recognized by the SOS Command Line Client, when preceded by the "-command" parameter. Please note that a SourceOffSite home directory must be specified to connect to the secure port and use encryption. - NOTE ON WORKING DIRECTORIES - Working directories in the Version 3.5 Command Line Client function as follows: If the path to the SourceOffSite home directory is specified by the -soshome parameter or SOSHOME is set as an environment variable, the Command Line Client will look for the project or file in, or fetch the project or file to, the working directory set in the GUI Client. If the -workdir parameter is specified, the Command Line Client will use that working directory. Otherwise, the Command Line Client assumes the current directory. - OPTIONAL PARAMETERS THAT CAN BE USED WITH ALL COMMANDS - Although not specified in the command descriptions below, the following optional parameters can be used with any command: -soshome -nocache -nocompress Please note that the -nocache parameter is not needed unless SOSHOME is set as an environment variable. By default, if the -soshome parameter is not passed to the command or the SOSHOME environment variable is not set, the Command Line Client will not use the cache file. For this reason, when the -soshome parameter is used the -nocache parameter should not be used. - GetDatabases - Lists all databases accessible by the input server. Required Params: -server - GetProjectTree - Gets the project tree rooted at the input project, or root project if none specified and outputs to standard out. This command returns the structure of the project in the VSS database. If a SourceOffSite home directory is specified, this command will also update the project tree in the local cache file. Please note that this command does not retrieve the files in the project. Required Params: -server -name -password -database Optional Params: -project - GetFileList - Gets a list of all files in the input project. This command outputs the name, version and check in date of each file to standard out. Required Params: -server -name -password -database -project - CreateProject - Creates an empty project in the VSS database whose full name is specified by the -project parameter. Required Params: -server -name -password -database -project Optional Params: -log - AddFolder - Adds an entire project to the database. The path to the project on the local machine is specified by the -workdir parameter. Specifying -recursive adds the entire project tree under the project, creating directories as necessary. Required Params: -server -name -password -database -project -workdir Optional Params: -recursive - AddFile - Adds a file to a project. If a working directory is not specified (please see the Note on Working Directories above for information on how working directories function), the Command Line Client will assume the current directory or the file is a full pathname. Required Params: -server -name -password -database -project -file Optional Params: -workdir -log - GetFile - Gets a file from the SourceSafe database. It will get the latest revision of a file unless the -revision parameter is used to specify a previous file version. Since the GetFile command does not check the file out, it sets the permission on the file to read-only. Please note that this operation overwrites a file with the same name, regardless of permissions. Required Params: -server -name -password -database -project -file Optional Params: -workdir -revision - GetProject - Gets all of the files in a project. It will get the latest revision of the files in a project unless the -label parameter is used to specify a previous version of a project. This operation overwrites existing files with the same name, regardless of permissions. Specifying -recursive gets the entire project tree under the project, creating directories as necessary. Required Params: -server -name -password -database -project Optional Params: -label -workdir -recursive - CheckOutProject - Checks out and locks an entire project. This command also makes the local files in the project writable. Specifying -recursive checks out the entire project tree under project, creating directories as necessary. Required Params: -server -name -password -database -project Optional Params: -workdir -recursive - CheckOutFile - Checks out and locks a file. This command also makes the local file writable. Required Params: -server -name -password -database -project -file Optional Params: -workdir - CheckInProject - Checks in and unlocks an entire project. This operation also makes the files in the project read-only after a successful check in. Specifying -recursive checks in the entire project tree under the project. Required Params: -server -name -password -database -project -file Optional Params: -workdir -recursive -log - CheckInFile - Checks in and unlocks a file. This operation also makes the file read-only after a successful check in. If a working directory is not specified (please see the Note on Working Directories above for information on how working directories function), the Command Line Client will assume the current directory or the file is a full pathname. Required Params: -server -name -password -database -project -file Optional Params: -workdir -log - UndoProjectCheckout - Cancels the checkout of a project by overwriting the files in the project with the latest version under source control. This operation also makes the files in the project read-only. Specifying -recursive will undo the checkout of the entire project tree under the project. Required Params: -server -name -password -database -project Optional Params: -workdir -recursive - UndoCheckOut - Cancels a checkout by overwriting the file with the latest version under source control. Also makes the file read-only. If a working directory is not specified (please see the Note on Working Directories above for information on how working directories function), the Command Line Client will assume the current directory or the file is a full pathname. Required Params: -server -name -password -database -project -file Optional Params: -workdir - GetFileHistory - Gets the revision history of the given file. Required Params: -server -name -password -database -project -file - ShareFile - Enables the current version of a file to be shared with another project. Updates to a shared file will be reflected in all the projects to which the file is shared. Required Params: -server -name -password -database -project -file -shareto Optional Params: -branch -log - ShareProject - Enables the current version of a project to be shared with another project. Updates to files in a shared project will be reflected in all the projects to which the project is shared. Specifying -recursive will share the files in entire project tree under the project. Required Params: -server -name -password -database -project -shareto Optional Params: -branch -log - BranchFile - This command will break the share link and the changes made to that file will no longer be reflected in other projects. Required Params: -server -name -password -database -project -file Optional Params: -log - BranchProject - This command will break the share link for all the files in a project. Changes made to the files in that project will no longer be reflected in other projects. Specifying -recursive will break the share link for all of the files in the entire project tree under the project. Required Params: -server -name -password -database -project Optional Params: -recursive -log - AddLabel - This command will add a label to a project. Required Params: -server -name -password -database -project -label Optional Params: -log - Delete - Deletes a file or project. If the -permanent flag is set, it will delete the file or project permanently from the database so it cannot be recovered. This command does not delete the file or project from the local machine. Required Params: -server -name -password -database -project Optional Params: -file -permanent - Rename - Renames a file or project in the VSS database. This command does not rename the file or project on the local machine. Required Params: -server -name -password -database -project -newname Optional Params: -file - GetFileInfo - Gets current information about a file. Outputs the file version and remote date to standard out. If a file is checked out, it will also display the user who has the file locked. Required Params: -server -name -password -database -project -file 6. EXAMPLES =========== - NOTES ON EXAMPLES - * These examples assume the Command Line Client is run on a Windows machine. If running the Client on a UNIX machine, the backslashes in the path to the database should be escaped. Some example database paths on UNIX would be as follows: c:\\VSS\\srcsafe.ini \\\\server\\vss\\srcsafe.ini * Any spaces in any command parameter value must be surrounded by quotes. For example: -database "c:\program files\vss\srcsafe.ini" -label "Version 1" -log "Fixed the problem" Example 1: Get a list of files ------------------------------ The command below gets the list of files in the "$/projects/apollo/src" project in the SourceSafe database on a machine named garcon running a SOS Server on port 8888. soscmd -command GetFileList -server garcon:8888 -name joe -password camel -database c:\VSS\srcsafe.ini -project $/projects/apollo/src Returns: Source1.h Source1.c Source2.h Source2.c Example 2: Get a file --------------------- This places the latest version of the file "source1.h" into "c:\projects\apollo\src" on the local machine. soscmd -command GetFile -server garcon:8888 -name joe -password camel -database c:\VSS\srcsafe.ini -project $/projects/apollo/src -file source1.h -workdir c:\projects\apollo\src Example 3: Check out a file --------------------------- This checks out the latest version of the file "source1.h" and places it into the working directory set in the GUI Client. soscmd -command CheckOutFile -server garcon:8888 -name joe -password camel -database c:\VSS\srcsafe.ini -project $/projects/apollo/src -file source1.h -soshome "c:\Program Files\SourceOffSite" Example 4: Check in a file --------------------------- This checks in the previously checked out file "source1.c", located on the local machine at "c:\projects\apollo\src". soscmd -command CheckInFile -server garcon:8888 -name joe -password camel -database c:\VSS\srcsafe.ini -project $/projects/apollo/src -file c:\projects\apollo\src\source1.c -log "Added function HelloWorld()" Example 5: Retrieve all files in a project tree by a label ---------------------------------------------------------- This example gets a previous version of a project from a label. It retrieves all of the files in the project associated with that label, placing them in the current directory or in the working directory set up in the GUI Client if the SOSHOME environment variable is set. It will create directories as needed. soscmd -command GetProject -server garcon:8888 -name joe -password camel -database c:\VSS\srcsafe.ini -project $/projects/apollo/src -label "version 1" -recursive Example 6: Add a project to the database ---------------------------------------- The command below adds an entire project located at "c:\projects\new" on the local machine to the project "$/projects/apollo/src" in the VSS database. soscmd -command AddFolder -server garcon:8888 -name joe -password camel -database c:\VSS\srcsafe.ini -project $/projects/apollo/src/new -workdir c:\projects\new -recursive Example 7: Label a project -------------------------- The command below applies the label "Build 4" to project "$/projects/apollo" in the VSS database. soscmd -command AddLabel -server garcon:8888 -name joe -password camel -database c:\VSS\srcsafe.ini -project $/projects/apollo -label "Build 4" Example 8: Share a project with another project ----------------------------------------------- This shares the current version of the project "$/projects/apollo/src" with the project "$/projects/sun" in the VSS database. soscmd -command ShareProject -server garcon:8888 -name joe -password camel -database c:\VSS\srcsafe.ini -project $/projects/apollo/src -shareto $/projects/sun -log "Sharing project Src into project Sun" Example 9: Branch a shared project ---------------------------------- This branches the project "$/projects/apollo/src" which was previously shared with another project in the VSS database. soscmd -command BranchProject -server garcon:8888 -name joe -password camel -database c:\VSS\srcsafe.ini -project $/projects/apollo/src Example 10: Delete a project permanently ---------------------------------------- The command below deletes project "$/projects/apollo/src" permanently from the VSS database. soscmd -command Delete -server garcon:8888 -name joe -password camel -database c:\VSS\srcsafe.ini -project $/projects/apollo/src -permanent 7. RETURN CODES =============== -1 Generic Error 200 Unsecure Challenge 201 Project Tree 202 File List 203 File 204 File History 205 File Info 250 Secure Challenge 300 Success 301 Check in Complete 302 File Unlocked 303 File Added 304 File Locked 400 Operation Failed 401 No Such File Or Project 402 File Or Project Not Locked 403 Auth Failed 404 Missing Header 405 Invalid Label 406 Invalid Version 407 Unrecognized Msg 408 Invalid Protocol Version 409 File Or Project Already Exists 410 File Or Project Already Locked 411 Unathorized User 412 Server Expired 413 Key Not Found 414 Key Expired 415 Invalid Key 416 Bad Ini File 417 Missing SS Auto 418 Missing Crypto 420 Failed Database Open