Documentation

What is Ark?

Ark is a centralized Version Control System (VCS) designed specifically to handle complex projects that use a large amount of binary assets, such as the ones in video game development.

It comes as an alternative for developers who are dissatisfied with mainstream solutions like Perforce and Git. Ark not only addresses the limitations of these solutions, but also strives to set a new standard of what a modern VCS should be, always prioritizing ease of use and high performance.

Getting Started

Ark has a client <-> server architecture, which means that you need to have a server running independently and then the clients will connect to it.

If you're working with a team, you'll want to setup a server in a dedicated machine that is always running, so that anybody can connect to it at any time. Then each client needs to setup their workspace on their machines and connect to the server.

If you're a solo developer, you'll most likely want to start by creating a workspace with a built-in server so that any time you run Ark it just handles the server for you.

Platforms

Ark is a single executable, which contains server, cli and gui. We currently support 3 platforms:

• Windows x64 (ark.exe)
• Linux x64 (ark-linux)
• MacOS Intel (ark-macos / Ark Vcs.app, runs on Arm via Rosetta)

Concepts

There's a few concepts that you should be familiar with when using Ark.

• Workspace: folder from which a user will work from;
• Project: self contained project (i.e. assets, branches, history), similar to depot in Perforce and repository in Git;
• Branch: parallel version of the project. Each project has at least 1 branch;
• Workspace Changelist: a set of local changes that can get eventually committed to the server;
• Changelist a set of changes that is already tracked by the server (may be committed or not). A changelist belongs to a branch;
• Shelved Changelist: a changelist that is stored in the server, but not yet committed to everybody else;
• Committed Changelist: a changelist that is marked as committed, which means it is now part of the history of the project and anybody getting latest on the branch it belongs to will get these changes;
• Shelving: send a workspace changelist to the server so it can be accessed by others;
• Committing: mark a changelist as part of the history of the project;
• Tag: a way to flag committed changelist in order for better tracking important commits;
• Locking: mechanism to control who can commit a file, in order to prevent data overwriting, specially useful for binary assets that cannot be merged;
• Branching: create a parallel version of the current branch, which has the root as a committed changelist;
• Merging: bring changes from a branch to another;
• Reverting: discard local changes in your workspace;
• Conflict: file has local and remote changes and a decision needs to be made about what version to keep;

Server

To start a server, you'll need to use the cli server command.

It requires the path to be explicitly passed if the server is being initialized in order to prevent errors by just running the server in an empty folder.

If the path is not passed, it will only run the server if it is already initialized in the current directory.

Valid log levels: debug, info, warning and error. Keep in mind that this only affects what is printed to console, the logs always use debug.

When a server is created, it will by default generate a RSA key pair and certificate for SSL encryption with the clients, but keep in mind that you can always manually create your own and place them inside your server folder.

Client / Workspace

Each user that wants to connect needs to run a client. A client runs from a local folder called a workspace.

A workspace will connect to a server and map to a specific branch of a project.

You can change switch your workspace to another branch / project whenever you want, however it is advised to only follow this approach if you're low on available disk space or if the differences between them are minimal, since you'll have to override the files in the workspace.

Convert Server <-> Built-In Server

To convert a server to a built-in server all you need to do is:

• Shutdown both your server and your GUI client
• Move the server folder inside your workspace folder and rename it to .ark_server/
• Run your GUI client

The GUI client will now automatically start / stop the server for you.

Conversely, the steps to turn your built-in server into a server simply:

• Shutdown your GUI client
• Move your .ark_server/ folder to wherever you want it (renaming it is advised, but not necessary)
• Run the server
• Run your GUI client

Changelist

A changelist is the base unit of work that a developer can create, like the name implies it is a list of changes (e.g. file A got added, file B got modified). It has 3 possible states:

• Workspace Changelist: exists only in the workspace;
• Shelved Changelist: a workspace changelist that has been uploaded to the server, but not yet committed;
• Committed Changelist: a shelved changelist that has been marked as being committed;

When you shelve your changelist, it gets assigned an id, and the data is copied to the server.

Once you decide to commit your shelf, the server simply changes the state of the changelist to committed, given that all the data is already on the server.

One of the benefits of having a centralized VCS is that you have a unique provider of ids for your changelists. Ark's changelist ids are incremental starting from 1, so the higher the id the later a changelist was committed.

This allows you to reason in a much more intuitive way about the state of your project, because if you're currently on changelist 1074 you know that you'll have any change committed in a changelist with a lower id.

Shelved Changelist

Quite often you end up in a situation where you need to collaborate with somebody, or you may simply want to store a snapshot of your current work in the server, while not disrupting anybody else's project. This is where shelves come in.

You may be familiar with them from Perforce, they are basically a way to store a changelist in the server without actually committing it.

Once a shelf is created, you can revert your local changes because you can always get them back from the shelf.

A shelf will now have a unique changelist id, and with this id other users can also unshelve your changes, allowing them to get changes without affecting anybody else.

