si createsandbox

CLI Reference > Configuration Management Commands > si createsandbox

si createsandbox

creates a new Sandbox on your local machine

Synopsis

Description

si createsandbox creates a new Sandbox on the client machine in a specified directory. When you want to work with a project, you create a Sandbox. A Sandbox resides on your local drive and is a mirror image of the project. Working in a Sandbox allows you to operate in your own workspace without interfering with the work of others. Once a Sandbox is created, you can add files or members to that Sandbox. The project is then updated to reflect the addition of new project members.

Different types of sandboxes are available for different types of development. Normal sandboxes are useful for the sequential development of a project over the long or short term. Variant sandboxes are useful for branching off the main development path. Build sandboxes are useful for testing a specific checkpoint of the project.

Using the Current Configuration

If you want to create a new Sandbox based on a subproject, then by default, the si createsandbox command uses the current configuration of that project, whether that is normal (the mainline), variant, or build.

Using Normal (Mainline)

You can force the new Sandbox to reference the mainline by specifying the configuration for the project and appending the special token #n= to the configuration path. This effectively forces a jump to the mainline and is the best method for ensuring a well-formed development path.

For example, assume the following project structure:

• Top level project /Top on the mainline

• Subproject /Top/Sub on the devpath

To create a subproject Sandbox on the development path:

si createsandbox --project="#/Top/Sub" sandbox

To create a subproject Sandbox on the mainline:

si createsandbox --project="#/Top/Sub#n=" sandbox

If the existing project configuration path is sufficiently complex (for example, if it contains explicit jumps between development paths), then appending #n= may not work, and you may need to provide a different, less complex configuration path to the mainline.

Using Variant Sandboxes

A variant Sandbox is based on a specific checkpoint of your project that has been branched off the main development path. When you create a variant Sandbox, you choose the development path to use. For example:

si createsandbox --devpath=MyVariant

In the variant Sandbox, you can see the current state of the project along that development path and the changes made by other developers using it. When a variant Sandbox is created for the first time, it is also created for all subprojects, reserving the assigned name as a unique identifier and ensuring no two paths can share the same name. For more information on creating development paths, see si createdevpath

Using Build Sandboxes

After major milestones, such as product releases, you might want to recreate a static version of an entire project as it existed at some point in the past. You create a build Sandbox, to build or test the project, not to begin further work along a new development path.

A build Sandbox is associated with a particular project checkpoint, and has no development path (since it is static and not meant for further development). For example:

si createsandbox --projectRevision=1.34

creates a build Sandbox based on the project checkpoint 1.34, and it cannot be modified.

With a build Sandbox, you cannot:

• check out, lock, or check in members

• remove or add members

• freeze or thaw members

• checkpoint the master project

• modify project or member attributes

• revert members

• set the member revision

However, with a build Sandbox, you can:

• change labels and states (see si addlabel)

• resynchronize your Sandbox (see si resync)

• compare a member revision in the build Sandbox to another revision (see si diff)

• merge a member revision (si merge) in the build Sandbox with another revision (of course, you cannot check that merged file back into the build Sandbox)

• check for differences between project checkpoints, (see si mods)

Specifying the Sandbox Scope

For large projects with mixed content, such as source code, simulation files, calibration files, and documentation, creating complete Sandboxes from these projects can impact Windchill RV&S Client performance and consume large amounts of network bandwidth. While you may need all components in the projects (subprojects), you may only need to work with certain subprojects, files, or file types.

Specifying a Sandbox scope allows you to define what subprojects, project members, or both subprojects and members are included in a Sandbox. A Sandbox scope transfers specific subprojects and/or members from the Windchill RV&S Server to the Sandbox directory when the Sandbox is created, and controls what initially displays in the Sandbox view. Specifying Sandbox scope can greatly improve the performance of the Create Sandbox operation, reduce network traffic, and make it easier to locate the relevant subprojects and/or members that you need to work with.

Changes to the scope definition are automatically reflected in the Sandbox view. Out of scope subprojects are automatically hidden from the view unless the corresponding folders exist on disk. Members with working files in the Sandbox that do not match the scope definition display deltas to indicate that they are out of scope. Performing a si resync or si revert removes the members and the out of scope subprojects from the Sandbox.

Note the following:

• When you define both subproject scope and member scope for a Sandbox, the member scope definition is combined with the subproject scope definition using a logical AND operation.

• The scope of a Sandbox is saved with the Sandbox and persists when the Sandbox or Windchill RV&S Client are closed and restarted. It is possible to have two Sandboxes of the same project with each one having a different Sandbox scope.

