file

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

Synopsis

file( string , [activate=boolean], [activeProxy=boolean], [add=boolean], [anyModified=boolean], [applyTo=string], [buildLoadSettings=boolean], [channels=boolean], [cleanReference=string], [command=[string, string]], [compress=boolean], [constraints=boolean], [constructionHistory=boolean], [copyNumberList=boolean], [defaultExtensions=boolean], [defaultNamespace=boolean], [deferReference=boolean], [editCommand=string], [errorStatus=boolean], [executeScriptNodes=boolean], [exists=boolean], [expandName=boolean], [exportAll=boolean], [exportAnim=boolean], [exportAnimFromReference=boolean], [exportAsReference=boolean], [exportAsSegment=boolean], [exportSelected=boolean], [exportSelectedAnim=boolean], [exportSelectedAnimFromReference= boolean], [exportSelectedNoReference=boolean], [exportUnloadedReferences=boolean], [expressions=boolean], [flushReference=string], [force=boolean], [groupLocator=boolean], [groupName=string], [groupReference=boolean], [i=boolean], [ignoreVersion=boolean], [importReference=boolean], [lastFileOption=boolean], [lastTempFile=boolean], [list=boolean], [loadAllDeferred=boolean], [loadAllReferences=boolean], [loadNoReferences=boolean], [loadReference=string], [loadReferenceDepth=string], [loadReferencePreview=string], [loadSettings=string], [location=boolean], [lockContainerUnpublished=boolean], [lockFile=boolean], [lockReference=boolean], [mapPlaceHolderNamespace=[string, string]], [mergeNamespaceWithParent=boolean], [mergeNamespaceWithRoot=boolean], [mergeNamespacesOnClash=boolean], [modified=boolean], [moveSelected=boolean], [namespace=string], [newFile=boolean], [open=boolean], [options=string], [parentNamespace=boolean], [postSaveScript=string], [preSaveScript=string], [preserveName=boolean], [preserveReferences=boolean], [preview=boolean], [prompt=boolean], [proxyManager=string], [proxyTag=string], [reference=boolean], [referenceDepthInfo=uint], [referenceNode=string], [relativeNamespace=string], [removeDuplicateNetworks=boolean], [removeReference=boolean], [rename=string], [renameAll=boolean], [renameToSave=boolean], [renamingPrefix=string], [renamingPrefixList=boolean], [replaceName=[string, string]], [resetError=boolean], [returnNewNodes=boolean], [save=boolean], [saveDiskCache=string], [saveReference=boolean], [saveReferencesUnloaded=boolean], [saveTextures=string], [sceneName=boolean], [segment=string], [selectAll=boolean], [shader=boolean], [sharedNodes=string], [sharedReferenceFile=boolean], [shortName=boolean], [strict=boolean], [swapNamespace=[string, string]], [type=string], [uiConfiguration=boolean], [unloadReference=string], [unresolvedName=boolean], [usingNamespaces=boolean], [withoutCopyNumber=boolean], [writable=boolean])

Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.

file is undoable, queryable, and editable.

Opening, importing, exporting, referencing, saving, or renaming a file

Querying information about a file

Querying file names

Resolved vs. unresolved name:

Full vs. short name:

