Revision Control and Asset Diff

Which revision control provider is connected and what it supports

Reports the editor's revision control provider (Git, Perforce...), whether it is enabled and reachable, the features it has (check_out, changelists, file_revisions, snapshots, read_only_files, diff_against_depot) and every provider that can be connected. Run it first: a provider without check_out (Git) needs no check_out_assets.

  cfa revision_control_status

Switch the editor to a revision control provider

Selects a provider by name and logs in with the settings it already has saved (server, workspace, repository). It never takes a password. Provider None turns revision control off. When the provider cannot connect, the editor stays on the provider it had and the error carries the provider's own status text and the fix: set it up once in the editor under Revision Control > Connect to Revision Control.

  cfa connect_revision_control --provider Git
  cfa connect_revision_control --provider None

Revision control state of assets or folders (Refresh)

Asks the provider for the current state of each asset or of every file under a content folder: checked_out, added, deleted, modified, conflicted, out_of_date, deleted_in_depot (another user deleted it and this file is an older copy), who else has it checked out, and what can be done next (can_check_out, can_check_in, can_add, can_revert). With no paths it lists every changed file in the project, which answers 'what did I change'. A provider reports files in a folder only when it knows them, so an unchanged file can be missing from a folder listing.

  cfa get_revision_control_state
  cfa get_revision_control_state --paths /Game/Data/DA_Hero
  cfa get_revision_control_state --paths /Game/Data --changed-only=true --filter modified

An asset's submitted revisions, newest first

Lists each submitted revision of an asset: revision, number, changelist, user, date, action, description and size. Use a revision, a number or a changelist from here wherever another command takes a revision.

  cfa get_asset_history --asset /Game/Data/DA_Hero
  cfa get_asset_history --asset /Game/Blueprints/BP_Door --filter "balance" --max-results 5

Check assets out for editing

Checks the assets out and returns each file's state as the provider reports it afterwards, with verdict pass when all are checked out. The whole call is refused, with a reason per file, when one is not under revision control, is checked out by someone else, is out of date or is in conflict. A provider without check out (Git) is refused with the reason: its files are always writable. On Subversion a check out is a lock. A provider_warning in the reply is the provider's own note, such as a stream that can never submit this file.

  cfa check_out_assets --assets /Game/Data/DA_Hero --assets /Game/Data/DA_Villain

Mark new assets for add

Marks assets that are not yet under revision control for add. Save a new asset first, or it has no file to add. An asset that is already added or already in the depot passes and is left as it is. Returns each file's state after, with a verdict.

  cfa mark_assets_for_add --assets /Game/Data/DA_NewHero

Check assets in with a description

Submits the assets. An asset with unsaved changes is refused, because the check-in would send the old file: run save_asset first. The whole call is also refused, with a reason per file, when one is not added yet, has nothing to check in, is out of date or is in conflict. Returns each file's state after, with a verdict.

  cfa check_in_assets --assets /Game/Data/DA_Hero --description "Raise hero health to 150"

Throw away local changes to assets

Reverts the assets to the depot version and reloads them in the editor. Everything changed in them is lost, unsaved edits included. To take back one value and keep the rest, use restore_asset_property. An asset that is only marked for add is refused: it has no depot version and the editor's revert would delete its file, so drop it with delete_asset or keep it with check_in_assets. A loaded level cannot be reverted while it is open.

  cfa revert_assets --assets /Game/Data/DA_Hero

Sync assets to the latest or a given revision

Syncs the assets to the latest and reloads them in the editor. With --revision it puts ONE asset back to an older revision (go back in time), and a later sync without --revision brings it forward to the latest again. That needs a provider with per-file revisions (Perforce); on a provider without them (Git, whose sync always pulls the whole branch) --revision is refused with what to use instead, and on Subversion, whose provider cannot go back, the reply says the asset went to the latest instead. An old-revision file is a local view, not a new check-in: to make old content the newest revision, take the values back with restore_asset_property and check in. An asset with unsaved changes is refused, because the reload would drop them. An asset that is checked out or changed here while a newer revision is in the depot is refused too: a sync cannot merge a binary asset, so revert_assets it first. An asset that another user deleted is removed here by the sync.

  cfa sync_assets --assets /Game/Data/DA_Hero
  cfa sync_assets --assets /Game/Data/DA_Hero --revision 12

Pending changelists of this workspace, or the files and shelf of one

With no changelist it lists every pending changelist of this workspace: id, description, file_count and shelved_count. With --changelist it opens one and lists its files, each with its state and flags, and its shelved assets by name. Needs a provider with changelists (Perforce, Plastic); Git and Subversion are refused with what to use instead. Changelists of other workspaces are not listed.

  cfa list_changelists
  cfa list_changelists --changelist 1234
  cfa list_changelists --changelist default --filter BP_Door

Create a pending changelist, with assets in it when given

Creates a pending changelist with the description and returns its id. With --assets it moves those assets into it in the same step; they must be checked out or marked for add already, or the call is refused with the fix. The reply is the changelist as the provider reports it afterwards, with a verdict.

  cfa create_changelist --description "Door rework" --assets /Game/BP_Door --assets /Game/M_Door

Change a changelist's description