However, Ark takes shelves to a new level. In Perforce, shelves are one way street, meaning that if user A shelves something, user B can only unshelve it, they cannot update or even commit this shelf.

Ark's shelves are two-way, it allows for any user to contribute to this shelf, and when there's changes users will get notified.

This makes them de-facto super lightweight branches, where people can collaborate on small tasks without going through all the hassle or creating, switching and merging branches.

Committed Changelist

Commit is the act of making a changelist officially part of the history of the branch it was committed to. This means that anybody on that branch getting latest will get those changes copied locally.

History

When a changelist is committed it becomes now part of the history of the branch.

The history is basically a stack of committed changelists, with growing id.

The changelist at the top is called latest or head.

In Ark you can only be in one changelist at the time, your current changelist. This is by design, to prevent issues like you can have in other VCS like Perforce.

The reason for it is that if somebody tells you that they are on changelist 602 and they don't have any local changes - which Ark tracks automatically for you -, then you're guaranteed that if you switch to that same changelist you'll have the same content that the other user has.

This sounds like a basic thing, but if you ever worked with Perforce you most likely encountered a situation where somebody either has untracked local changes or has part of their code tree at one changelist and part at another, making it quite a frustrating endeavour to figure out what's wrong.

Tags

Tags are a way to mark committed changelists to be able to track more easily important changelists. For example, if you built a demo for an event you may tag it with 'demo_2025' tag and more easily go back to it.

Since we want to allow some commands to work on both changelist ids and tags, there's a few restrictions with what is considered a valid tag name:

• Cannot be reserved dynamic changelist id names (i.e. head, latest, current)
• Cannot be a changelist id (e.g. 123, 3_344, 8.555)
• Cannot start with * (since it is used for pattern matching with changelist ids)

Ignore Files

All projects have files that we don't want to commit, and Ark follows a similar path to Perforce and Git.

There's an .ark_ignore file in which you define rules to ignore or not files / folders.

By default and for convenience, when connecting to an empty project Ark will add a default .ark_ignore with common rules, but you can always go in and edit these rules (specially removing rules that are not needed, given that the less rules the faster it will be).

Given Ark's approach towards performance, we keep the ignore rule system simple by not supporting regex. Here's what you need to know about it:

• It can only have 1 entry per line;
• It is case insensitive;
• # starts a comment;
• * is used to create complex patterns;
• ! allows to exclude patterns;

Here are some examples of all of this put together:

Ignore Inspector

Whenever projects get too big, ignores can get a bit out of hand, and some times it's quite annoying to find out why something is or is not ignored. To help with this Ark comes with the panel Views -> Ignore Inspector.

When you click Gather Ignore Data it will reconcile the whole project and collect information about the ignores. You can then hover each entry to find out why it was added or removed from the ignores.

Smart File Locking

When working with multiple users on binary files, it's very important to be able to control who has currently ownership of the files in order to prevent losing work. This concept is generally know as file locking.

Ark's approach tries to improve the standard provided by other VCS.

Instead of locks being exclusive to one user, Ark uses a lock queue approach, in which the user at the head of the queue has ownership but others can queue behind them to get the lock as soon as it's released.

It also allows you to request / give the lock ownership to another user in the queue.

To configure which files should lock by default, you edit the .ark_lock file. In it you define rules - following the same pattern rules of the .ark_ignore file - of files that you want to be automatically locked when edited.

You can also explicitly lock a file, even if it is not matching any of the .ark_lock file rules.

Users

Like mentioned above, the first user connecting to the server will become an admin. Afterwards, all other users will need to be manually added.

A user can have one of the following roles:

• Normal: use version control;
• Manager: use version control, manage normal/manager users;
• Admin: use version cotnrol, manage all users, manage projects;

Keep in mind that even though we login using email, the actual user is identified by a unique user id (starting from 1). This means that a user is free to change their email / username and it will display the updated version even on older changelists.

That being said, the email and username need to be unique between users.

Projects

A project can be seen as a depot in Perforce or repository in Git. Projects are self contained, they have their our assets, branches, changelists, and history. Usually what you'll want to do is to setup a project for each individual game/application/website you want to develop.

When creating a new server, it will automatically create a project for you with a random name from [Alpha, Beta, Gamma, Delta, Epsilon, Kappa, Lambda, Sigma, Omega] and a root branch called dev.

Like everything else, projects are identified by a unique id (starting from 1), so you can change its name freely. This implies that project names cannot be numbers.

Branches

If you're familiar with Git then you'll be familiar with how branches work in Ark.

Branches allow you to split your current code base into multiple versions, like for example to stabilize a build for a demo or release.

We highly recommend you to follow a trunk-based approach to development, which means that people work as much as possible on the same branch (traditionally called trunk, hence the name trunk-based development) and only jump to other branches when necessary.

With this approach, branches are usually done for stabilizing or for very disruptive development (e.g. you want to replace the physics engine).

