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

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.

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.

Querying file names

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

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
activate(a)	boolean
This flag is obsolete.
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.
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.
anyModified(amf)	boolean
This flag is obsolete. Please use file -q -modified instead.
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). Specify the reference node name as argument. To apply the edits to nodes in the main scene (i.e., the root namespace), pass in ":". To collapse <main> (i.e., map it to "None"), pass in "". May only be used with the file -i/import or -r/reference flags.
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.
channels(chn)	boolean
For use with exportSelected to specify whether attached channels 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.
command(c)	[string, string]
Specifies the callback to execute before any file operation. This is an internal flag used only in the file format.
compress(cmp)	boolean
When used with save, it will compress (gzip) the file on output.
constraints(con)	boolean
For use with exportSelected to specify whether attached constraints should be included in the export.
constructionHistory(ch)	boolean
For use with exportSelected to specify whether attached construction history 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.
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.
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.
editCommand(ec)	string
For use with cleanReference. Remove only this type of edit. Supported edits are: setAttr addAttr deleteAttr connectAttr disconnectAttr and parent
errorStatus(err)	boolean
Query the error status of the last file read. Returns true if and error occurred during the last file read.
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.
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.
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.
exportAsSegment(exs)	boolean
This flag is obsolete.
exportSelected(es)	boolean
Export the selected items into the specified file. Returns the name of the exported file.
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.
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.
exportSelectedNoReference(esr)	boolean
This flag is obsolete.
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.
expressions(exp)	boolean
For use with exportSelected to specify whether attached expressions should be included in the export.
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.
force(f)	boolean
Force an action to take place. (new, open, save, remove reference, unload 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. Used with unloadReference to force unload reference even if the reference node is locked, without prompting a dialog that warns user about the lost of edits.
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. May only be used with the -o flag.
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.
lastFileOption(lfo)	boolean
On query, returns the last option string used by the file command.
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.
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.
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 -i/import, -r/reference or -lr/loadReference flags, will load the top-most reference only.
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.
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. May only be used with the -o/open, -i/import, -r/reference or -lr/loadReference flags. When "none" is used with -lr/loadReference, only path validation is performed. This can be used to replace a reference without triggering reload. Not using loadReferenceDepth will load references in the same loaded or unloaded state that they were in when the file was saved. Additionally, the -lr/loadReference flag supports a fourth type, "asPrefs". This will force any nested references to be loaded according to the state (if any) stored in the current scene file, rather than according to the state saved in the reference file itself.
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.
location(loc)	boolean
Query the location of the given file name.
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.
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.
lockReference(lck)	boolean
Locks attributes and nodes from the referenced file.
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 ":". To collapse the namespace (i.e., map it to "None"), use "". When queried, namespaces that are mapped to "None" will return "(None)" for clarity.
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.
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.
modified(mf)	boolean
Set the modified state of the entire scene. If the scene is modified it 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 scene has been modified 1 is returned. Otherwise 0 is returned.
moveSelected(ms)	boolean
This flag is obsolete.
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.
newFile(new)	boolean
Initialize the scene. Returns untitled scene with default location.
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.
parentNamespace(pns)	boolean
Returns the name(s) of a referenced file's parent namespaces.
postSaveScript(pos)	string
When used with the save flag, the specified script will be executed after the file is saved.
preSaveScript(prs)	string
When used with the save flag, the specified script will be executed before the file is saved.
preserveName(pn)	boolean
When used with compress, it will retain the regular extension rather than appending .gz.
preserveReferences(pr)	boolean
Modifies the various import/export flags such that references are imported/exported as actual references rather than copies of those references.
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.
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.
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
This flag is only used during queries. In MEL, if it appears before -query then it must be followed by the name of one of the scene's reference nodes. That will determine the reference to be queried by whatever flags appear after -query. If the named reference node does not exist within the scene the command will fail with an error. In Python the equivalent behavior is obtained by passing the name of the reference node as the flag's value. In MEL, if this flag appears after -query then it takes no argument and will cause the command to return the name of the reference node associated with the file given as the command's argument. If the file is not a reference or for some reason does not have a reference node (e.g., the user deleted it) then an empty string will be returned. If the file is not part of the current scene then the command will fail with an error. In Python the equivalent behavior is obtained by passing True as the flag's value. In query mode, this flag can accept a value.
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.
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 -i/import flag.
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.
rename(rn)	string
Rename the scene. Used mostly during save to set the saveAs name. Returns the new name of the scene.
renameAll(ra)	boolean
If true, rename all newly-created nodes, not just those whose names clash with existing nodes. Only available with -i/import.
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.
renamingPrefix(rpr)	string
The string to use as a prefix for all objects from this file. This flag has been replaced by -ns/namespace.
renamingPrefixList(rpl)	boolean
This flag returns a list of all of the renaming prefixes used by the file.
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. May only be used with file -i/import or -r/reference. 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 -e/edit 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".
resetError(rer)	boolean
Turn off any pre-existing global file errors.
returnNewNodes(rnn)	boolean
Used to control the return value in open, import, loadReference, and reference operations. It will force the file command to return a list of new nodes added to the current scene.
save(s)	boolean
Save the specified file. Returns the name of the saved file.
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").
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.
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.
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").
sceneName(sn)	boolean
return the name of the current scene.
segment(seg)	string
This flag is obsolete.
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 behavior is to replace the existing selection. Use with the "add" flag to keep the active selection list.
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.
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.
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.
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. May only be used with the -o/open, -i/import, -ir/importReference or -r/reference flags.
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.
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.
unloadReference(ur)	string
This flag will unload the reference file associated with the passed reference node.
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.
usingNamespaces(uns)	boolean
Returns boolean. Queries whether the specified reference file uses namespaces or renaming prefixes.
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.
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.

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.mb
#
cmds.file( 'C:/mystuff/wilma.mb', reference=True )

# get the name of the reference node for wilma.mb
cmds.file( 'C:/mystuff/wilma.mb', query=True, referenceNode=True )
# Result: wilmaRN #

# does the wilmaRN reference node represent a deferred reference?
cmds.file(query=True, referenceNode='wilmaRN', deferReference=True)
# Result: False #

# 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", i=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', i=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
#