Import Project

If you are starting a new WVS project but already have existing data, there are several ways that you can proceed.

One way is to just start a new blank project and then copy your existing files into it. However, if your project is large, or already in another version control system, using the WVS import functionality is the preferred approach.

WVS provides several ways to import your data depending on your specific situation. Below are several different scenarios. Identify the one closest to your situation and follow the instructions for that scenario.

Preparation and verification (Important!)

Regardless of the approach you use to import existing data, the procedure consists of three important steps. Do not skip any of them!

  1. Prepare your data: Before you actually do the import, you need to make sure that you aren’t importing any temporary data, and that your data is organized the way you want it.

  2. Do the WVS import: Following the instructions from one of the import scenarios below.

  3. Validate the import: If you are importing an interactive project that uses an editor like Unreal or Unity, there are several validation steps you want to perform to make sure your project is correctly configured before you start doing any work with it.

That last step is very important if you want to ensure that developers on your project have a smooth workflow. It is very common for editors to generate files that you do not want to commit to source control. You must confirm that simply running the editor does not cause side effects to tracked files in your repository or collaborators will find themselves resolving conflicts more than necessary.

Import Scenarios

The currently supported import scenarios for creating a new WVS project from existing data are:

If your data is in another version control system such as Subversion, Plastic, or Perforce, you can checkout a snapshot of the current data into a directory on disk and use the “From a local directory” scenario.

Git provides a way to convert a Perforce repository, with all its history, into a Git repository. If you wish, you can follow this procedure, which will result in a local Git repository for your project and then you can use the “From a local Git repository” scenario to import it into WVS.

From a local directory

Using the WVS command line

  1. First, follow these suggestion to make sure your data is prepared for import

  2. Open a Windows command prompt window (terminal window on Mac)

  3. Change the current directory into the directory that you are importing 

cd \projects\ShooterGame
  1. Run the wvs import command, providing the desired name of the project. The name does not need to be the same as the directory being imported. 
wvs project import --name "name of new project"
  1. Follow these suggestions to validate that your data is imported appropriately for your development environment.

From a local Git repository

If you are importing an interactive project, we strongly recommend careful consideration as to whether importing “From a local Git repository” is the right approach.

Importing interactive projects into a repository is tricky business. Unlike most software projects, interactive project have lots of binary files and those must be treated differently in a version control system. Not only must one be sure that they are recognized as binary files, but they must also be set up to have locking enabled so that multiple people do not try editing them at the same time. In Git, these configuration primarily relate to correct configuration of LFS and the .gitattributes file

When creating new projects or importing existing data, WVS does its best to make sure that the new project is correctly configured for all common tools and engines used in interactive development.

Importing an existing local Git repo, however, entails importing something that has already been configured. If the LFS configuration in your existing Git project is not present, incomplete, or incorrect, WVS will import it as-is, and it will be difficult to correct later.

The WVS team is currently working on pre-import analysis of git projects so that we can be sure that the git project is well configured prior to import. Until that feature is released, we recommend that users fetch the current state of their git repo into a folder and follow the “From a local directory” scenario.

If you feel that your project is well configured for LFS and would like to import an existing repository with its history, please contact support and we will give you the beta version of the procedure.

From a Github repository

Many of the same caveats as are mentioned in the “From a local Git repository” scenario apply to projects imported from Github. However, because Github places severed limitations on the size of non-LFS data, if you are importing an interactive project from Github, the odds of the project having been correctly configured for LFS are much better than for a local project.

The procedure for importing from Github is quite simple:

  1. Select “New Project” on wvs.io.

  2. Select “Import from Github”

  3. Follow the instructions which require you to enter Github authentication and select a project

Preparing your data for import

It is always a good idea to clean up your director tree prior to importing it. While it is easy to correct mistakes after the fact, the history of the repository will still have the initially imported data and thus you are unnecessarily bloating your repository if you check in unnecessary files on the initial import.

  • Remove temporary files created by various tools. (e.g. *.bak, *.tmp, etc.)
  • Remove build and intermediate directories (e.g. Intermediate, Build, obj, etc.)
  • Make sure there are no “.git” directories anywhere in the tree. These are fatal to the import process.
  • Make sure there are no .gitignore or .gitattribute files in the tree, unless you understand the implications.
  • Make sure there are no symbolic links in the tree

Validating the import

Once an import has been completed, it is very important that you verify that the repository is correctly configured for your interactive project. This process consists of the following steps.

  1. Make a fresh clone of the newly imported project to another directory. Do not use the directory you just imported from to test with. It is critical that you clone a fresh copy because otherwise you will not know whether you actually imported all the necessary files, and if their configuration is correct so that someone who does a fresh clone of the project does not have any problems.

  2. Read the project into your engine editor and load the project from the newly cloned location. Do not try to make changes, but make sure that it reads correctly and you can run it the same way you could before your import. If you have a problem reading in the project, then most likely a critical file was not imported in the initial import. The two most common reasons for this are:

    • The file was missing in the directory you imported. You will need to add the missing files to the project.

    • The file was intentionally ignored during the import process by the .gitignore file that was used. If you try adding the missing file to the project and the client is ignoring it, you know that this is the issue and you will need to modify your .gitignore file before adding the file.

  3. Quit out of the engine editor without making changes.

  4. Using your client of choice (either standard git client, or one of the WVS clients), make sure that there aren’t any pending changes. This is the critical step! All you did to get to this step was clone the project and open the editor without making changes. If you see pending changes, that means that developers on the project are touching files (and will be checking them in) every single time they open the engine tools, even if they are not making explicit changes. This results in lots of conflicts and users stepping on each others toes. The root cause of this behavior is almost always that you imported temporary/work files and or intermediate/build/work directories used by the engine. You need to identify the problem files and/or directories, delete them from the repository, and modify your .gitignore file to ignore them in the future. Do not allow users to work on the project until you have resolved any issues you may find in this step!

If you are having issues identifying why a fresh clone of your project is not working as expected it is advised to “diff” the contents with the original folder you imported. There are several diffing tools on the market such as Beyond Compare that can help you track down any discrepancies in the data.