file

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

Synopsis

file [-anyModified] [-buildLoadSettings] [-channels boolean] [-cleanReference string] [-command string] [-constraints boolean] [-constructionHistory boolean] [-copyNumberList] [-defaultExtensions boolean] [-defaultNamespace] [-deferReference boolean] [-editCommand string] [-errorStatus] [-executeScriptNodes boolean] [-exists] [-expandName] [-exportAll] [-exportAnim] [-exportAnimFromReference] [-exportAsReference] [-exportSelected] [-exportSelectedAnim] [-exportSelectedAnimFromReference] [-expressions boolean] [-flushReference string] [-force] [-groupLocator] [-groupName string] [-groupReference] [-ignoreVersion] [-import] [-importReference] [-lastFileOption] [-lastTempFile] [-list] [-loadAllDeferred boolean] [-loadAllReferences] [-loadNoReferences] [-loadReference string] [-loadReferenceDepth string] [-loadSettings string] [-location] [-lockContainerUnpublished boolean] [-lockFile boolean] [-lockReference] [-modified boolean] [-namespace string] [-newFile] [-open] [-options string] [-parentNamespace] [-postSaveScript string] [-preSaveScript string] [-preserveReferences] [-prompt boolean] [-reference] [-referenceDepthInfo uint] [-referenceNode string] [-removeReference] [-rename string] [-renameAll boolean] [-renameToSave boolean] [-renamingPrefix string] [-renamingPrefixList] [-returnNewNodes] [-save] [-saveDiskCache string] [-saveReference] [-saveTextures string] [-sceneName] [-selectAll] [-shader boolean] [-sharedNodes string] [-sharedReferenceFile] [-shortName] [-strict boolean] [-swapNamespace string string] [-type string] [-uiConfiguration boolean] [-unloadReference string] [-unresolvedName] [-usingNamespaces] [-withoutCopyNumber] [-writable] string

file is undoable, queryable, and editable.

This command needs a single main flag that specifies the action to take. Some of the main flags also take optional secondary flags to modify that action.

The main flags are:

cr	ea	ean	ear	eas	er	esa	es
esn	ex	fr	i	ir	l	lr
loc	ltf	mf	new	o	op	ot	pmt
r	rdi	rn	rr	rts	s	sa	sdx
st	stx	typ	uc	ur	w

-o/-open can be modified by the following secondary flags

f	lad	lad	lnr	rnn

-es/-exportSelected can be modified by the following secondary flags

ch	chn	con	exp	sh

-r/-reference can be modified by the following secondary flags

dns	dr	gr	gl	gn	ns	rfn	rpr	sns	srf	shd	rnn

-i/-import can be modified by the following secondary flags

dns	dr	gr	gn	pr	ra	rdn	rnn	rpr	sns

-n/-new and -s/-save can be modified by the following secondary flags

f

-er/exportAsReference can be modified by the following secondary flags

ns	rpr

-ea/-exportAll and -es/-exportSelected can be modified by the following secondary flags

f	pr

-ean/-exportAnim, -eas/-exportSelectedAnim can be modified by the following secondary flags

f

-ear/-exportAnimFromReference, -esa/-exportSelectedAnimFromReference can be modified by the following secondary flags

f	rfn

Querying information about a file

This command needs a single main query flag that specifies the query to take and then optional secondary flags to modify that query.

The main query flags are:

amf	ch	chn	con	dr	err	ex	exn
exp	l	loc	ltf	mf	ns	op	ot
pmt	pns	r	rfn	rpl	rpr	rts	sdc
sh	sn	stx	typ	uc	w

-dr/-deferReference can be modified by the following secondary flags

rfn

-exn/-expandName, -l/-list, -r/reference, -sn/sceneName can be modified by the following secondary flags

un	shn	wcn

Querying file names

When querying a file name there are a number of ways to format the result:

resolved vs. unresolved name:
When a file is loaded into Maya (e.g. by opening or referencing it), the file path provided may not be complete. It could, for example, be a relative path (ex: "scenes/myScene.ma"), it could contain environment variables (ex: "$PRODUCTION_DIR/myScene.ma"), and it could even be a path which simply doesn't exist on the local disk. In each of these cases Maya goes through a number of steps resolve the path and find the file on disk. By default the 'file' command will return the resolved file name (e.g. the location from which Maya is actually reading the file), but if the -un/-unresolved flag is used, the unresolved file (e.g. the one that was originally specified) will be returned.

