Latest version: 0.9.3
Warning: as Ark is currently in fast evolution there's a chance that some of the documentation is outdated, so please keep in mind that information may not match 1 for 1 the current state. Entries will be flagged with the version they were added or updated to help mitigate this.
As Ark stabilizes towards a release there will be a pass to make sure everything is up to date.
Because Ark is still in heavy development, you're strongly encouraged to backup your project often, specially when dealing with branching / merging. If you want to use it in a production environment we encourage you to use in parallel with your current VCS before you make a full switch.
Since 0.8.0, Ark comes with 3 executables: ark.exe for Windows, ark-linux for Linux and ark-macos for MacOS.
The easiest way to get started is by running a Client with a built-in Server. This will create a .ark_server/ folder inside your Workspace from where your server will run automatically when you run the Client.
You can also just run a Server and Client separately.
CLI support is in it's infancy, but expect it to improve with each new release. To get information about supported commands you can do:
ark.exe help
Note #1: You may need to change ark-linux to have executable permissions, you can do that by running chmod 755 ark-linux.
Note #2: The MacOS version also has an Ark Vcs.app, which is basically ark-macos wrapped in an app bundle.
Since version 0.2.0 you can choose to create a Workspace with built-in server. This means that on the same folder of your Workspace, a .ark_server/ folder will be created from where the server runs.
The application will run automatically built-in servers, making it easier for you to try out Ark or for you to just work on a project by yourself but still have the benefits of using version control.
Ark is a centralized VCS, which means that you need to have a server running somewhere. To run a server, follow these steps:
When you want to stop the server just do Ctrl+C in the terminal.
After you have a server running, try launching the ark executable by double clicking it. It should look something like this:
A workspace is where you'll be working locally. Click the Create New Workspace button (or File->Create New Workspace) and you should see something like this:
You can select a folder that has content, but it's maybe best for the first time to try it with an empty folder so that you can try things step by step. A .ark/ folder will be created inside, where Ark writes everything it needs.
In the case of creating a built-in Server, there will also be a .ark_server/ folder where everything related to the Server will be saved.
Now that you have a Workspace, if the Server is running (or is a Built-in Server) you should have it automatically connect to it.
In order to the flow as simple as possible, there's things that happen automatically when you connect to a new Server:
In the cases where you don't have the Server running, you may have a Reconnecting in Xs or a Connect To Server button on the lower right.
I highly recommend you check the log panel as all this information will be displayed there.
At this point, you're ready to start working!
Like mentioned above, the first user authenticated will be automatically added as an Admin. Afterwards, all other users will need to be manually added.
To manage users go to Workspace->Users.
There's currently 3 levels of users:
If you need to reset a user's password you need to right-click on them and choose Edit.... There you'll see an option to check Reset Password, and if you click Edit the password will be reset. The next time the user authenticates it will assign whatever password was used.
Note: Passwords are never sent to the Server, they are hashed and only the hashes get sent. This means that even if somebody has phisical access to the Server they cannot find out what your password is.
To manage projects go to Workspace->Projects.
You can add / edit Projects and edit their Branch, however currently Branches are limited to just one per Project. Of course Branches are quite important for a VCS, so expect big changes here.
Once you're all setup, you can just start adding / changing / deleting files.
I'd recommend you giving it a go and add files via Explorer while keeping an eye on Ark to see just how fast it reacts. In case you're not aware, Ark handles adding files 44x faster than Perforce and Git.
Once you have some changes you want to commit, right click on the Workspace Changelist and choose Commit....
This will bring up the Commit Window where you can add a comment. When you click Commit it will push your changes to the Server.
To ignore files you have 2 options: right-click on the file / folder you want to ignore, or create / open a .ark_ignore file on the root of your Workspace.
Like everything in Ark, performance also applies to the ignore system. So we try to keep this system simple, but also flexible.
In 0.6.5 it was revamped to allow for more complex patterns. Here's what you need to know about it:
Here are some examples of all of this put together:
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 an Ignore Inspector (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.
Built-in Server is done in a way that it is just a normal Server that runs from your Workspace.
This means that if you have an existing server folder, you can just copy it to your workspace and rename it to .ark_server/.
It also means that you can start working with Ark locally in a convenient way, but if you decide to start working with other people and want to setup the Ark Server on another machine, you only need to move that folder to another machine, name it whatever you want, and then run it with ark.exe server -path <path> cli command.
From 0.3.0 you can access the Built-in Server logs by right clicking on the logs panel or by selecting Built-in Server / Show Console in the preferences to have a console with the log always visible.
File locking is an essential feature for when you're working with binary files since, unlike text files, you cannot merge them.
Ark's approach to locking is to try to get out of your way but still ensure that there's no loss of work.
The first person to lock a file gets the lock ownership, which means that only they can commit this file. However, a file being locked doesn't mean that you can't try to lock it. In fact, when you try to lock a file that is already locked by somebody else, you'll get added to a queue of lock requesters.
Whenever the lock owner unlocks the file, the first person in the queue will get the lock ownership.
In order to make this process simple, you can define a .ark_locks file. This file follows the same format of the .ark_ignore, and allows you to define rules for files to automatically request the lock if changed. To create a default .ark_locks file with a set of rules for a lot of common files go to Workspace->Create Default .ark_locks.
This means that locking only requires Ark running; no need to have special plugins integrated into your text editors like with other VCS.
That being said, there may be some situations when you want to manually lock a file before it is even changed. To explicitly lock a file, you right-click on it and select Lock.
Even if a locked file doesn't have any changes yet, it will be added to your Workspace Changes.
Sometimes you may need the file urgently, and to streamline this process Ark has a mechanism to request lock ownership. To use it, right-click on a locked file you're queuing for and select Request Lock Ownership.
If the lock owner is online, they'll get a notification requesting for approval. After they make a decision, the requester will get a notification informing him if it was successful or not.
To unlock a file explicitly, you can right-click on it and choose Unlock.
When committing, you also are given a choice to keep the locks. If you do, after committing you'll still have lock ownership. If not, they'll be unlocked.
Note that just because a file may get a lock automatically from the .ark_locks rules, you can unlock it at any time if you don't need it. This is very useful for situations where you had to do some local changes that you don't plan to commit, but don't want to get in the way of people that actually need that file.
If you're familiar with Perforce, you've most likely come across the concept of Shelves. Shelves are a way to store changes in the server without actually committing them to everybody. Shelving is simply the act of creating / updating these shelves on the server.
This doesn't mean that they are a replacement for branches. Those still have their place, but when working with a trunk-based development approach their use is slightly different, usually more focused on stabilization or disruptive changes.
When you have a set of changes, instead of committing them you can right-click and choose Shelve....
This will open a new window in which you can update the comment and select which files you want to shelve.
When you shelve, it will assign a Changelist Id that will now be displayed on the header of the change set. You can then send this id to anybody that would like to access that shelf.
To open a window with that shelf you go to Workspace->Go To... (shortcut Ctrl+G) and input the Changelist Id. From this window you'll be able to Unshelve and get that shelf to your workspace.
Ark's goal is not to be a copy of other VCSs, it is meant to take the current state of the art and improving on it. So contrary to other implementations, Ark's shelves bring multiple features.
When somebody else gets your shelf, they can also update or even commit it. This is one of the biggest usages for shelves, a fast and simple way to colaborate with others on small problems.
Each time you update a shelf, you create a new Revision. This means that you can get a history of that shelf and go back / compare with previous versions. This will also be tied to other features, but more about that in the future.
They are meant to be done in a way that doesn't disrupt your workflow, and actually helps you have a better understanding of what's going on. So for example, if you have an outdated version of a shelf it's title will show up with a different color. To get the latest version of a shelf you right-click and choose Shelf->Get Latest.
On top of these visual cues, whenever you hover any of the files you'll get that information on it's tooltip.
Branches are a way to create separate working copies of your project without them affecting each other.
By default each project starts with a default branch (i.e. trunk branch, by default called 'dev' in Ark). A new branch can be created from any changelist.
At any point, you may choose to merge changes from one branch to another.
Like with everything else in Ark, we try to simplify what branching / merging looks like. We don't want this to be a daunting task, it should be simple enough that anybody can actually use them.
That's entirely up to you, there's no situation where you're forced to create branches.
Ark's approach is trunk-based development, which means that you develop mostly on the trunk branch and then you branch out for stabilization. For example, let's say you have a demo coming up, you'd create a branch to stabilize the project, but development would continue in the trunk. Then any stabilization done in the demo branch would be merged into the trunk.
Think of it as the further it is from trunk, the more stable it should be. So you normally don't merge changes from trunk to these branches, you always merge from more stable to less stable.
Of course there's always exceptions, let's say you want to do a new feature that completely disrupts your project. It may be worth to split that into a new branch, and then keep merging trunk into it until you're ready to merge it back to the trunk. That being said, I'd recommend you minimize this approach and use for example feature flags.
Although Ark doesn't prevent you from doing full on branch-driven development (i.e. create branches for any work), we highly recommend against it. To find out more on why, check this talk from Naughty Dog's Jason Gregory at HandMadeCon 2016.
Branches take a lot of inspiration from Git. Even thought Ark isn't focused on branch-driven development, creating branches should be intuitive and not as scary as with Perforce.
To create a new branch, you right click from any changelist and choose the Branch... option:
This will open a new window. To create a branch, you have to assign it a unique name.
A branch name can be changed at any time, it's just to make it more convenient with identifying the branches.
You then have to options: to just create the branch, or to create it and immediately switch to it.
When a branch is created, in the history panel you'll see a new triangle node on that changelist entry. A triangle represents a start of a new branch. A circle node represents to which branch it belongs.
Each branch is represented by a different color, which gets automatically assigned. You can however still customize the color of each branch via the Workspace->Projects.
To customize a branch, click on it and choose Edit....
Note that any changes made to the branches are global, so if you change the name or color it propagates to every user.
This is an area that will be improved later on, however at the moment there's 2 places informing you. The first is in the window frame, where you have which server, branch, and changelist you're currently on:
The second is in the history panel, on your current changelist the node that has the white outline is the current branch you're on.
Merging is the way to bring changes from one branch to another while keeping track of what has been merged.
First thing you need to do is be on the branch and changelist you want to merge to. Usually that should be the latest changelist of a branch, but nothing prevents you from doing it from any other changelist.
Then you right click on the branch you want to merge, and choose one of the 2 merge options:
Ark will figure out which changes need to be merged and will populate a changelist. Any file that has been marked as being merged, will have a merge icon next to it.
Once you commit this changelist, you'll now see a connection between those branches in the history panel, and the changelist will show which branches it merged from.
If a branch is idenfified as not yet merged leading up to our current changelist, it's changelist id and comment will be faded out. The purpose of this is to give you an easy overview of what changelists have been merged or not.
Note that if the file for the current changelist and the file merged don't have the same base root, it will lead to conflicts which you then will be prompted to decide (i.e. Choose Ours, Theirs or Merge Manually).
In order to help fixing builds in case of crashes, Ark now generates minidumps in Windows and fulldumps in Linux when it crashes. These will be saved along side their log in:
In case you ever have the app crashing, please get in touch via bugs@ark-vcs.com. In case of Linux fulldumps, the file may be too large for email, but we'll find some solution.
Note: Linux fulldumps depend on gcore, an executable part of gdb (GNU Debugger).
Alongside Ark 0.9.0, Unreal Engine Plugin 0.1 has been released. Although you technically don't need a plugin to use Ark with Unreal Engine, it isn't a smooth experience because of the way Unreal Editor handles certain things (e.g. holding on to files of assets it has loaded in memory, preventing you from reverting / updating files without closing Unreal Editor).
To improve quality of life, we're introducing the Ark Plugin and it's first implementation into Unreal Editor, which brings the following features:
Unreal Plugin 0.1 has the following limitations, which will be improved in future versions:
Note: It is highly recommended that you do the first commit via Ark directly and only afterwards you build and connect to Ark via Unreal Editor, specially if your project will also contain Unreal Engine source code, in order to be able to prevent committing any generated files that shouldn't be.
To install the plugin you simply have to 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 project, go to Edit->Plugins and enable Ark Source Control plugin.
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:
Note: The plugin will only be working if Ark is connected to the server.
Afterwards you simply use version control like you would inside Unreal Editor.
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.
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 userYou 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 toolip.