• For future Create Sandbox operations, you can use the si setprefs command to set the Sandbox scope for the si createsandbox command. The syntax for setting scope preferences is si setprefs --command=createsandbox scope="scopepreference".To specify a logical OR operator, separate the preferences with a comma. To specify a logical AND operator, type each scope preference on a separate line with no spaces before them.

• Defining Sandbox scope is different from filtering members using the view filters using the si viewsandbox command. Sandbox scope determines what subprojects and members are initially included in the Sandbox and are transferred to the file system when you resynchronize. View filters allow you to further filter which members are displayed in the Sandbox view. For example, if you create a scoped Sandbox that includes members with attribute name/value OS=Windows, your Sandbox only includes members that match that scope. You can then apply the Locked Members filter to your Sandbox to display only members that match the Sandbox scope and have a lock. Members of the project that have a lock but do not match your scope are not visible in the view.

• When you add new members that do not match the current Sandbox scope, the new member is added and the new member displays as an out of scope member in the Sandbox. However, when you add new subprojects using the Windchill RV&S client that do not match the Sandbox scope, the new subproject is not visible in the Sandbox view because the folder is not created on disk. A new folder is created on disk and visible in the Sandbox view when you create a new subproject using the CLI.

• Other operations can result in subprojects or members in the Sandbox that do not match the current Sandbox scope. For example, you can resynchronize change packages using --resyncIfOutOfScope to resynchronize both in scope and out of scope subprojects and members. You can also modify a member so that it no longer matches the Sandbox scope, or update the Sandbox scope definition.

• For commands that include the --filter option, you can specify subprojects or members that do not match the current Sandbox scope definition. For example, you can display the subprojects and/or members in your Sandbox that do not match the current scope (si viewsandbox --filter=outofscope), or resynchronize subprojects and/or members in your Sandbox that do not match the current scope (si resync --filter=outofscope).

• The --scope and --[no]sparse options are independent of one another. For example, you can create a sparse scoped Sandbox.

• While specifying the scope, if multiple subdirectories having quotes in the name are OR’d together, then scoped sandbox gets created without subdirectories. However, if only a single subdirectory is mentioned whose name has quotes, then the scoped sandbox with subdirectory will be created.

Options

This command takes the universal options available to all si commands, as well as some general options. See the options reference page for descriptions.

defines what subprojects, members, or both subprojects and members are included in the Sandbox, and transfers specific members from the Windchill RV&S Server to the Sandbox directory.

You can include or invert (!) one or more of the following options:

◦ --scope=subproject:subprojectConfigurationPath

specifies one or more subprojects, where the subproject name is relative to its parent. Subproject scope cannot be inverted.

To avoid potential ambiguities, the subproject name must specify the subproject using a Sandbox-relative source configuration path. PTC recommends that you use explicit non-compact keyword string syntax to match the path definition defined in the GUI instead of using compact hash syntax.

For example, the following source configuration path:

#s=sub/project.pj#s=sub2/project.pj#s=sub3/project.pj

is the same as the following compact source configuration path:

#sub/sub2/sub3 or #sub#sub2#sub3

however, the non-compact keyword string syntax is recommended to account for cases where project paths are not necessarily well-formed.

When specifying a Sandbox-relative source configuration path using keyword-based strings, the following keywords are not supported: #b/#build, #d/#devpath, or #n/#normal. See the options reference page for details on specifying source configuration management projects and for a description of all keywords.

To specify a logical OR operator, separate each option with a comma. For example, for project/project.pj, include subprojects with --scope=subproject:s#=sub1/project.pj, subproject:s#=sub2/project.pj to define the scope as including sub1 or sub2. This option is case-sensitive. Joining subproject scope clauses with a logical AND operator is not supported.

◦ --scope=attribute:name[=value] specifies project members with an attribute or an attribute set to a value. For example, include members with --scope=attribute:Beta or do not include members with --scope=!attribute:OS=Windows. This option is case-sensitive.