full vs. short name:
By default the 'file' command will return the full path to a file, but if the -shn/-shortName flag is used just the file name will be returned.

with vs. without copy number:
When the same file is loaded into Maya more than once (for example by referencing the same file twice), Maya distinguishes between the various copies by appending a copy number to the end of the file name. The first time the file is loaded, no copy number is appended. The second time the file is loaded a "{1}" is appended, the third time a "{2}" is used, and so on. By default the 'file' command will return the file name with the copy number appended, but if the -wcn/-withoutCopyNumber flag is used the file name without the copy number will be returned.

Additional Details
• The file command usually expects a file name as its argument, if none is specified then the root scene is used.
• See the individual flag descriptions for details and limitations.

Return value

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

Related

Flags

Long name (short name)	Argument types	Properties
-anyModified(-amf)
This is a query only flag. If any of the memory resident files require a save to be performed then 1 is returned.
-buildLoadSettings(-bls)
When used with the "o/open" flag it indicates that the specified file should be read for reference hierarchy information only. This information will be stored in temporary load settings under the name "implicitLoadSettings". When this flag is used the specified scene file will not be loaded: no objects/nodes will be created or modified. Note: most users will not need to use this flag or the "implicitLoadSettings" it builds. They can access the same functionality by setting the "Selective Load" option in the File > Open Option Box.
-command(-c)	string
Specifies the callback to execute before any file operation. This is an internal flag used only in the file format.
-constructionHistory(-ch)	boolean
For use with exportSelected to specify whether attached construction history should be included in the export.
-channels(-chn)	boolean
For use with exportSelected to specify whether attached channels should be included in the export.
-copyNumberList(-cnl)
When queried, this flag returns a string array containing a number that uniquely identifies each instance the file is used.
-constraints(-con)	boolean
For use with exportSelected to specify whether attached constraints should be included in the export.
-cleanReference(-cr)	string
Remove edits from the passed in reference node. The reference must be in an unloaded state. To remove a particular type of edit, use the editCommand flag. If no flag is specified, all edits will be removed.
-editCommand(-ec)	string
For use with cleanReference. Remove only this type of edit. Supported edits are: setAttr addAttr deleteAttr connectAttr disconnectAttr and parent
-defaultExtensions(-de)	boolean
Use the default extensions to rename the files.
-defaultNamespace(-dns)
Use the default name space for import and referencing. This is an advanced option. If set, then on import or reference, Maya will attempt to place all nodes from the imported or referenced file directly into the root (default) name space, without invoking any name clash resolution algorithms. If the names of any of the new objects already exist in the root namespace, then errors will result. The user of this flag is responsible for creating a name clash resolution mechanism outside of Maya to avoid such errors. Note: This flag is intended only for use with custom file translators written through the API. Use at your own risk.
-errorStatus(-err)
Query the error status of the last file read. Returns true if and error occurred during the last file read.
-deferReference(-dr)	boolean
When used in conjunction with the -reference flag, this flag determines if the reference is loaded, or if loading is deferred. C: The default is false. Q: When queried, this flag returns true if the reference is deferred, or false if the reference is not deferred. If this is used with -rfn/referenceNode, the -rfn flag must come before -q.
-exportAll(-ea)
Export everything into a single file. Returns the name of the exported file.
-exportAnim(-ean)
Export all animation nodes and animation helper nodes from all objects in the scene. The resulting animation export file will contain connections to objects that are not included in the animation file. As a result, importing/referencing this file back in will require objects of the same name to be present, else errors will occur. The -sns/swapNamespace flag is available for swapping the namespaces of given objects to another namespace. This use of namespaces can be used to re-purpose the animation file to multiple targets using a consistent naming scheme.
-exportSelectedAnim(-eas)
Export all animation nodes and animation helper nodes from the selected objects in the scene. See -ean/exportAnim flag description for details on usage of animation files.
-exportAnimFromReference(-ear)
Export the main scene animation nodes and animation helper nodes from all referenced objects. This flag, when used in conjunction with the -rfn/referenceNode flag, can be constrained to only export animation nodes from the specified reference file. See -ean/exportAnim flag description for details on usage of animation files.
-exportAsReference(-er)
Export the selected objects into a reference file with the given name. The file is saved on disk during the process. Returns the name of the reference created.
-exportSelected(-es)
Export the selected items into the specified file. Returns the name of the exported file.
-exportSelectedAnimFromReference(-esa)
Export the main scene animation nodes and animation helper nodes from the selected referenced objects. This flag, when used in conjunction with the -rfn/referenceNode flag, can be constrained to only export animation nodes from the selected nodes of a specified reference file. See -ean/exportAnim flag description for details on usage of animation files.
-executeScriptNodes(-esn)	boolean
If true, allow the appropriate script nodes to execute. If false, do not allow any script node scripts to run. For more information, see the documentation for script nodes. Default: true.
-exists(-ex)
Query if the file exists. Returns true if the file exists.
-expandName(-exn)
This is a query only flag that can be used to query for the file path name of the file.
-expressions(-exp)	boolean
For use with exportSelected to specify whether attached expressions should be included in the export.
-force(-f)
Force an action to take place. (new, open, save)
-flushReference(-fr)	string
This flag will unload the reference file associated with the passed reference node, retaining all associated reference nodes and scene files. ** This option only works when using namespaces **. More Details: This flag is primarily intended to be used as part of a custom asset management system. It can be used to defer loading of a reference which contains child references without losing information about those child references. Prior to reloading a flushed reference which contains child references, the 'createNode reference' lines should be manually removed from the children's Maya ASCII files. If this is not done, extra reference nodes will be created.
-groupLocator(-gl)
Used only with the -r and the -gr flag. Used to group the output of groupReference under a locator
-groupName(-gn)	string
Used only with the -gr flag. Optionally used to set the name of the transform node that the imported/referenced items will be grouped under.
-groupReference(-gr)
Used only with the -r or the -i flag. Used to group all the imported/referenced items under a single transform.
-ignoreVersion(-iv)
Used to open files with version greater or less than those officially supported. Data loss, data corruption or failure to open altogether are all possibilities, but as much as can be successfully read, will be. Must be used with the -o flag.
-lockReference(-lck)
Locks attributes and nodes from the referenced file.
-lockFile(-lf)	boolean
Lock or unlock the main scene. Any file referencing this scene will automatically lock all attributes and nodes. Also prevents reference edits from being saved to it from a parent file.
-lockContainerUnpublished(-lcu)	boolean
Set the unpublised lock state for all containers in this file. This will not lock the attributes in the main scene directly, but any file that references this scene will have all its containers come in as unpublished locked.
-import(-i)
Import the specified file. Returns the name of the imported file.
-importReference(-ir)
Remove the encapsulation of the reference around the data within the specified file. This makes the contents of the specified file part of the current scene and all references to the original file are lost. Returns the name of the reference that was imported.
-list(-l)
List all files. Returns a string array of the names of all segment/reference files. Duplicates will be removed. So if a file is referenced more than once, and the -withoutCopyNumber flag is set, it will only be listed once. in the scene.
-loadReferenceDepth(-lrd)	string
Used to specify which references should be loaded. Valid types are "all", "none" and "topOnly", which will load all references, no references and top-level references only, respectively. Must be used with the -open, -import, -reference or -loadReference flags. When "none" is used with -loadReference, only path validation is performed. This can be used to replace a reference without triggering reload.
-loadAllDeferred(-lad)	boolean
This flag is obsolete, and has been replaced by the loadReferenceDepth flag. When used with the -open flag, determines if the -deferReference flag is respected when reading in the file. If true is passed, all of the references are loaded. If false is passed, the -deferReference flag is respected.
-loadAllReferences(-lar)
This flag is obsolete and has been replaced with the loadReferenceDepth flag. When used with the -open flag, this will cause all references to be loaded.
-loadNoReferences(-lnr)
This flag is obsolete and has been replaced witht the loadReferenceDepth flag. When used with the -open flag, no references will be loaded. When used with -import, -reference or -loadReference flags, will load the top-most reference only.
-location(-loc)
Query the location of the given file name.
-loadReference(-lr)	string
This flag loads a file and associates it with the passed reference node. If the reference node does not exist, the command will fail. If the file is already loaded, then this flag will reload the same file. If a file is not given, the command will load (or reload) the last used reference file.
-loadSettings(-ls)	string
When used with the "o/open" flag this flag specifies which reference load settings should be used. Reference load settings specify which references should be brought in loaded and which unloaded. Those reference files that are brought in unloaded will usually not need to be read and interpreted by Maya. This can potentially reduce the time it takes Maya to load the whole scene. If no "ls/loadSettings" flag is specified, or the empty string ("") is used as the flag argument, the default load settings are used. The default load settings represent the state of all references when the file was last saved. The load settings "implicitLoadSettings" refer to the temporary load settings generated by the "bls/buildLoadSettings" flag and edited with the "loadSettings" command. Currently on the default and implicit load settings are supported.
-lastTempFile(-ltf)
When queried, this flag returns the temp file name used during file save. The temp file will be left in the same directory as the intended file name if the save fails.
-modified(-mf)	boolean
Set the modified state of the file. A modified file will need to be saved before a new file is opened or created. You do not normally need to edit this flag as the state of the file is updated automatically whenever an object is created or modified. If the file has been modified 1 is returned. Otherwise 0 is returned.
-newFile(-new)
Initialize the scene. Returns untitled scene with default location.
-namespace(-ns)	string
The namespace name to use that will group all objects during importing and referencing. Change the namespace used to group all the objects from the specified referenced file. The reference must have been created with the "Using Namespaces" option, and must be loaded. Non-referenced nodes contained in the existing namespace will also be moved to the new namespace. The new namespace will be created by this command and can not already exist. The old namespace will be removed.
-open(-o)
Open the specified file. Returns the name of the opened file.
-options(-op)	string
Set/query the currently set file options.
-lastFileOption(-lfo)
On query, returns the last option string used by the file command.
-prompt(-pmt)	boolean
This flag controls the display of file prompting dialogs. Some examples of file prompting dialogs include error messages that require user confirmation and missing file reference dialogs. Once this flag is used, every instance of the file command will use the last set value of this flag. Some interactive file operations may post dialogs even when the flag is set to false, but every scripted file command will not display any dialogs when this flag is set to false. The default value is true.
-parentNamespace(-pns)
Returns the name(s) of a referenced file's parent namespaces.
-preserveReferences(-pr)
When used with the import/export flags this tells the importer/exporter to import/export references as references instead of copies of those references.
-preSaveScript(-prs)	string
When used with the save flag, the specified script will be executed before the file is saved.
-postSaveScript(-pos)	string
When used with the save flag, the specified script will be executed after the file is saved.
-reference(-r)
Create a reference to the specified file. Returns the name of the file referenced. Query all file references from the specified file.
-renameAll(-ra)	boolean
Only available with -import. If true, rename all newly-created nodes, not just those whose names clash with existing nodes. Only available with -import.
-referenceDepthInfo(-rdi)	uint
This flag is used to store reference loading preferences associated with a Maya ascii file (.ma). This flag is only useful during file I/O so users should not have any need to use this flag.
-referenceNode(-rfn)	string
When queried, this flag returns the name of the reference node associated with the file. If the file is not a reference or does not have a reference node, an empty string is returned. In query mode, this flag can accept a value.
-rename(-rn)	string
Rename the scene. Used mostly during save to set the saveAs name. Returns the new name of the scene.
-returnNewNodes(-rnn)
Used to control the return value in open, import, loadReference, and reference operations. It will force file command to return a list of new nodes added to the current scene.
-renamingPrefixList(-rpl)
This flag returns a list of all of the renaming prefixes used by the file.
-renamingPrefix(-rpr)	string
The string to use as a prefix for all objects from this file. This flag has been replaced by -ns/namepace.
-removeReference(-rr)
Remove the given file reference from its parent. This will also Remove everything this file references. Returns the name of the file removed.
-renameToSave(-rts)	boolean
If true, the scene will need to be renamed before it can be saved. When queried this flag returns true if the scene must be renamed before it can be saved. The default is false.
-save(-s)
Save the specified file. Returns the name of the saved file.
-saveReference(-sr)
Save reference node edits and connections to reference file. This includes newly added history and animation, provided that these do not apply to any objects outside the reference being saved.
-selectAll(-sa)
Select all the components of this file as well as its child files. Note that the file specified must be one that is already opened in this Maya session.
-saveDiskCache(-sdc)	string
This flag sets the saveAs option for Jiggle disk caches. The valid inputs are "always" - always copy a file texture to a new location, "never" - do not copy at all. C: The default is "always". Q: When queried it returns a string ("always", "never").
-shader(-sh)	boolean
For use with exportSelected to specify whether attached shaders should be included in the export.
-sharedNodes(-shd)	string
This flag modifies the '-r/-reference' flag to indicate that certain types of nodes within that reference should be treated as shared nodes. All shared nodes will be placed in the default namespace. New copies of those nodes will not be created if a copy already exists in the default namespace, instead the shared node will be merged with the existing node. The specifics of what happens when two nodes are merged depends on the node type. In general attribute values will not be merged, meaning the values set on any existing shared nodes will be retained, and the values of the nodes being merged in will be ignored. The valid options are "displayLayers", "shadingNetworks", "renderLayersByName", and "renderLayersById". This flag is multi-use; it may be specified multiple times to for example, share both display layers and shading networks. Two shading networks will only be merged if they are identical: the network of nodes feeding into the shading group must be arranged identically with equivalent nodes have the same name and node type. Additionally if a network is animated or contains a DAG object or expression it will not be mergeable. This flag cannot be used in conjunction with -srf/sharedReferenceFile.
-shortName(-shn)
When used with a main query flag it indicates that the file name returned will be the short name (i.e. just a file name without any directory paths). If this flag is not present, the full name and directory path will be returned.
-sceneName(-sn)
return the name of the current scene.
-swapNamespace(-sns)	string string
Can only be used in conjunction with the -r/reference or -i/import flags. This flag will replace any occurrences of a given namespace to an alternate specified namespace. This namespace "swap" will occur as the file is referenced in. It takes in two string arguments. The first argument specifies the namespace to replace. The second argument specifies the replacement namespace. Use of this flag, implicitly enables the use of namespaces and cannot be used with deferReference.
-sharedReferenceFile(-srf)
Can only be used in conjunction with the -r/reference flag and the -ns/namespace flag (there is no prefix support). This flag modifies the '-r/-reference' flag to indicate that all nodes within that reference should be treated as shared nodes. New copies of those nodes will not be created if a copy already exists. Instead, the shared node will be merged with the existing node. The specifics of what happens when two nodes are merged depends on the node type. This flag cannot be used in conjunction with -shd/sharedNodes.
-strict(-str)	boolean
Set strict file path resolution. If true, all paths will be matched exactly, both relative and absolute. Relative paths will be considered relative to the project root directory. Must be used with the -open, -import, -importReference or -reference.
-saveTextures(-stx)	string
This flag sets the saveAs option for 3d Paint file textures. The valid inputs are "always" - always copy a file texture to a new location, "unlessRef" - copy only if this is not a referenced file texture, "never" - do not copy at all. C: The default is "unlessRef". Q: When queried it returns a string ("always", unlessRef", "never").
-type(-typ)	string
Set the type of this file. By default this can be any one of: "mayaAscii", "mayaBinary", "mel", "OBJ", "directory", "plug-in", "audio", "move", "EPS", "Adobe(R) Illustrator(R)", "image" plug-ins may define their own types as well. Return a string array of file types that match this file.
-uiConfiguration(-uc)	boolean
Save the ui configuration with the scene in a uiConfiguration script node. (eg. panes, etc.) The current default is on and is set in initialStartup.mel.
-usingNamespaces(-uns)
Returns boolean. Queries whether the specified reference file uses namespaces or renaming prefixes.
-unresolvedName(-un)
When used with a main query flag it indicates that the file name returned will be unresolved (i.e. it will be the path originally specified when the file was loaded into Maya; this path may contain environment variables and may not exist on disk). If this flag is not present, the resolved name will be returned.
-unloadReference(-ur)	string
This flag will unload the reference file associated with the passed reference node.
-writable(-w)
Query whether the given file is writable in the current scene. For main scene files this indicates writable to the file system by the current user. Files referenced by the main scene file are always not writable (referenced files are by nature read only). Files not present in the current scene always return false.
-withoutCopyNumber(-wcn)
When used with a main query flag it indicates that the file name returned will not have a copy number appended to the end. If this flag is not present, the file name returned may have a copy number appended to the end.

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

// save the current scene to an ascii file named "fred.ma"
//
file -rename "fred.ma"; file -save -type "mayaAscii";

// save the current scene to an ascii file without the ".ma" extension
//
file -rename "tmp"; file -save -de 0 -type "mayaAscii";

// open the file fred.ma, using the default load settings. Any references will
// be brought in in the same state they were in when fred.ma was last saved.
//
file -o "fred.ma";

// reference the file wilma.ma
//
file -r "C:/mystuff/wilma.mb";

// reference the file barney.mb into a namespace called "rubble".
//
file -r -type "mayaAscii" -namespace "rubble" "C:/maya/projects/default/scenes/barney.ma";

// change the namespace containing barney.mb.
//
file -e -namespace "purpleDinosaur" "C:/maya/projects/default/scenes/barney.ma";

// retrieve a string array of all files referenced in the scene
//
  file -q -l;
// Result: C:/maya/projects/default/scenes/fred.ma C:/mystuff/wilma.mb C:/maya/projects/default/scenes/barney.ma

// Select "betty" and export betty to a separate file called "betty.mb".
// Reference the new betty file into this scene, replacing the
// previous betty object from this scene with the reference to betty.
//
file -type "mayaBinary" -namespace "rubble" -er "c:/mystuff/betty.mb";

// Select all the objects associated with file betty.mb
//
file -sa "c:/mystuff/betty.mb";
// Result: rubble:betty

// Remove the reference file betty.mb. All nodes in betty.mb will
// be removed from the scene
file -rr "c:/mystuff/betty.mb";

// Query whether the file named "foo.mb" exists on disk
//
file -q -ex "foo.mb";
// Result: 0 //

// Query whether the reference node "rubble:betty is deferred loaded.
// Note, -rfn flag has to come before -q flag.
file -rfn rubble:betty -q -dr;

// Query the last temp file during file save
//
file -q -lastTempFile;

/////////////////////////////////////////////////////////////////////////
///   Example for the '-buildLoadSettings' and '-loadSettings' flags  ///
/////////////////////////////////////////////////////////////////////////

// Build load settings for "ref.ma"
file -o -buildLoadSettings "ref.ma"
// Edit those settings, to indicate that some reference should
  // be brought in unloaded.
// Note: the following command is primarily intended for internal
// use. It may not be easy to determine the numeric ID of a given
// reference ("2" in this case) .
file -loadSettings -e -deferReference 1 "2"
// Use the edited settings when opening the file
file -o -loadSettings "implicitLoadSettings" "ref.ma";

/////////////////////////////////////////////////////////////////////////
///   Example for the '-cleanReference' and '-editCommand' flags      ///
/////////////////////////////////////////////////////////////////////////

// Create a simple reference to a sphere
//
file -f -new;
polySphere;
file -rename "ref.ma";
file -f -type "mayaAscii" -save;
file -f -new;
file -r -ns "ref" "ref.ma";

// Scale the sphere
//
setAttr ref:pSphere1.s 5 5 5;
getAttr ref:pSphere1.s;
// Result: 5 5 5 //

// The 'cleanReference' and 'editCommand' flags only work on
// unloaded references.
//
file -unloadReference "refRN";

// Query the setAttr edits:
//
reference -rfn "refRN" -q -editCommand;
// Result: setAttr ref:pSphere1.s -type "double3" 5 5 5 setAttr ref:lightLinker1.lnk -s 2 //

// Remove all setAttr edits on refRN:
//
file -cleanReference "refRN" -editCommand "setAttr";
reference -rfn "refRN" -q -editCommand;
// Note that nothing is returned

file -loadReference "refRN";

getAttr ref:pSphere1.s;
// Result: 1 1 1 //
// Note that scale has returned to 1 1 1