Working in this way has a lot of benefits:

• Everybody has the same code / assets;
• All code / assets are getting QA;
• Disruptions to your code / assets from others is detected very fast, and vice-versa;
• Features can be turned on / off simply by changing a flag;

All of these combine to create a much more stable project. If a lot of branches are used (and the longer they live the worse), then things tend to get much more unstable when merged. Don't just trust us, Jason Gregory from Naughty Dog at HandMadeCon 2016 goes over this subject.

That being said, Ark still allows a workflow that is branch-driven, and we try to make our branching and merging process as simple and fast as possible.

Conflicts

Conflicts can happen in 2 situations: when getting latest and when merging changes.

When getting latest is the most common occurrence, it's when the files you're working on had changes committed in the meantime.

Likewise with merging branches, if the assets have been changed in both branches they will be flagged as being in conflict and you'll have to resolve them.

There's 3 options to resolve a conflict:

• Keep Ours: leaves your current workspace file intact;
• Get Theirs: discards your current workspace file and copies the remote version;
• Manually: launches the defined merge application for a manual file merge;

No Commit / #nocommit

When working on a file, you'll quite often find yourself in a situation where you have local changes that you don't want to commit accidentally. To help with this situation there is a feature called #nocommit.

There are two ways to use #nocommit. The first - and more convenient if you're programmming - is to simply add #nocommit keyword inside your text files. When parsing text files for changes, Ark will look for this keyword and flag your file. To remove this state, you simply remove this keyword from your file.

The second way is to explicitly mark the file by right-clicking on it and selecting Set No Commit, which is specifically useful for binary assets.

When using the explicit approach, you'll then have to use right-click Clear No Commit option to remove it.

Keep in mind that a text file can have both in file and explicit #nocommit, and you can see that state in the file's tooltip.

In case you have a lot of files that you want to prevent committing - perhaps part of a bigger feature -, you can also mark the workspace changelist with #nocommit by right-clicking on it and selecting Set No Commit. In the case of workspace changelists, it will always just append #nocommit to its comment, which means that you can also just write it yourself in the comment. To remove it, you can either manually remove it from the comment or right-click and select Clear No Commit.

Crash Dumps

When Ark crashes, it will generate a crashdump that the user can then submit a bug report with. They are saved along side that session's log in:

• <server folder>/crashdumps/ for servers;
• C:/Users/{user}/AppData/Local/Ark-Vcs/crashdumps/ for clients in Windows;
• ~/Ark-Vcs/ for clients in Linux and MacOS;

Game Engine Plugins

Ark is a standalone application, but there are some cases where having a plugin is helpful, because it allows for a tighter integration, like being able to see in the game editor that an asset is outdated or locked by somebody else.

It is also necessary when using editors that are not very VCS friendly, like it is the case of Unreal Engine (UE). Unfortunately, when UE loads an asset it keeps a hold of that asset, which makes it impossible for Ark to then make changes to it. By having a plugin, you can have a communication channel between Ark and the game editor to address these issues.

Unreal Engine Plugin

Install

To install the plugin simply place the ArkSourceControl folder either in the Engine (e.g. <path_to_engine>/Plugins/Developer/) or in the Game (e.g. <path_to_game>/Plugins/).

After relaunching your UE Editor, go to Edit->Plugins and enable Ark Source Control plugin.

Setup Unreal Editor

To start using Ark as you version control system in Unreal Editor go to the lower right and select Revision Control->Connect to Revision Control...:

Then choose the Ark Vcs as the provider, and configure all the settings:

The Ark workspace will default to your project's root, however you may want to change it if for example you are using Unreal Engine Source.

After you click Accept Settings and Unreal Editor will launch Ark for you. If you close Ark, then you'll be disconnected from source control. To reconnect just open this window and click Accept Settings again. When you're connected to version control it will display a green checkmark on Revision Control button:

Afterwards you simply use version control like you would inside Unreal Editor.

Lock Requests

If you're used to Ark, you'll know about how our locks work, and some mechanisms that it has like being able to request lock ownership from another user.

These mechanisms will also work from inside Unreal Editor. If you try to lock (i.e. checkout in Unreal Editor nomenclature) a file that is already locked by somebody else, you'll be presented with a notification asking if you'd like to request the lock ownership:

If you receive a request, you'll also get a notification asking if you want to give the lock away:

You'll also receive notifications with the response to a lock ownership request, and when you eventually receive it.

File Status Icons

One of the benefits of using the plugin is that you'll be able to get visual feedback on your assets:

Here's a listing of all the icons Ark uses:

• Local changes and is new
• Local changes with lock
• Local changes with lock by another user
• Local changes with asset outdated
• Local changes with conflict which needs to be resolved
• No local changes with asset outdated
• No local changes with lock ownership
• No local changes with lock by another user

You don't need to memorise these, when you see an icon on an asset just hover it and you'll get all the information on the tooltip.