workspace

Go to: Synopsis. Return value. Related. Flags. MEL examples.

Synopsis

workspace [-active] [-baseWorkspace string] [-create string] [-directory string] [-expandName string] [-fileRule string string] [-fileRuleEntry string] [-fileRuleList] [-filter] [-fullName] [-list] [-listFullWorkspaces] [-listWorkspaces] [-newWorkspace] [-objectType string string] [-objectTypeEntry string] [-objectTypeList] [-openWorkspace] [-projectPath string] [-removeFileRuleEntry string] [-removeVariableEntry string] [-renderType string string] [-renderTypeEntry string] [-renderTypeList] [-rootDirectory] [-saveWorkspace] [-shortName] [-update] [-updateAll] [-variable string string] [-variableEntry string] [-variableList] [string]

workspace is undoable, queryable, and NOT editable.

The string argument represents the workspace. If no workspace is specified then the current workspace is assumed.

A workspace provides the underlying definition of a Maya Project. Each project has an associated workspace file, named workspace.mel, which is stored in the project root directory. The workspace file defines a set of rules that map file types to their storage, either relative to the project root or as an absolute location. These rules are used when resolving file paths at runtime.

The workspace command operates directly on the low-level definition of the workspace to read, change and store the definition to the underlying file. Use of this command is not generally required, for most purposes it is recommended that project definition changes be done via the Project Window in the User Interface. Multiple actions go under the assumption that given paths exist.

Return value

In query mode, return type is based on queried flag.

Related

Flags

Long name (short name)	Argument types	Properties
-active(-act)
This flag is a synonym for -o/openWorkspace.
-baseWorkspace(-bw)	string
A workspace may be based on another workspace. This means that all the file rules and variables in the base workspace apply to this workspace unless they are explicitly overridden. By default, a new workspace has the workspace "default" as it's base workspace. Note that "duplicated" file rules containing relative paths are not verified nor created when creating a new workspace or when changing the base workspace.
-create(-cr)	string
Create a new directory. If the directory name is not a full path name, it will be created as a subdirectory of the "current" directory set with the -dir flag. Note that this flag does not create a workspace.
-directory(-dir)	string
This option will set the current workspace directory to the path specified. When queried it will return the current workspace directory. This directory is used as an initial directory for the fileBrowser and is part of the search path used for locating files. It should not be confused with the current working directory as used by the pwd and chdir commands. When the file browser is used, it will set this value to the last location navigated to.
-expandName(-en)	string
Query for the full path location of a filename using the current workspace definition. The path may be a project relative file name, a full path name or a variable name. The return value is always a full path name. If the path is an empty string, the return value will be the project root directory. Variable expansion is supported, and will consider both variables defined in the workspace as well as environment variables. There are three formats supported for expanding variable names: %variableName%, $variableName, ${variableName}. Maya will first attempt to find matching variables defined in the current workspace, then search for a matching environment variable. The tilde character ('~') is also supported. If a tilde is located at the beginning of a variable, Maya will only consider and expand environment variables, and will leave the tilde in the expanded result. On linux and mac platforms, a tilde can be used to expand a user's home directory, using the form ~username, ~, or ~/. When specified as ~username, it will be replaced with the corresponding user's home directory. When specified as ~ or ~/, it will be replaced with the value of the HOME environment variable.
-fileRule(-fr)	string string
Set the default location for a file. The first parameter is the fileRule name(scenes, images, etc) and the second is the location. When queried, it returns a list of strings. The elements of the returned list alternate between fileRule names and the corresponding location. There is typically one file rule for each available translator. Environment variables are supported. You can set multiple path for the file rule by separating them with semicolons (;) on Windows and colons(:) on MacOSX and Linux. Note that whitespace at the beginning and end of each item in the separated sequence is significant and will be included as part of the path name (which is not usually desired unless the pathname does actually start or end with spaces). A valid filerule name cannot contain multiple byte characters. Note that creating a filerule does not create any directories. It is the user's responsibility to ensure that all paths are valid.
-fileRuleEntry(-fre)	string
Return the location for the given fileRule.
-fileRuleList(-frl)
Returns a list of the currently defined file rules.
-filter(-f)
This flag is obsolete.
-fullName(-fn)
Return the full name of the workspace.
-list(-l)
This option will list the current workspace directory. If a path is specified for the "workspaceFile" then the contents of that directory will be listed. Otherwise, the contents of the directory set with the -dir flag will be listed.
-listFullWorkspaces(-lfw)
Returns a list of the full path names of all the currently defined workspaces.
-listWorkspaces(-lw)
Returns a list of all the currently defined workspace names.
-newWorkspace(-n)
This specifies that a new workspace is being created with a given path (full path or relative to "current" directory). If a workspace with this path already exists, the command will fail. Note that the application is creating a virtual workspace without creating any new directories. If given a relative path, it will map the new workspace to the "current" directory set with the -dir flag concatenated with the given path. If the path does not exist, it will default the workspace root directory -rd to the system's root path (e.g. C:\ or '/'). It is the user's responsibility to ensure that all paths exist.
-objectType(-ot)	string string
This flag is obsolete. All default locations will be added to the fileRules going forward.
-objectTypeEntry(-ote)	string
This flag is obsolete. This will now return the same as fileRuleEntry.
-objectTypeList(-otl)
This flag is obsolete. This will now return the same results as fileRuleList going forward.
-openWorkspace(-o)
Open the workspace. The workspace becomes the current workspace.
-projectPath(-pp)	string
Convert filePath passed as argument to a filename that is relative to the project root directory (if possible) and return it. If the filePath is not under the project root directory, a full path name will be returned.
-removeFileRuleEntry(-rfr)	string
Remove the given file rule from the specified workspace. If the workspace name is not specified, the given file rule will be removed from the current workspace.
-removeVariableEntry(-rve)	string
Remove the given variable from the specified workspace. If the workspace name is not specified, the given variable will be removed from the current workspace.
-renderType(-rt)	string string
This flag is obsolete. All default render types will be added to fileRules going forward.
-renderTypeEntry(-rte)	string
This flag is obsolete, use fileRuleEntry going forward
-renderTypeList(-rtl)
This flag is obsolete, use fileRuleList going forward.
-rootDirectory(-rd)
Returns the root directory of the workspace.
-saveWorkspace(-s)
Save the workspace. Workspaces are normally saved when Maya exits but this flag will make sure that the data is flushed to disk.
-shortName(-sn)
Query the short name of the workspace.
-update(-u)
This flag reads all the workspace definitions from the project directory. It is used by Maya at startup time to find the available workspaces.
-updateAll(-ua)
This flag is a synonym for -u/update.
-variable(-v)	string string
Set or query the value of a project variable. Project variables are used when expanding names. See the -en/expandName flag below.
-variableEntry(-ve)	string
Given a variable name, will return its value.
-variableList(-vl)
Return a list of all variables in the workspace.

