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

Synopsis

file( string , [anyModified=boolean], [buildLoadSettings=boolean], [channels=boolean], [cleanReference=string], [command=string], [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], [exportSelected=boolean], [exportSelectedAnim=boolean], [exportSelectedAnimFromReference=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], [loadSettings=string], [location=boolean], [lockContainerUnpublished=boolean], [lockFile=boolean], [lockReference=boolean], [modified=boolean], [namespace=string], [newFile=boolean], [open=boolean], [options=string], [parentNamespace=boolean], [postSaveScript=string], [preSaveScript=string], [preserveReferences=boolean], [prompt=boolean], [reference=boolean], [referenceDepthInfo=uint], [referenceNode=string], [removeReference=boolean], [rename=string], [renameAll=boolean], [renameToSave=boolean], [renamingPrefix=string], [renamingPrefixList=boolean], [returnNewNodes=boolean], [save=boolean], [saveDiskCache=string], [saveReference=boolean], [saveTextures=string], [sceneName=boolean], [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.

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.

Return value

stringThe name of the specified file for most actions.

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

Related

getFileList, namespace, namespaceInfo, referenceEdit, referenceQuery, workspace

Flags

anyModified, buildLoadSettings, channels, cleanReference, command, constraints, constructionHistory, copyNumberList, defaultExtensions, defaultNamespace, deferReference, editCommand, errorStatus, executeScriptNodes, exists, expandName, exportAll, exportAnim, exportAnimFromReference, exportAsReference, exportSelected, exportSelectedAnim, exportSelectedAnimFromReference, expressions, flushReference, force, groupLocator, groupName, groupReference, i, ignoreVersion, importReference, lastFileOption, lastTempFile, list, loadAllDeferred, loadAllReferences, loadNoReferences, loadReference, loadReferenceDepth, loadSettings, location, lockContainerUnpublished, lockFile, lockReference, modified, namespace, newFile, open, options, parentNamespace, postSaveScript, preSaveScript, preserveReferences, prompt, reference, referenceDepthInfo, referenceNode, removeReference, rename, renameAll, renameToSave, renamingPrefix, renamingPrefixList, returnNewNodes, save, saveDiskCache, saveReference, saveTextures, sceneName, selectAll, shader, sharedNodes, sharedReferenceFile, shortName, strict, swapNamespace, type, uiConfiguration, unloadReference, unresolvedName, usingNamespaces, withoutCopyNumber, writable
Long name (short name) Argument types Properties
anyModified(amf) boolean query
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 create
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 create
Specifies the callback to execute before any file operation. This is an internal flag used only in the file format.
constructionHistory(ch) boolean createquery
For use with exportSelected to specify whether attached construction history should be included in the export.
channels(chn) boolean createquery
For use with exportSelected to specify whether attached channels should be included in the export.
copyNumberList(cnl) boolean query
When queried, this flag returns a string array containing a number that uniquely identifies each instance the file is used.
constraints(con) boolean createquery
For use with exportSelected to specify whether attached constraints should be included in the export.
cleanReference(cr) string create
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 create
For use with cleanReference. Remove only this type of edit. Supported edits are: setAttr addAttr deleteAttr connectAttr disconnectAttr and parent
defaultExtensions(de) boolean createquery
Use the default extensions to rename the files.
defaultNamespace(dns) boolean create
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
Query the error status of the last file read. Returns true if and error occurred during the last file read.
deferReference(dr) boolean createquery
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 create
Export everything into a single file. Returns the name of the exported file.
exportAnim(ean) boolean create
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) boolean create
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 create
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 create
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 create
Export the selected items into the specified file. Returns the name of the exported file.
exportSelectedAnimFromReference(esa) boolean create
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 create
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
Query if the file exists. Returns true if the file exists.
expandName(exn) boolean query
This is a query only flag that can be used to query for the file path name of the file.
expressions(exp) boolean createquery
For use with exportSelected to specify whether attached expressions should be included in the export.
force(f) boolean create
Force an action to take place. (new, open, save)
flushReference(fr) string create
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 create
Used only with the -r and the -gr flag. Used to group the output of groupReference under a locator
groupName(gn) string create
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 create
Used only with the -r or the -i flag. Used to group all the imported/referenced items under a single transform.
ignoreVersion(iv) boolean create
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 create
Locks attributes and nodes from the referenced file.
lockFile(lf) boolean create
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 create
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 create
Import the specified file. Returns the name of the imported file.
importReference(ir) boolean create
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 query
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 create
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 create
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 create
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 create
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
Query the location of the given file name.
loadReference(lr) string createquery
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 create
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 query
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 query
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) boolean create
Initialize the scene. Returns untitled scene with default location.
namespace(ns) string edit
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 create
Open the specified file. Returns the name of the opened file.
options(op) string createquery
Set/query the currently set file options.
lastFileOption(lfo) boolean query
On query, returns the last option string used by the file command.
prompt(pmt) boolean createquery
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 query
Returns the name(s) of a referenced file's parent namespaces.
preserveReferences(pr) boolean create
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 create
When used with the save flag, the specified script will be executed before the file is saved.
postSaveScript(pos) string create
When used with the save flag, the specified script will be executed after the file is saved.
reference(r) boolean query
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 create
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 create
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 query
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 create
Rename the scene. Used mostly during save to set the saveAs name. Returns the new name of the scene.
returnNewNodes(rnn) boolean create
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 query
This flag returns a list of all of the renaming prefixes used by the file.
renamingPrefix(rpr) string createquery
The string to use as a prefix for all objects from this file. This flag has been replaced by -ns/namepace.
removeReference(rr) boolean create
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 createquery
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 create
Save the specified file. Returns the name of the saved file.
saveReference(sr) boolean create
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) boolean create
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 createquery
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 createquery
For use with exportSelected to specify whether attached shaders should be included in the export.
sharedNodes(shd) string createmultiuse
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 query
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 query
return the name of the current scene.
swapNamespace(sns) [string, string] createmultiuse
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 create
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 create
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 createquery
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 query
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 createquery
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 query
Returns boolean. Queries whether the specified reference file uses namespaces or renaming prefixes.
unresolvedName(un) boolean query
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 create
This flag will unload the reference file associated with the passed reference node.
writable(w) boolean query
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 query
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 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, de=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', o=True )

