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

Synopsis

referenceEdit [-applyFailedEdits] [-changeEditTarget string string] [-editCommand string] [-failedEdits boolean] [-onReferenceNode string] [-removeEdits] [-successfulEdits boolean]

referenceEdit is NOT undoable, NOT queryable, and NOT editable.

Use this command to remove and change the modifications which have been applied to references. A valid commandTarget is either a reference node, a reference file, a node in a reference, or a plug from a reference. Only modifications that have been made from the currently open scene can be changed or removed. The 'referenceQuery -topReference' command can be used to determine what modifications have been made to a given commandTarget. Additionally only unapplied edits will be affected. Edits are unapplied when the node(s) which they affect are unloaded, or when they could not be successfully applied. By default this command only works on failed edits (this can be adjusted using the "-failedEdits" and "-successfulEdits" flags). Specifying a reference node as the command target is equivalent to specifying every node in the target reference file as a target. In this situation the results may differ depending on whether the target reference is loaded or unloaded. When it is unloaded, edits that affect both a node in the target reference and a node in one of its descendant references may be missed (e.g. those edits may not be removed). This is because when a reference is unloaded Maya no longer retains detailed information about which nodes belong to it. However, edits that only affect nodes in the target reference or in one of its ancestral references should be removed as expected. When the flags -removeEdits and -editCommand are used together, by default all connectAttr edits are removed from the specified source object. To remove only edits that connect to a specific target object, the target object can be passed as an additional argument to the command. This narrows the match criteria, so that only edits that connect the source object to the provided target in this additional argument are removed. See the example below. NOTE: When specifying a plug it is important to use the appropriate long attribute name.

Return value

None

Keywords

reference, attribute, node

Related

file, referenceQuery

Flags

applyFailedEdits, changeEditTarget, editCommand, failedEdits, onReferenceNode, removeEdits, successfulEdits
Long name (short name) Argument types Properties
-applyFailedEdits(-afe) create
Attempts to apply any unapplied edits. This flag is useful if previously failing edits have been fixed using the -changeEditTarget flag. This flag can only be used on loaded references. If the command target is a referenced node, the associated reference is used instead.
-changeEditTarget(-cet) string string create
Used to change a target of the specified edits. This flag takes two parameters: the old target of the edits, and the new target to change it to. The target can either be a node name ("node"), a node and attribute name ("node.attr"), or just an attribute name (".attr"). If an edit currently affects the old target, it will be changed to affect the new target. Flag 'referenceQuery' should be used to determine the format of the edit targets. As an example most edits store the long name of the attribute (e.g. "translateX"), so when specifying the old target, a long name must also be used. If the short name is specified (e.g. "tx"), chances are the edit won't be retargeted.
-failedEdits(-fld) boolean create
This is a secondary flag used to indicate whether or not failed edits should be acted on (e.g. queried, removed, etc...). A failed edit is an edit which could not be successfully applied the last time its reference was loaded. An edit can fail for a variety of reasons (e.g. the referenced node to which it applies was removed from the referenced file). By default failed edits will be acted on.
-removeEdits(-r) create
Remove edits which affect the specified unloaded commandTarget.
-successfulEdits(-scs) boolean create
This is a secondary flag used to indicate whether or not successful edits should be acted on (e.g. queried, removed, etc...). A successful edit is any edit which was successfully applied the last time its reference was loaded. This flag will have no affect if the commandTarget is loaded. By default successful edits will not be acted on.
-editCommand(-ec) string createquerymultiuse
This is a secondary flag used to indicate which type of reference edits should be considered by the command. If this flag is not specified all edit types will be included. This flag requires a string parameter. Valid values are: "addAttr", "connectAttr", "deleteAttr", "disconnectAttr", "parent", "setAttr", "lock" and "unlock". In some contexts, this flag may be specified more than once to specify multiple edit types to consider.
-onReferenceNode(-orn) string createquerymultiuse
This is a secondary flag used to indicate that only those edits which are stored on the indicated reference node should be considered. This flag only supports multiple uses when specified with the "exportEdits" command.
Flag can appear in Create mode of command Flag can appear in Edit mode of command
Flag can appear in Query mode of command Flag can be used more than once in a command.

MEL examples

//
// EXAMPLE FOR -removeEdits
//
// Assume:
// main.ma contains a reference to mid.ma.
// mid.ma contains a reference to bot.ma.
// NOTE: The target reference must be unloaded for the
// following commands to work.
// Remove all the edits which apply to mid.ma.
// This can be done by specifying either the reference
// node or the reference file.
referenceEdit -removeEdits midRN;
referenceEdit -removeEdits "mid.ma";
// Remove all "setAttr" edits which apply to mid.ma.
// This can be done by specifying either the reference
// node or the reference file.
referenceEdit -editCommand "setAttr" -removeEdits midRN;
referenceEdit -editCommand "setAttr" -removeEdits "mid.ma";
// Remove all the "parent" edits which apply to mid:pSphere1.
referenceEdit -editCommand "parent" -removeEdits mid:pSphere1;
// Remove all the "connectAttr" edits which apply to mid:pSphere1.translateX.
referenceEdit -editCommand "connectAttr" -removeEdits mid:pSphere1.translateX;
// Remove the "connectAttr" edit having mid::pSphere1.translateX as a source and mid:pSphere2.translateX as a destination
referenceEdit -failedEdits true -successfulEdits true -editCommand connectAttr -removeEdits "|mid:pSphere1.translateX" "|mid:pSphere2.translateX";
// Remove all the edits which apply to bot.ma and are stored on midRN.
// The referenceEdit command is only capable of removing edits which
// are stored on a top level reference node. The only edits which
// are stored on a top level reference node are those which were made
// from the main scene. If the file mid.ma was previously opened and
// modifications were made to bot.ma, those edits can only be removed
// by opening mid.ma and issuing a referenceEdit command.
//
referenceEdit -removeEdits mid:botRN;
referenceEdit -removeEdits "bot.ma";
//
// EXAMPLE FOR -changeEditTarget
//
string $tempDir = `internalVar -utd`;
// Create a reference containing pSphere1.
//
file -f -new;
polySphere -r 1 -sx 20 -sy 20 -ax 0 1 0 -ch 1;
file -rename ($tempDir + "ref.ma");
file -f -type "mayaAscii" -save;
// Reference the file in and position pSphere1
//
file -f -new;
file -r -ns "ref" ($tempDir + "ref.ma");
select -r ref:pSphere1;
move 5 5 5;
file -rename ($tempDir + "top.ma");
file -f -type "mayaAscii" -save;
// Later on its determined that pSphere1 is actually
// BobMrozowski.
//
file -f -o ($tempDir + "ref.ma");
rename pSphere1 BobMrozowski;
file -f -type "mayaAscii" -save;
// Now go to open your main scene again...
//
file -f -o ($tempDir + "top.ma");
// ... and notice that BobMrozowski is back at
// the origin.
//
// So remap all edits so that anything that used to
// affect ref:pSphere1 now affects ref:BobMrozowski...
//
referenceEdit -changeEditTarget "ref:pSphere1" "ref:BobMrozowski" "refRN";
// ... and then force all previously failing edits affecting
// refRN to be re-applied.
//
referenceEdit -applyFailedEdits "refRN";
// BobMrozowski should now be back at 5 5 5.
//