Flag can appear in Create mode of command	Flag can appear in Edit mode of command
Flag can appear in Query mode of command	Flag can be used more than once in a command.

MEL examples

// Set the current workspace to "alphabet"
workspace -openWorkspace alphabet;

// Save the current workspace settings (for "alphabet").
workspace -saveWorkspace;

// Change current directory to project directory
workspace -directory "/h/userName/maya/projects/";

// Create a directory for a new workspace
workspace -create newWorkspace;

// Create a new workspace named "newWorkspace".
workspace -newWorkspace newWorkspace;

// The file rules and variables of "newWorkspace" are based on "default" workspace
workspace -baseWorkspace "default";

// Return the list of existing workspaces
workspace -listWorkspaces ;
// Result: default   newWorkspace

// Add a scriptJob to run on workspaceChanged events
global proc workspaceChangedCallback()
{
    print "My workspaceChangedCallback was called";
}

int $workspaceChangedID = `scriptJob -event workspaceChanged workspaceChangedCallback`;

// add a file rule to the current workspace
workspace -fileRule "newFileRuleName" "newFileRuleValue";
My workspaceChangedCallback was called            //workspaceChangedCallback was called

// look up the value of the file rule entry
workspace -q -fileRuleEntry "newFileRuleName";
// Result: newFileRuleValue

// remove specified file rule entry
workspace -removeFileRuleEntry "newFileRuleName";
My workspaceChangedCallback was called            //workspaceChangedCallback is called

// kill the scriptJob with the number
scriptJob -kill $workspaceChangedID;

// The following example shows how to expand environment and workspace variables

// expand a path value to be a full path relative to the project directory
// relative path example
workspace -expandName "relativePathName";
// Result: /h/userName/maya/projects/newWorkspace/relativePathName
// full path example
workspace -expandName "/h/userName/maya/projects/default/";
// Result: /h/userName/maya/projects/default/

// The following examples show various formats for expanding workspace and
// environment variables

// add a variable to the current workspace
workspace -variable "newVariableName" "newVariableValue";

workspace -expandName "%newVariableName%";
// Result: /h/userName/maya/projects/newWorkspace/newVariableValue

// add an environment variable
putenv "newEnvVariableName" "newEnvVariableValue";

workspace -expandName "%newEnvVariableName%";
// Result: /h/userName/maya/projects/newWorkspace/newEnvVariableValue

// The following example shows how conflicting names in both workspace
// and environment variables are resolved.
// Add an environment variable with the same as the workspace variable
putenv "newVariableName" "newEnvVariableValue"

// maya considers workspace variables first before matching environment variables
workspace -expandName "%newVariableName%";
// Result: /h/userName/maya/projects/newWorkspace/newVariableValue

// However when a tilde is used, maya will only consider the environment varible, not
// the workspace variable.
workspace -expandName "~%newVariableName%";
// Result: /h/userName/maya/projects/newWorkspace/~newEnvVariableValue

// The following example shows how to set multiple paths into a fileRule value
workspace -fileRule "newMultiPathFileRuleName" "/h/userName/maya/projects/default;newFileRuleValue";

string $multipath = `workspace -q -fileRuleEntry "newMultiPathFileRuleName"`;
// Result : /h/userName/maya/projects/default;newFileRuleValue

// Note that white space at the beginning and the end of each path is significant
// Add a file rule that uses multiple paths with the white space at the beginning and the end
// of each path
workspace -fileRule "newMultiPathFileRuleName" " /h/userName/maya/projects/default ; newFileRuleValue ";
// Querying and expanding the path value shows the white space is still included
string $multipath = `workspace -q -fileRuleEntry "newMultiPathFileRuleName"`;
// Result :  /h/userName/maya/projects/default ; newFileRuleValue

// Find the current workspace area.
workspace -q -directory;
// Result : /h/userName/maya/projects/default

// Note that the "current working directory" as defined by the
// 'pwd' and 'chdir' commands is unrelated to the directories
// used by the workspace command.
//
pwd;
// Result : /usr/tmp

chdir "/tmp";
pwd;
// Result : /tmp
workspace -q -directory;
// Result : /h/userName/maya/projects/default

workspace -directory "/h/userName/maya/projects/commercial";
pwd;
// Result : /tmp