With vs. without copy number:

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
activeProxy(ap)	boolean
This flag is intended for internal use by Maya during file referencing. It specifes which file is the active proxy when the file is loaded when used with the reference flag. It is also used to specify which file is the active proxy in the file referencing preload information when used with the referenceDepthInfo flag.
anyModified(amf)	boolean
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)	boolean
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, 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)	boolean
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. This defaults to true, but is a persistent setting within a given session of Maya, meaning that if you set it to true or false, that value will continue to be used in subsequent file commands until a new value is set.
defaultNamespace(dns)	boolean
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)	boolean
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)	boolean
Export everything into a single file. Returns the name of the exported file.
exportAnim(ean)	boolean
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. The exportAnim flag will not export animation layers. For generalized file export of animLayers and other types of nodes, refer to the exportEdits command. Or use the Export Layers functionality.
exportSelectedAnim(eas)	boolean
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)	boolean
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)	boolean
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)	boolean
Export the selected items into the specified file. Returns the name of the exported file.
exportSelectedAnimFromReference( esa)	boolean
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)	boolean
Query if the file exists. Returns true if the file exists.
expandName(exn)	boolean
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)	boolean
Force an action to take place. (new, open, save, remove reference) Used with removeReference to force remove reference namespace even if it has contents. Cannot be used with removeReference if the reference resides in the root namespace.
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)	boolean
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)	boolean
Used only with the -r or the -i flag. Used to group all the imported/referenced items under a single transform.
ignoreVersion(iv)	boolean
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)	boolean
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.
i(i)	boolean
Import the specified file. Returns the name of the imported file.
importReference(ir)	boolean
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)	boolean
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.
mergeNamespacesOnClash( mnc)	boolean
Used with the import, reference or edit flags, this option will prevent new namespaces from being created when namespaces of the same name already exist within Maya. The default value is false. For example, if an object "pSphere1", which is being imported, refers to the namespace "ref" and there is already a namespace called "ref" defined in Maya. If mergeNamespacesOnClash is true, the existing "ref" namespace will be reused and pSphere1 will be moved into the existing namespace; and if the namespace has another object which is also named "pSphere1", then the imported one will be renamed with an incremental number("pSphere2"). On the other hand, if mergeNamespacesOnClash is false, a new namespace will be created with an incremental number (in first case is "ref1") and pSphere1 will be moved into the "ref1" namespace. This flag also support nested namespace, for example, if an object "pSphere1" which is imported and refers to namespace "ref:foo" and mergeNamespacesOnClash is true this time, then the existing "ref:foo" will be reused and the object will be moved into "ref:foo". Also if mergeNamespacesOnClash is false, then a new namespace "ref:foo1" will be created and "pSphere1" will be moved into that new namespace.
mergeNamespaceWithParent( mnp)	boolean
Used with the removeReference flag. When removing a file reference and its namespace, move the rest of the namespace content to parent namespace. Cannot be used if the reference resides in the root namespace.
mergeNamespaceWithRoot( mnr)	boolean
Used with the removeReference flag. When removing a file reference and its namespace, move the rest of the namespace content to root namespace. Cannot be used if the reference resides in the root namespace.
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)	boolean
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)	boolean
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)	boolean
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.
loadReferencePreview(lrp)	string
This flag will perform a special preview-only load of a reference file. A preview-only reference file is not completely loaded, but instead is partially loaded so that certain information, such as nested references it contains, can be determined. Nested references that are previewed remain in a special preview-only state.
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)	boolean
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. Normally there is no need to edit this flag as the state of the file is updated automatically whenever an object is created or modified. If editing of the state is desired, it is done without use of the edit flag as covered in the example section below. In query mode, if the file has been modified 1 is returned. Otherwise 0 is returned.
newFile(new)	boolean
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)	boolean
Open the specified file. Returns the name of the opened file.
options(op)	string
Set/query the currently set file options. file options are used while saving a maya file. Two file option flags supported in current file command are v and p. v(verbose) indicates whether long or short attribute names and command flags names are used when saving the file. Used by both maya ascii and maya binary file formats. It only can be 0 or 1. Setting v=1 indicates that long attribute names and command flag names will be used. By default, or by setting v=0, short attribute names will be used. p(precision) defines the maya file IO's precision when saving the file. Only used by maya ascii file format. It is an integer value. The default value is 17. The option format is "flag1=XXX;flag2=XXX".Maya uses the last v and p as the final result. Note: 1. Use a semicolon(";") to separate several flags. 2. No blank space(" ") in option string.
lastFileOption(lfo)	boolean
On query, returns the last option string used by the file command.
preview(pv)	boolean
Used in conjunction with any of the -exportXXX flags, causes Maya to return a list of the nodes that would be exported, without actually writing the exported file to disk.
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)	boolean
Returns the name(s) of a referenced file's parent namespaces.
preserveReferences(pr)	boolean
When used with the import/export flags this tells the importer/exporter to import/export references as references instead of copies of those references.
exportUnloadedReferences( eur)	boolean
Only effective when preserveReferences is used. When used with the exportAll flag, tells the exporter to include all unloaded references in the export. When used with the exportSelected flag, tells the exporter to include all unloaded proxy references that are related to any node in the selection.
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.
proxyManager(pm)	string
When a one or more proxy references are added to an existing file reference, the proxy manage node is used to define the proxies associated with that reference. This flag is used in conjunction with the activeProxy and proxyTag flag to specify the proxyManager of interest. This flag is also used to specify the proxyManager for a proxy reference in the file referencing preload information, when used in conjunction with the referenceDepthInfo flag.
proxyTag(pt)	string
This flag is intended for internal use only during file load or preload. Proxy tags are names you assign to proxy references to more easily manage the proxy references from the reference editor. Proxy tags are unique within a given proxy set. This flag must be used in conjunction with the proxyManager flag.
reference(r)	boolean
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)	boolean
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)	boolean
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/namespace.
removeReference(rr)	boolean
Remove the given file reference from its parent. This will also Remove everything this file references. Returns the name of the file removed. If the reference is alone in its namespace, remove the namespace. If there are objects remaining in the namespace after the file reference is removed, by default, keep the remaining objects in the namespace. To merge the objects remaining in the namespace to the parent or root namespace, use flags mergeNamespaceWithParent or mergeNamespaceWithRoot. The empty file reference namespace is then removed. To forcibly delete all objects, use flag force. The empty file reference namespace is then 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)	boolean
Save the specified file. Returns the name of the saved file.
saveReference(sr)	boolean
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.
compress(cmp)	boolean
When used with save, it will compress (gzip) the file on output.
preserveName(pn)	boolean
When used with compress, it will retain the regular extension rather than appending .gz.
removeDuplicateNetworks( rdn)	boolean
When set, Maya will remove imported networks if the same network is also detected in the current scene. This flag can only be used in conjunction with the import flag.
resetError(rer)	boolean
Turn off any pre-existing global file errors.
selectAll(sa)	boolean
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. The default behaviour is to replace the existing selection. Use with the "add" flag to keep the active selection list.
add(add)	boolean
When used with selectAll it indicates that the specified items should be added to the active list without removing existing items from the active list.
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)	boolean
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)	boolean
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)	boolean
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.
saveReferencesUnloaded( sru)	boolean
This flag can only be used in conjunction with the save flag. It specifies that the saved file will be saved with all references unloaded.
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)	boolean
Returns boolean. Queries whether the specified reference file uses namespaces or renaming prefixes.
unresolvedName(un)	boolean
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)	boolean
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)	boolean
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.
segment(seg)	string
This flag is obsolete.
activate(a)	boolean
This flag is obsolete.
exportAsSegment(exs)	boolean
This flag is obsolete.
exportSelectedNoReference( esr)	boolean
This flag is obsolete.
moveSelected(ms)	boolean
This flag is obsolete.
applyTo(at)	string
When importing or referencing an offline edit file, apply it to to the given reference (i.e. determine what <main> gets mapped to). So specify the reference node name. To apply the edit to nodes in the main scene (i.e. the root namespace) pass in ":". Must be used with the file -i/-import or -r/-reference flags.
mapPlaceHolderNamespace( mns)	[string, string]
Map a placeHolderNamespace to the given reference. Must be used with the file -i/-import, -r/-reference flags in create mode. The first string is the place holder namespace, including the angle brackets (ex: "<foo>"). The second string is the reference node whose namespace it should be mapped to (ex: "refRN"). If the namespace should be mapped to the root namespace, use ":".
replaceName(rep)	[string, string]
Define a search and replace string. Will apply search and replace to leaf node names. The search string can include namespaces and wild-cards, but will only apply to leaf nodes in a dag hierarchy. Intended for use with offline edits files. Must be used with file -import/-i or -reference/-r. If a nested reference also defines a substitution, it will become the active substitution table while loading the nested reference. Note: if used with the -edit/-e flag, the replacement will only be applied the next time the reference is loaded Examples: -replace "*pCube1" "prop" will change "foo:pCube1" to "foo:prop" and "|A:pCube1|B:pCube1" to "|A:pCube1|prop".
relativeNamespace(rns)	string
This flag can be used with the exportSelected and exportAll operations to specify that the nodes in the exported file are to be written out relative to a specified namespace. This provides the ability to remove undesired levels of namespacing from the node names as they are exported. The relativeNamespace value specifies the namespace to use as the relative root for the exported nodes, and must be specified as an absolute namespace. Nodes in the exported file not residing within the specified relative namespace will be written out using absolute namespace names. Note: this flag cannot be used in conjunction with the preserveReferences flag.

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 have multiple arguments, passed either as a tuple or a list.