# reference the file wilma.ma
#
cmds.file( 'C:/mystuff/wilma.mb', r=True )

# reference the file barney.mb into a namespace called "rubble".
#
cmds.file( 'C:/maya/projects/default/scenes/barney.ma', r=True, type='mayaAscii', namespace='rubble' )

# change the namespace containing barney.mb.
#
cmds.file( 'C:/maya/projects/default/scenes/barney.ma', e=True, namespace='purpleDinosaur' )

# retrieve a string array of all files referenced in the scene
#
cmds.file( q=True, l=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', er=True )

# Select all the objects associated with file betty.mb
#
cmds.file( 'c:/mystuff/betty.mb', sa=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', rr=True )

# Query whether the file named "foo.mb" exists on disk
#
cmds.file( 'foo.mb', q=True, ex=True )
# Result: 0 #

# Query whether the reference node "rubble:betty is deferred loaded.
# Note, -rfn flag has to come before -q flag.
cmds.file(rfn='rubbleRN', q=True, dr=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', o=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', o=True, loadSettings='implicitLoadSettings')

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

# Create a simple reference to a sphere
#
cmds.file( f=True, new=True )
cmds.polySphere()
cmds.file( rename='ref.ma' )
cmds.file( f=True, type='mayaAscii', save=True )
cmds.file( f=True, new=True )
cmds.file( 'ref.ma', r=True, ns='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( rfn='refRN', q=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( rfn='refRN', q=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