Skip to main content
You can import a Perforce depot into a new Diversion repository, history included. The import runs on a machine you provide, called the import host, which needs network access to your Perforce server. Your Perforce password stays on the import host; Diversion never receives it. The Diversion app creates the repository and an API token and generates the configuration file the import host needs. A script on the import host then runs the import in Docker, checking in with Diversion every 5 minutes.

Requirements for the import host

  • One of these:
    • Linux or another Unix: bash, cron, and Docker Engine 20.10 or newer with the Docker Compose plugin 2.17 or newer. Optional: curl and the AWS CLI. Without them, the script runs them from a container image instead.
    • Windows 10 or 11 with WSL 2 (Windows Subsystem for Linux). An admin must set it up once. The setup steps install Docker inside WSL, so you don’t need Docker Desktop. On a virtual machine, WSL 2 needs nested virtualization.
  • Network access to your Perforce server and to Diversion over HTTPS

Set up the import in the Diversion app

1

Open the Perforce import page

Go to your Dashboard and choose Import from Perforce. If it isn’t there, click New repository at the top right and choose Import from P4. You can also choose Import from Perforce from the footer of the repo selector dropdown at the top left (alongside Create new repository and Import Git repository).
On self-hosted installs, these options open a request form instead, and the Diversion team runs the import for you.
2

Download the import script

Choose the tab for your import host’s operating system, and download its script:
  • Linux / Unix: click Download p4_import_bootstrap.sh.
  • Windows: click Download install_windows_task.ps1. It sets up the import inside WSL and downloads the Linux script there for you. Your browser may warn before it saves the file, because it is a script. Choose Keep.
The scripts are the same for every import, and you can download them from this page at any time.
3

Name the new repository

The repository name is filled in from the depot name; change it if you like. The repository must belong to an organization. If you don’t have one yet, you can create it here.
4

Fill in the import settings

See Import settings below for what each field does.
5

Click 'Create repository and import files'

Diversion creates the repository, an API token, and your import configuration.
6

Download local.env

Click Download local.env. The file contains the API token, your repository ID and the setup steps for Linux, Unix and Windows.
This API token is shown only once. Download local.env before you leave the page. If you leave without it, you can create a new token and file: see Recover a lost local.env.

Import settings

Protect local.env

local.env holds an API token with admin access to your Diversion account. Treat it like a password:
  • Keep it only on the import host, readable only by the user that runs the import (chmod 600 local.env, as in the steps below). On Windows, the setup script copies the file into WSL, makes that copy readable only by root, and deletes the one in your Downloads folder.
  • Don’t commit it to version control, share it in chat or email, or copy it to other machines.

Run the import on the import host

Run these steps as the user that will run the import — a user with access to Docker. Don’t use sudo: it would install the schedule in root’s crontab.
1

Put both files in one directory

Copy p4_import_bootstrap.sh and local.env into the same directory on the import host, for example /opt/dv-p4-import, and cd into it.
2

Make the script executable

3

Fill in your Perforce settings

Open local.env and fill in the Perforce connection at the bottom of the file:
Leave API_DOMAIN, API_TOKEN and REPO_ID as generated.
4

Protect local.env

5

Run the script once to check the setup

A successful first run downloads your import configuration, pulls the Diversion import image and starts it. The output includes a line like Remote env changed -- recreating: ..., and docker ps shows the import container running. The first run can take a few minutes while images download.
6

Schedule the import

This adds a crontab entry that runs the script every 5 minutes from this directory and appends its output to bootstrap.log. Each run restarts the import if it stopped and applies any change to its configuration.

Change the Perforce settings

The setup check does not test the Perforce connection. If the settings are wrong, the import stops, and docker logs shows a Perforce login error.
Edit local.env in the import directory. The next run, within 5 minutes, applies the change.

Follow the import’s progress

Open the new repository in Diversion. Until the import finishes, the repository page shows its progress through three stages: Reading history, Preparing history and Uploading files. Commits, branches and files appear once history is ready. Files open as soon as their contents are uploaded. Large depots take a long time to import. The import host must stay on and connected until it finishes.

Stop or remove the import

The schedule keeps the import running until you remove it.
Keep the schedule if you need continuous import from Perforce, or export back to it, after the initial import. Contact support to enable continuous import or export.
When the import is done and you don’t need it to continue:
  1. Run crontab -e and delete the line containing p4_import_bootstrap.sh.
  2. Delete local.env from the import host.

Troubleshooting

The script writes errors to its output and, once scheduled, to bootstrap.log in the import directory. On Windows, run the commands below inside the distro: put wsl -d Ubuntu-24.04 -u root --cd /root/p4-import -- in front of them, for example wsl -d Ubuntu-24.04 -u root --cd /root/p4-import -- tail -n 50 bootstrap.log.

Troubleshooting on Windows

Send logs to Diversion support

If the import fails or stops and you can’t find the cause, send its logs to Diversion support. Run this in the import directory:
On Windows, run this in PowerShell instead:
The running import is not stopped. Make sure API_TOKEN is set in local.env, because it is used for authentication when uploading. If it is missing, the upload fails; see If the upload fails. When the upload succeeds, the output says Support bundle sent to Diversion, and our support team gets your description. The uploaded file contains:
  • The import logs from the last 3 days. Long logs are shortened: the start, the end and every warning and error are kept.
  • The recent output of the import containers and the end of bootstrap.log.
  • The settings in local.env and in the import configuration. Values of secret settings, such as P4PASSWD and API_TOKEN, are replaced by their length.
  • Basic details of the import host: operating system, free disk space and Docker version.

If the upload fails

A copy of the file stays at dv-bootstrap/p4-support-bundle-<time>.tgz. If the upload fails, the script prints the file’s path; email that file to support@diversion.dev.

Recover a lost local.env

If you left the Import from Perforce page before downloading local.env, don’t start a new import: the repository and its import settings already exist. Recreate the file instead. Until the import starts, the repository page offers a new file:
  1. Open the new repository in Diversion.
  2. Under Lost your local.env file?, click Create a new local.env. This also creates a new API token.
  3. Download the file and continue with Run the import on the import host.
Only an admin of the repository sees this button. Once the import has started, create the file by hand:
1

Create local.env

On the import host, create local.env with this content. On Linux or Unix, put it next to p4_import_bootstrap.sh. On Windows, put it in your Downloads folder.
local.env
2

Fill in REPO_ID

In the Diversion app, open the repo selector dropdown at the top left to see the list of your organization’s repositories. Hover over the row of the new repository and click the Copy repo ID button that appears. Paste the ID as REPO_ID.
3

Fill in API_TOKEN

If you copied the token from the import page, paste it as API_TOKEN.If you didn’t, generate a new one:
  1. Click your avatar (top-right) and choose Integrations from the menu.
  2. Click Generate a new API token, give it a name, and click Generate token. Generate it while signed in as the user who created the repository, so the token has admin access to it.
  3. Copy the token and paste it as API_TOKEN. It’s shown only once.
4

Continue the setup

Follow Run the import on the import host from the start. On Windows, start at Fill in your Perforce settings. If the distro already has a local.env, answer y when the setup script asks whether to replace it.

Request a managed import

If you can’t meet the requirements above, we can run the import for you. Use Request a managed import at the bottom of the Import from Perforce page, or contact us at support@diversion.dev.