Python examples

import maya.cmds as cmds

# save the current scene to an ascii file named "fred.ma"
#
cmds.file( rename='fred.ma' )
cmds.file( save=True, type='mayaAscii' )
# save the current scene to an ascii file without the ".ma" extension
#
cmds.file( rename='tmp' )
cmds.file( save=True, defaultExtensions=False, 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.
#
cmds.file( 'fred.ma', open=True )
# reference the file wilma.ma
#
cmds.file( 'C:/mystuff/wilma.mb', reference=True )
# reference the file barney.mb into a namespace called "rubble".
#
cmds.file( 'C:/maya/projects/default/scenes/barney.ma', reference=True, type='mayaAscii', namespace='rubble' )
# change the namespace containing barney.mb.
#
cmds.file( 'C:/maya/projects/default/scenes/barney.ma', edit=True, namespace='purpleDinosaur' )
# retrieve a string array of all files such as main scene and reference files in the scene
#
cmds.file( query=True, list=True )
# 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.
#
cmds.file( 'c:/mystuff/betty.mb', type='mayaBinary', namespace='rubble', exportAsReference=True )
# Select all the objects associated with file betty.mb
#
cmds.file( 'c:/mystuff/betty.mb', selectAll=True )
# Result: rubble:betty
# Remove the reference file betty.mb. All nodes in betty.mb will
# be removed from the scene
cmds.file( 'c:/mystuff/betty.mb', removeReference=True )
# Query whether the file named "foo.mb" exists on disk
#
cmds.file( 'foo.mb', query=True, exists=True )
# Result: 0 #
# Query whether the reference node "rubble:betty is deferred loaded.
# Note, -referenceNode flag has to come before -q flag.
cmds.file(referenceNode='rubbleRN', query=True, deferReference=True )
# Query the last temp file during file save
#
cmds.file( query=True, lastTempFile=True)
####################################/
#/   Example for the '-buildLoadSettings' and '-loadSettings' flags  #/
####################################/
# Build load settings for "ref.ma"
cmds.file( 'ref.ma', open=True, buildLoadSettings=True )
# 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) .
# cmds.loadSettings( '2', deferReference=1 )
# Use the edited settings when opening the file
cmds.file('ref.ma', open=True, loadSettings='implicitLoadSettings')
#
#   Example for the '-cleanReference' and '-editCommand' flags
#
# Create a simple reference to a sphere
#
cmds.file( force=True, new=True )
cmds.polySphere()
cmds.file( rename='ref.ma' )
cmds.file( force=True, type='mayaAscii', save=True )
cmds.file( force=True, new=True )
cmds.file( 'ref.ma', reference=True, namespace='ref' )
# Scale the sphere
#
cmds.setAttr( 'ref:pSphere1.s', 5, 5, 5 )
cmds.getAttr( 'ref:pSphere1.s' )
# Result: 5 5 5 #
# The 'cleanReference' and 'editCommand' flags only work on
# unloaded references.
#
cmds.file( unloadReference='refRN' )
# Query the setAttr edits:
#
cmds.reference( referenceNode='refRN', query=True, editCommand=True )
# Result: setAttr ref:pSphere1.s -type "double3" 5 5 5 setAttr ref:lightLinker1.lnk -s 2 #
# Remove all setAttr edits on refRN:
#
cmds.file( cleanReference='refRN', editCommand='setAttr' )
cmds.reference( referenceNode='refRN', query=True, editCommand=True )
# Note that nothing is returned
cmds.file( loadReference='refRN' )
cmds.getAttr( 'ref:pSphere1.s' )
# Result: 1 1 1 #
# Note that scale has returned to 1 1 1
# apply the edit file to a reference
cmds.file("translateSphere.editMA", reference=True, applyTo="refRN")
# Result: maps <main> to refRN's namespace
# apply the edit file to nodes in the main scene
cmds.file("translateSphere.editMA", import=True, applyTo=":")
# Result: maps <main> to the root namespace
# apply the edit file to a reference, but it also has connections between two refs
cmds.file("connectionsBetweenRefs.editMA", reference=True, applyTo="refRN", mapPlaceHolderNamespace=("<otherRef>", "otherRefRN"))
# Result: maps <main> to refRN's namespace and <otherRef> to otherRefRN's namespace
# Change the modified state of the file.
cmds.file(modified=True)
# Set the file options
cmds.file( force=True, save=True, options='v=1;p=17',type='mayaAscii');
# Result:The saved file uses full names for attributes on nodes and flags in command.Also the precision of values in file is 17.
# Load Reference Preview
# Create a nested reference with a child reference under a parent reference.
cmds.file( force=True, new=True )
cmds.polySphere()
cmds.file( rename='child.ma' )
cmds.file( force=True, type='mayaAscii', save=True )
cmds.file( force=True, new=True )
cmds.file( 'child.ma', reference=True, namespace='child_namespace' )
cmds.file( rename='parent.ma' )
cmds.file( force=True, type='mayaAscii', save=True )
# Preview the unloaded child reference under the unloaded parent reference.
cmds.file( force=True, new=True )
cmds.file( 'parent.ma', reference=True, namespace='parent_namespace' )
cmds.file( 'parent.ma', unloadReference=True )
cmds.file( 'parent.ma', loadReferencePreview=True )
#
#                          Example for 'mergeNamespacesOnClash'
#
# Create a reference
cmds.file( force=True, new=True )
cmds.namespace( add="bar" )
cmds.namespace( set="bar" )
cmds.polySphere();
cmds.file( rename="ref.ma" )
cmds.file( force=True, type='mayaAscii', save=True )
# Create a scene with some namespaces and objects
cmds.file( force=True, new=True )
cmds.namespace( add="ref:foo:bar" )
cmds.namespace( set="ref:foo:bar" )
cmds.polySphere();
# Merge into root
cmds.file('ref.ma', reference=True, mergeNamespacesOnClash=True, namespace=':');
# Merge into nested namespace
cmds.file('ref.ma', import=True, mergeNamespacesOnClash=True, namespace=':ref:foo');
# Don't merge namespace
cmds.file('ref.ma', reference=True, mergeNamespacesOnClash=False, namespace=':ref:foo');
# Now Edit the new namespace and merge it
cmds.file('ref.ma', edit=True, mergeNamespacesOnClash=True, namespace=':ref:foo');
###############################################/
#/ Example for export with relativeNamespace  #/
###############################################/
cmds.file(new=True,force=True)
cmds.sphere(name=":A:sphereA")
cmds.sphere(name=":A:B:sphereB")
cmds.sphere(name=":A:B:C:sphereC")
cmds.sphere(name=":D:sphereD")
# Select all the spheres.
#
cmds.select(":A:sphereA", replace=True)
cmds.select(":A:B:sphereB",add=True)
cmds.select(":A:B:C:sphereC",add=True)
cmds.select(":D:sphereD",add=True)
# Export all these spheres with -relativeNamespace flag.
#
cmds.file(rename="exp.ma")
cmds.file(force=True, exportSelected=True, type="mayaAscii", relativeNamespace=":A:B")
# The result in the exported file:
# :A:sphereA
# :C:sphereC
# :D:sphereD
# -sphereB
#