Changes the description of a pending changelist and reads it back for the verdict. The default changelist has none to set.

  cfa set_changelist_description --changelist 1234 --description "Door rework, second pass"

Move checked-out assets into another changelist

Moves assets that are checked out or marked for add into a pending changelist, or back to the default one with --changelist default. An asset that is not open is refused: check it out first. The reply is the target changelist afterwards, with verdict pass when it holds every given asset.

  cfa move_assets_to_changelist --assets /Game/BP_Door --changelist 1234
  cfa move_assets_to_changelist --assets /Game/BP_Door --changelist default

Delete an empty pending changelist

Deletes a pending changelist that holds no files and no shelf. One that is not empty is refused with what to run first. The default changelist cannot be deleted.

  cfa delete_changelist --changelist 1234

Check in every file of one changelist

Submits a whole pending changelist under its own description, or under --description when given (required for the default changelist). Refused, with the reason, when an asset in it has unsaved changes, when the changelist still holds a shelf (run delete_shelved_assets first), or when a file is out of date or in conflict. Returns the provider's message with the submitted number, file_count, the state of the first 20 files and a verdict that covers all of them. To check in only some assets, use check_in_assets.

  cfa check_in_changelist --changelist 1234
  cfa check_in_changelist --changelist default --description "Fix the door angle"

Shelve the files of a changelist

Stores a copy of a changelist's files on the server as a shelf, for a backup or a review. The files stay checked out with their content. --assets shelves only those assets of the changelist. A shelf needs a numbered changelist, so for --changelist default pass --description: the provider moves the files into a new changelist and the reply names it. An asset with unsaved changes is refused, because the shelf would get the old file.

  cfa shelve_assets --changelist 1234
  cfa shelve_assets --changelist default --description "Door rework, for review"

Put shelved content back into the workspace

Writes the shelved content of a changelist over the workspace files and reloads those assets in the editor. An asset that is still checked out here, or has unsaved changes, is refused: revert_assets it first, then unshelve. The shelf itself stays on the server. Returns file_count, the state of the first 20 files and a verdict that covers all of them.

  cfa unshelve_assets --changelist 1234
  cfa unshelve_assets --changelist 1234 --assets /Game/BP_Door

Remove files from a changelist's shelf

Deletes shelved files from the server. The workspace files are not touched. A changelist must have no shelf before check_in_changelist or delete_changelist can take it.

  cfa delete_shelved_assets --changelist 1234

Load an old revision of an asset as a read-only copy

Fetches a submitted revision into a temp package, as Diff Against Depot does, and returns its object_path. Pass that path to read commands (export_object, get_object_property, export_graph, describe_object) to see what the asset was. For a list of what changed, use diff_asset.

  cfa load_asset_revision --asset /Game/Data/DA_Hero
  cfa load_asset_revision --asset /Game/Blueprints/BP_Door --revision 7

What changed in an asset: against the depot, between revisions, or against another asset

Compares two versions of any asset through reflection, so a data asset, Blueprint, material, Niagara system, PCG graph, StateTree or Customizable Object all work with no per-type code. The old side is the newest submitted revision by default (Diff Against Depot), an old_revision, or a base_asset (which needs no revision control). The new side is the current in-editor state, or a new_revision. Each change has a kind: property (object + path + old + new, where path is the set_object_property path grammar), object (a sub-object such as a component, material expression or PCG node was added or removed), row (data table rows), or graph (node_added, node_removed, node_moved, node_comment, node_property, pin_default, pin_link_added/removed/moved, pin_type, with the node id, title and the engine's own description). summary counts every change by kind; filter and max_results scope the list. Long values are cut at 240 characters unless full_values is set. export writes the complete diff to Saved/CodeFizzEditorAgent/Exports and returns the path. Feed a property change to restore_asset_property to take the old value back, or read the object it names with get_object_property --asset-path <asset>.<object>. A saved asset is compared from its file, so an open asset editor adds no false changes; an asset with unsaved edits is compared from memory and new.unsaved says so.

  cfa diff_asset --asset /Game/Data/DA_Hero
  cfa diff_asset --asset /Game/Blueprints/BP_Door --filter node_added
  cfa diff_asset --asset /Game/Data/DA_Hero --old-revision 3 --new-revision 5
  cfa diff_asset --asset /Game/Data/DA_Hero --base-asset /Game/Data/DA_Villain --filter Health
  cfa diff_asset --asset /Game/Materials/M_Wall --export=true --max-results 10

Take one value back from an old revision or another asset

Reads one property from the old side and writes it into the current asset, leaving every other change alone: a field, a struct member, an array element or a map entry. Pass property (and object, when the change had one) exactly as diff_asset printed them. An element that did not exist in the old version is removed instead. The edit is one undo step and is not saved; the reply carries before, after and a verdict read back from the asset. Data table rows are edited with update_data_table_row instead.

  cfa restore_asset_property --asset /Game/Data/DA_Hero --property MaxHealth
  cfa restore_asset_property --asset /Game/Data/DA_Hero --property "Prices[Sword]" --revision 3
  cfa restore_asset_property --asset /Game/Data/DA_Hero --property Stats.Armor --base-asset /Game/Data/DA_Villain