◦ --scope=path:expression specifies project members that reside in a directory, relative to the top-level Sandbox, for example, watch/lib/*. The specified path does not differentiate between subdirectories and subproject names. This means that you cannot specify individual co-located subprojects.

For example, if you create a scoped Sandbox from the following top-level project:

/p1/project.pj

with the following subprojects and members:

/p1/sub1/project.pj

/p1/sub1/aa.txt

/p1/sub1/bb.txt

/p1/sub1/dd.txt

/p1/sub2/project.pj

/p1/sub2/sub1/cc.txt

specifying --scope=path:sub1 matches /p1/sub1/aa.txt and /p1/sub1/dd.txt or specifying --scope=path:*sub1 matches /p1/sub1/aa.txt, /p1/sub1/bb.txt, /p1/sub2/sub1/cc.txt, and /p1/sub1/dd.txt.

If the client OS is a case-sensitive file system and the database repository on the server is case-sensitive, the --scope=path:expression and --scope=name:expression options are case-sensitive. Otherwise, these options are case-insensitive.

◦ --scope=name:expression specifies project members with a name or file extension. A name is only valid for a file name, not a leading directory prefix. For example, include members with --scope=name:Readme.txt or do not include members with --scope=!name:*.java.

◦ --scope=memberrevlabellike:expression specifies project members with a label at member revision. For example, include members with --scope=memberrevlabellike:TEST or do not include members with --scope=!memberrevlabellike:TEST. This option is case-sensitive and accepts wildcards (* and ?).

◦ --scope=anyrevlabellike:expression specifies project members with a label at any revision. For example, include members with --scope=anyrevlabellike:PROD or do not include members with --scope=!anyrevlabellike:PROD. This option is case-sensitive and accepts wildcards (* and ?)

◦ --scope=type:binary|text specifies project members that are a binary or text archive type. For example, include members with --scope=type:binary or do not include members with --scope=!type:text.

◦ --scope=any specifies all project members. This is the default setting.

Using Logical Operators to Define Sandbox Member Scope

You can also combine Sandbox member scope selections using logical AND or OR operators, and invert Sandbox member scope selections by preceding each selection with a ! character. For example, to transfer project members with the member attributes Alpha AND Beta, specify --scope=attribute:Alpha--scope=attribute:Beta. An OR operator is specified as a comma between values in a --scope option. For example, to transfer project members with member attributes Alpha OR Beta OR GA, specify --scope=attribute:Alpha,attribute:Beta,attribute:GA. You can combine logical operators to create more complex Sandbox scope selections. For example, to transfer project members with member attributes Alpha OR Beta OR GA AND name *.java, specify --scope=attribute:Alpha,attribute:Beta,attribute:GA--scope=name:*.java.

Using the si createsandbox and si configuresandbox commands, you can create and edit more complex Sandbox member scope definitions than the GUI using a combination of logical AND or OR operators; however, these definitions may not always be editable from the GUI. If you attempt to edit a complex member scope definition from the GUI, Windchill RV&S truncates the definition to what the GUI is capable of displaying. If you attempt to edit a complex member scope definition using the si configuresandbox -g/gui command, Windchill RV&S displays a warning message that choosing to edit the scope definition removes the options the GUI is not capable of displaying.

• --lineTerminator==[lf|cr|crlf|native]

explicitly identifies the characters to use as the line terminator for this Sandbox. lf is a line feed character, crlf is the combination of the carriage return and line feed characters, and native uses the default line terminator in the client operating system: crlf in Windows, cr in Mac OS, and lf in Linux.

When you create a Sandbox, Windchill RV&S remembers the setting of the line terminator, and all checkouts (using si co) and resyncs (using si resync) in that Sandbox use the same line terminator setting. If you want to override the line terminator on an individual member, you must use some utility such as the MKS Toolkit flip command.

• --[no]populate

controls whether to populate the Sandbox with read-only working files for all members.

• --[no]sparse

controls whether to create a sparse Sandbox.

Creating a sparse Sandbox with --sparse affects the way the Sandbox behaves with the si ci check in command and the si co check out command, as well as si resync. This option creates a Sandbox with no working files and defers the creation of Sandbox directories and subsandboxes until you need to work with them. A sparse Sandbox does not retain working files when a member is checked in and continues to function this way throughout its use; however, once created, Sandbox directories and subsandboxes remain in the Sandbox. Using si ci to check in a member to a sparse Sandbox removes the working file from the Sandbox (unless you did a check in locked, using the -l option). Similarly, using si resync on the Sandbox by default removes the working files for those members that are not locked by you, although you can override this with si resync--populate in a sparse Sandbox, which in effect causes the resync to behave like it does in a normal, non-sparse Sandbox.

• --[no]awaitServer

instructs the client to repeatedly attempt the operation if the Windchill RV&S Server does not respond.

• --[no]openView

controls whether to open the Sandbox view after this new Sandbox is registered on the client. If --noopenView is used, the Sandbox view does not open.

• directory

identifies a location on the Windchill RV&S client system for the new Sandbox. Use spaces to identify more than one directory.

Do NOT append the name of the project file (typically project.pj) to the directory. The name will be calculated automatically.

Diagnostics

See the diagnostics reference page for possible exit status values.

Preferences

Using si setprefs or si viewprefs, you are able to set or view the preference keys for this command.