Wiki

Upload an existing project

Put an Unreal project already on your disk under uVersion: initialise the folder in place, check the exclusions, then a checkin from the Pending tab. With the pitfalls of the first upload.

You have an Unreal project on your disk and you want to put it under uVersion. This page covers that exact case: your files do not move, the folder is linked to the server in place, then uploaded.

If, on the contrary, you are starting from an empty repository already created on the server, what you need is a clone, not this page.

Before you begin

Close the Unreal editor At the end of an upload, the uploaded files go back to read-only on the disk. But the uVersion plugin, when the editor opens, automatically reserves every asset left writable: if the editor is open during the operation, it immediately takes locks again on what you have just uploaded. Since locks never expire on their own, you would keep them without knowing it.

Also check that the folder you are about to declare is really the intended root of the repository. The .uproject file must sit at most three levels below that root, otherwise the client will not recognise the project as an Unreal project and the Unreal panel will stay invisible.

Initialise the folder

1. Open the Open Repository window

In the sidebar, open Workspace, then click Open Repository (or the "+" of the tab bar). The window that opens is meant first for cloning an existing repository: that is not what you want here. Scroll all the way down, below the list of repositories and below Open Local Repository..., and click New Repository from a Project Folder...

You do not see this button? It only appears for the admin role, because it creates a repository on the server. See Create a repository.

The bottom of the Open Repository window: the Download files after clone checkbox, the Open Local Repository button, and below it the New Repository from a Project Folder button.

2. Choose the project root

A folder picker opens, titled Select your project folder to create a new repository. Choose the root of your project, the one that contains the .uproject or the folder that contains it. Nothing is copied or moved: this folder will stay where it is.

3. Name the repository and create

The form appears in the window itself, in the place of the button you have just clicked, not in a new dialog box. It recalls the chosen path and offers a Repository name field pre-filled with the folder name. Adjust it if needed, then click Create & Open. The button stays inactive as long as the name is empty, and this name must be unique across the whole server.

The in-place creation form, in the Open Repository window: the path of the chosen folder on one line, the Repository name field pre-filled with the folder name, the Create and Open and Cancel buttons.

The client then does four things, and nothing else:

it creates the repository on the server;
it writes a .uversion/ folder in your project, which records the repository, the server address and the account that owns the workspace;
it writes a .uversionignore file, only if one does not already exist;
it downloads nothing and touches none of your files.

This folder becomes yours The account that initialises the folder becomes its owner, and it is under this identity that the command line will then act in this folder. A colleague must not copy your folder: they must clone the repository on their side, otherwise they will get the message This workspace belongs to ....

Check the exclusions

This is the right moment, and it is far simpler now than later. Open the .uversionignore file at the root: it lists what will never be uploaded. The default template already sets aside what an Unreal project regenerates on its own, notably Binaries/, Build/, DerivedDataCache/, Intermediate/, Saved/ and Packages/, as well as the project files of the development environments.

Two rules cannot be changed, and it is better to know them:

Plugins/uVersion is always excluded. The Unreal plugin is never versioned: each machine installs the version that matches ITS engine, through the desktop client. Seeing it absent from the repository is normal.
A path containing a folder named exactly ThirdParty is never excluded, whatever rule you write. Your third-party libraries therefore always go up.

Since Packages/ is excluded, a packaged build will never go into the repository: it is distributed through the build publishing feature, not through versioning.

Upload

4. Observe the state in the Files tab

Your whole project appears there with the untracked status: present on your side, not yet on the server. That is the normal state of a folder that has just been initialised. The counter badge above the tree sums up the same thing (N local only), the Rev column shows v0 everywhere, and the Pending tab already carries a badge with the same number: the client spotted your files on its own, there is nothing to "add" by hand.

The Files tab right after initialisation: the N local only badge above the tree, the untracked status on each row, the Rev column at v0, and the badge of the same number on the Pending tab.

5. Open the Pending tab

All your files are already there, marked add, filed in the Default changelist. The left column shows the tree of what will go up, the right panel the flat list with a Diff and a Remove per row. Only remove here what you never want to version: the right answer to "this folder has nothing to do here" is a rule in .uversionignore, not a Remove row by row.

The Pending tab at the first upload: the file tree on the left, the Default changelist on the right with each file marked add, the Diff and Remove buttons per row, the Describe your changes area and the Checkin all button.

6. Describe, then Checkin all

Write a message in Describe your changes...: it is mandatory, the Checkin all button stays inactive as long as the area is empty. "First upload of the project" works perfectly well. Then click Checkin all (N).

The Default changelist panel: the Describe your changes area filled with a first-upload message, the Checkin all button active with the number of files.

The upload reserves for you The checkin itself places the locks of the files it uploads, then releases them once the revision is validated. On a first upload this has no consequence, you are alone on those files. On an already-shared repository, a file reserved by someone else makes the upload fail: see the pitfalls further down.

The upload then runs on its own, in several phases displayed in the header bar: chunking, checking what the server already holds, transfer, then validation. You can switch tabs in the meantime, the progress follows. An interrupted transfer resumes where it left off rather than starting all over. At the end, the uploaded files go to read-only: that is the sign that they are on the server and that they will have to be reserved to be modified.

Pitfalls of the first upload

I am looking for the upload button in Files

It is not there. The Files tab shows the state and serves for one-off actions; the upload is done from the Pending tab, where every untracked or modified file appears on its own. If Pending shows a badge, then there is something to upload.

"Failed to acquire locks for N file(s)"

One or more files are already reserved by someone else, and the whole upload is cancelled, not only the files concerned. Look at the pending reservations tab to find out who holds them, and ask them to release them.

A file I selected went up as a deletion

A path that is uploaded but absent from the disk at the moment of the transfer is interpreted as a deletion. This happens if you move or rename files between the selection and the upload. Avoid working in the folder during the operation.

"This folder is already a uVersion repository"

The folder already contains a .uversion/. Use Open Local Repository... instead of recreating it.

The folder is refused

The client deliberately refuses certain locations: the root of a disk, a system folder, an automatic-startup folder, or a relative path. Choose an ordinary working folder.