Version Control


Setting up Perforce

  • Set up a workspace on your local machine
  • Note the following information; you will need it to set up Version Control in SD:

Workspace Name

Workspace Path

Setting up Version Control in Substance Designer

  • Open the Preferences panel
  • Go to the "Version Control" tab
    • Check "Version Control Enabled"



  • Fill in workspace information:
    • Name: enter the "Workspace Name" you previously retrieved from P4V.
    • Path: enter the "Workspace Path" you previously retrieved from P4V.

Setup Actions:

The actions will be available in the contextual menu of a package in the Explorer. There are predefined actions that match most Version Control tool concepts:

To be available, the package needs to be saved under the "Workspace Path" (Ex: under "f:/Dev/perforce")
    • All action labels can be changed as needed.

    • All actions need a script in order to be valid.

You can use:

    • one script per action
      OR
    • one script for all actions

For the Perforce integration, we choose to use one script for all actions.

Setup

    • In the "Actions" group, click on the "..." button of the "Add" action
    • Select the following script: "tools/version_control/perforce.py"
    • The script should automatically be set up for all other actions

Add Custom Actions

As all Version Control tools are different and include many features, we allow the user to add custom actions.

    • Click on "Add Item"

    • Fill in the label of the new action, and set its script:

 Set up the Script Interpreter

    • Depending on the script type that you use for your action, you will need to specify some interpreters to evaluate your scripts - Python scripts will require an interpreter, for example.
    • In the "Interpreters" group, click on "Add Item".

    • Set a script file extension (or suffix) and the path of the interpreter.


    • Edit the perforce.py to set the location of the "p4" binary.

How to Use Version Control

  • Create a new package
  • Save the package in the "Workspace Path" directory 
  • Right-click on the package; you now have access to the "Version Control" submenu:

  • You find several actions depending on the status of the package file in the workspace:
    • "Add": Mark the files as "ToAdd" 
    • "Submit": Submit the selected packages
      • When submitting changes, a dialog box appears allowing you to enter a change message:
  • "Revert": Revert the modification
    • The Revert action will create a dialog box to select files to revert:
    • "Checkout": Check the file out from the depot
    • "Get Last Version": Retrieve the latest version from the depot
    • "Refresh Status": Refresh the package file status

Information:

  • All actions support multi-selection
  • Read-only package files can't be modified in SD. 
    • For Perforce and other Version Control tools that use read-only file permission to restrict modifications, the user will first have to check out the package before modifying it.
  • The package will have the following icons, depending on its status:

Action Scripts

The scripts associated with each action are named using the following syntax: my_script WorkspaceName WorkspacePathActionName[ActionArgs]

    • WorkspaceName: the name of the workspace

    • WorkspacePath: the path of the root directory of the workspace
    • ActionNamethe name of the action:
      • "add": for the "Add" action
      • "checkout": for the "Checkout" action
      • "submit": for the "Submit" action
      • "revert": for the "Revert" action
      • "get_last_version": for the "Get Last Version" action
      • "get_status": for the "Get Status" action
      • The Label set up in the SD Preferences panel (with ' ' character replaced by '_')
        • Ex: "My Action" => "My_Action"
    • ActionArgs: arguments of the action:
      • "-desc: Description":
        • A description string.
        • Used by "Submit" action
      • "-files: Files":
        • list of files
      • "-files_list: File":
      • a text file that contains a list of files per line


The script will return certain values depending on the action carried out:

    • "get_status"
      • returns a value depending of the status of the specified file:
        • 0: Undefined status
        • 1: file is not in the depot
        • 2: file is a previous version (it is not up to date)
        • 3: file is at the latest version (it is up to date)
        • 4: file is checked out
        • 5: file is marked for addition
    • other actions:
      • 0: success
      • other: error

     


In this page