Perforce – Shotgun Sync

Perforce Shotgun Sync

This app contains the sync command used to sync Perforce changes into Shotgun

By: Shotgun Software
Latest Version: v0.1.5 (alpha)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-shell-perforcesync


This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations User Guide for details. This app is the link between Perforce and Shotgun. Newly submitted Perforce changes containing files recognised by Toolkit will have a Revision entity created for them in Shotgun and each file revision will have a PublishedFile entity registered. The app can be run as a background process/daemon to ensure that Shotgun is kept in sync with Perforce.


We're currently working on the docs for this app but in the mean time, for a more high-level overview of how we've integrated Perforce into Shotgun Pipeline Toolkit, please see this page:

Sync Perforce with Shotgun.

To sync specific changes between Perforce and Shotgun use the sync_perforce command that this app registers. It's intended that this should be run using the project context, e.g.:

./tank Project <project id> sync_perforce -s <start change> -e <end change> -u <perforce user> -p <perforce password>

The command will only register changes and published files if they aren't already registered with Shotgun.

Sync Daemon

To continually sync new changes as they are submitted to Perforce, you can use the sync_perforce_daemon command which should be set up as a background process running on a server (how to do this will vary depending on your OS - more details to come!).

Run the sync daemon command like:

./tank Project <project id> sync_perforce_daemon -u <perforce user> -p <perforce password>

Large number of pre-existing changes

If you are using a Perforce server that contains a large number of changes that you know for certain Toolkit will be able to ignore, you can also pass a start argument to the daemon command - you only need to do this the first time the daemon is run though.

./tank Project <project id> sync_perforce_daemon -s 123456 -u <perforce user> -p <perforce password>

Related Apps and Documents

Perforce Integration

This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the [Shotgun Integrations Admin Guide]( for details. This document describes the Perforce integration for Toolkit - what it is, who it is aimed at and a high level overview of how it is implemented.

Installation and Updates

Adding this App to the Shotgun Pipeline Toolkit

If you want to add this app to Project XYZ, in an environment named asset, execute the following command:

> tank Project XYZ install_app asset tk-shell tk-shell-perforcesync

Updating to the latest version

If you already have this item installed in a project and you want to get the latest version, you can run the update command. You can either navigate to the tank command that comes with that specific project, and run it there:

> cd /my_tank_configs/project_xyz
> ./tank updates

Alternatively, you can run your studio tank command and specify the project name to tell it which project to run the update check for:

> tank Project XYZ updates

Collaboration and Evolution

If you have access to the Shotgun Pipeline Toolkit, you also have access to the source code for all apps, engines and frameworks in Github where we store and manage them. Feel free to evolve these items; use them as a base for further independent development, make changes (and submit pull requests back to us!) or simply tinker with them to see how they have been built and how the toolkit works. You can access this code repository at

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.14.43 or higher to use this.
  • You need Engine version v0.3.6 or higher to use this.


Below is a summary of all the configuration settings used. These settings need to be defined in the environment file where you want to enable this App or Engine.


Type: int

Default Value: 5

Description: Interval in seconds that the daemon will poll for new changes

Release Notes

Welcome to the release notes for this App. Below you will find an overview of all the changes we did for each release. We try to be as detailed as possible and include all bugs we have fixed, features we have added and things that may have changed. If you have questions about a particular release, don't hesitate to contact our support team!


Fixed core v0.15 compatibility issue


Ticker message is now only output when running with debug enabled!


Fixed minor bug with some fallback code to handle a legacy Shotgun field issue


Added additional debug output and error checking


Updated documentation


Several minor improvements:

Details: - Added sg_workspace as a required field & updated to use the new published_files field on the Revision entity - App no longer requires/uses Perforce workspace for user - Updated to use new framework versioning syntax - Removed some old code


Review data for publishes is now handled correctly


Dependencies are now handled correctly


Various improvements and fixes

Details: - commands can now take Perforce user and password as arguments - Creation of changes is now atomic so that multiple daemons can be run at the same time - Deletions are no longer synced to Shotgun - a url is now used to store the published file depot path in Shotgun - Lots of other fixes!


Updated to require latest version of the Perforce framework


Minor fixes and improvements


Publish data is now loaded using framework prior to registering publishes


Initial Release