A step-by-step guide to versioning a Godot game project with Diversion

Whether you’re a long-time open-source game dev or an enthusiastic Godot newcomer, you probably know that getting used to a sound and robust workflow is an essential skill for any kind of software developer.

And, in particular, having a way of keeping track of your project’s progress is a really cool and often necessary thing to set up early on. Which is why, over the years, the game dev community has become more and more interested in version control for game projects.

In fact, in Godot, there are some built-in tools using one of the go-to VCS solutions, Git…

But, as we’ve discussed in several articles before, some of those “old timers” in the VCS worlds aren’t really the best fit for games, because those are complex multimedia projects. And so, as time went by, various alternative projects started to grow to offer new and more suited version control tools to game devs.

Among which: Diversion, a cloud-native VCS that is meant to enable game creators to work quickly, with nice real-time collaborative dev, and an easy-to-use interface.

So, in this tutorial, we’ll explore the basics of using Diversion to version a Godot project, from setting up an account to actually committing updated work, tracking your progress in the online web app, and even doing more advanced tasks like creating branches.

Exploring the Diversion version control tool

A quick note on Diversion’s pricing system

Like most of the cloud-based versioning tools, Diversion’s pricing works with tiers, and you can keep with the free one until you’ve reached the thresholds… which here, are actually pretty sweet!

Indeed, as shown on the pricing page, with a completely Free tier account, you can have 10 repositories, 100GB of storage and 10 collaborators - and you can use virtually all features of the tool:

After that, if you need to scale up, you can switch to the Team or the Enterprise tier, depending on your needs.

Note: Also, it’s important to remember that Diversion is still in beta. So, it’s already quite promising - and there’s even more coming! In particular, integrations with CI/CD solutions or Git are on their way, to make it even easier to integrate Diversion in your usual workflow.

Creating your account

Alright so - let’s say for now you want to explore the tool, and you’re fine with the (loose) limitations of the Free tier. Then, first things first, to get started using Diversion, you’ll need to create a new account :)

It’s actually very easy! All you need to do is go to Diversion’s website and, in the top-right corner, click on the Login button:

This will bring you to the login form, where you can also sign up for a new account by using the Sign up call-to-action at the bottom:

That’s where you’ll be able to enter your new Diversion account info (username, email, password) or choose to sign up using a Google account, and then you’ll simply need to confirm with the unique code sent to your email address:

And that’s it! At this point, you’ll have your Diversion account, and you’ll be auto-redirected to the welcome page with a step-by-step onboarding wizard (the following screenshot shows just the first step of this wizard):

This wizard walks you through the base steps for installing the Diversion command-line tool (dv), configuring it to use your new account, and using it to initialise or update a Diversion version control repository.

So, now that we have access to the tool, let’s see how to actually set it up on our computer and use it for our own projects…

A quick peek at the Diversion CLI tool

Before talking about mixing Diversion with Godot, we need to start by installing and preparing our Diversion CLI. To do this, we simply have to use the CURL download URL provided on the welcome page.

This depends a bit on your OS. You’ll find all the necessary details in the quickstarting guide - but typically, for my Mac, I can use the following:

curl -sL https://get.diversion.dev/unix | bash

Once it’s done, we can simply open a new terminal (or re-source the current one to take the changes into account), and we’ll have a brand new dv tool we can use to init or inspect a Diversion repo.

For example, to check that all went well, just call dv help - you should get a detailed list of all the available commands, with neat (and even coloured!) instructions that show you a lot of nice tricks for using this CLI tool:

You’ll notice that there are actually a good deal of commands you can play with to create, update, reset or share your repo contents.

By the way a nice thing is that you can use all of those in interactive mode by first typing dv in your console to enter a new Diversion CLI context, and then use those commands without the dv prefix at the beginning. Plus, this gives you really cool bonus helpers like a command menu, and autocomplete!

And if you’re a bit familiar with the famous Git VCS, you’ll also see that many of those commands are super similar. So, basically, if in doubt, you can usually start by “mimicking” your git [X] command with dv [X], and there is a good chance that it will work directly :)

Though, because Diversion is first-and-foremost a collab dev cloud-based version control tool, there’s also many additional utilities for working with other teammates, such as:

• dv status -sync-only or dv status -wait: Compared to the simple git status command, Diversion lets you enforce the sync has happened if you want by using dv status -wait. This way, you’re sure that you’re seeing the latest changes in your repo at any moment!
• dv invite: It allows you to invite a new collaborator to the repo by passing in their email. Note that you can also specify the level of access you want to give them by adding an additional <access> option:
  • dv invite <email> –-access WRITE
  • dv invite <email> –-access READ
  • dv invite <email> –-access ADMIN
• dv share: It shares your repo with one or more other Diversion usernames, either in read-only mode (default) or in read/write mode if you add the –-rw option at the end. The users are referenced by their usernames, and you can pass a list of space-separated usernames if you want: dv share <user1> <user2> –-rw.

Moreover, the dv login, dv logout and dv view are commands to directly sign in or out of your Diversion account, and to use the web interface instead of the CLI if you prefer to manage your repo.

Typically, if you want to login into your account from the CLI, you can just run dv login. Your browser will automatically open an OAuth authentication page and, assuming you’ve logged in your Diversion account earlier, you’ll directly be signed in, and you’ll be able to instantly come back to your shell.

Ok - now, with all this in mind, let’s see how to use the code>dv CLI to version a simple Godot project, and discover the Diversion web app.

Versioning a Godot game with Diversion

Preparing the Godot demo project

For this tutorial, I’m going to use Godot’s “Dodge the creeps” official demo project, which you can get for free on the official Github. It’s a basic 2D game where you control an avatar with the arrow keys and you have to avoid the enemies that are spawning randomly around you:

Note: Although the Github branch is marked as 3.5X, the project also works directly in Godot 4 :)

To get the project, you can download the whole repo as a zip, or clone it locally on your computer using Git; then, open your Godot app and, in the startup project browser, click the Scan option:

Then, go to your local copy of the dodge-the-creeps/ demo folder, and click Select Current Folder - this will auto-add the project to your Godot projects list, and you’ll be able to double-click on it to open it as usual:

Inside, you’ll find a simple 2D scene that looks like this - and that you can run to try out the demo game yourself :)

Initialising the Diversion repo

**_Important note: This part of the guide assumes you’ve logged into your Diversion account from the CLI, using the dv login command, as discussed before :)

Now that we have a Godot project to version, let’s see how to use Diversion for it.

To start up, we can just open a shell, go to this folder and run the dv init command. We need to pass in the path of the folder to create a repo for, so here it’s just our current folder (dv init .):

This will do several things:

• It will create a new Diversion repo linked to this specific directory.
• It will auto-add a .dvignore file in the folder, which is the equivalent of the .gitignore file for a Git-versioned project.
• It will register this repository in your Diversion account to make it accessible from anywhere on the web app.

Note that the base contents .dvignore file are improved regularly by the Diversion team and now contains some goodies for Godot game devs (like the .godot/ folder that is auto-generated by any Godot 4 project, and contains some cache files that don’t require versioning). So although you can always edit it to fit your own specific architecture, it should usually be fine as-is for your game projects :)

So, now, let’s have a look at what files in our Godot demo project are ready for versioning by running the dv status command:

That’s nice!

You see that our Diversion versioning only takes into account the “real” assets in our project. Moreover, we can notice something at the very bottom of the screenshot: Diversion shows us a Sync complete message.

That’s because, as we said before, Diversion being a cloud-native tool, your repositories are always synced to the online version available via the web app…

Exploring the Diversion web app

To get a direct link to the online version of this repo, we’ll simply run the dv view command. This opens a new browser page in the Diversion app (as usual, you’ll need to be logged in to see it) that is dedicated to this specific project:

At the very top, we see the name of the repo and the branch we’re currently viewing - here it’s dodge-the-creeps, and main.

Then, below, we have a list of files corresponding to our current workspace that perfectly reflects the results from our last dv status command, and a list of the latest commits. You see that we can also commit files from this interface using the left sidebar.

Typically, let’s say that we want to add all of those files, and create a new commit about adding the Godot demo project. Then we could click on the checkbox at the very top of the workspace view to select all files, enter our commit message in the input field at the bottom, and click the Commit button:

As soon as we click on the Commit button, we get a confirm window, and then a quick spinner while Diversion actually does the commit… and here we go!

Our new commit now appears in the list of recent commits on the right, and we see our workspace has no modified files anymore :)

By the way, if you have a longer history in your Diversion repo and you want to keep track of some older modifications, you can also go to the left sidebar and switch over to the History tab to see the full evolution of your project, or search for a specific commit:

Of course, we could also come back to our shell and, inside our Diversion-versioned repo, run the dv log command - and sure enough, our new commit is already synced locally, too!

Now that we know the basics, let’s see how to use branches in Diversion to help organise collaborative development, handle important features, or just follow common DevOps workflows like Trunk-based Development.

Working with branches

As most (if not all) VCS tools, Diversion has branch-related features that let us easily create, switch between and delete branches.

So in this last part, we’re going to quickly recall why using branches when versioning a project can be beneficial, and we’ll see how to apply this to our Diversion/Godot demo project.

Why should I use branches when working with a versioning tool?

Using branches in version control systems is an efficient way to manage code changes, collaborate with team members, experiment with new features, and maintain a stable and organised codebase.

Most notably, branches provide the following advantages:

• Isolating new features or big changes: Branches allow you to work on specific features or changes without affecting the main or stable codebase. This is crucial in preventing unfinished or potentially unstable code from impacting the rest of the project.
• Supporting parallel development: Multiple developers can work on different features simultaneously by creating separate branches. This parallel development can significantly speed up the overall progress of a project - and it’s totally aligned with the main objectives of Diversion, and its cloud-native nature :)
• Testing or experimenting: Branches are also a safe space for tinkering with new ideas or implementing potentially disruptive changes. Developers can create feature branches, test new code, and easily discard or merge it back into the main branch if successful.
• Collaborating & doing code reviews: Branches help with the code review process, too. After they’ve created their branch and committed changes on them, developers can initiate a pull request for team members to review before merging into the main branch. This ensures that changes meet quality standards and follow the team's coding conventions.
• Managing releases: Branches are often used to manage releases. This can help plan, verify and execute a nice release schedule while always maintaining a stable main branch.
• Doing hotfixes: If critical issues are discovered in the released version, branches can be used for quick hotfixes. This is a sort of “practical application” of the parallel development mentioned before: thanks to branches, you can address urgent problems without affecting the ongoing development work in the main branch.

So having branch-related features is a must-have for version control solutions - and Diversion has got some to make it easy to work in parallel.

Using branches in Diversion

If we take a look at the dv branch documentation in the CLI tool, by running the dv help branch command, we get the following:

To test the branch features, what we’re going to do is change the Godot demo a little to have enemies move more slowly; we’ll suppose this is some experimental changes that we want to test to make the game easier, but we’re not too sure it will be perfect - so we’d rather use a branch to isolate our new development.

To create our new branch, we can use dv branch -c <name>. Then, if we run the dv status command, we’ll see that the CLI auto-switched us to our new branch (contrary to Git, for example, that doesn’t auto-check you out on your new branch):

If you want, you can also have a look at the browser and you’ll see that this new branch will have appeared in the project online dashboard, and you’ll be switched on it:

We’re now on our new branch, ready to work. The next step is to actually do our change in the code, to reduce the enemies’ speed.

To do this, let’s go to the Main.gd script, in the _on_MobTimer_timeout() function, and replace:

# Choose the velocity for the mob.
var velocity = Vector2(randf_range(150.0, 250.0), 0.0)

With:

# Choose the velocity for the mob.
var velocity = Vector2(randf_range(50.0, 150.0), 0.0)

If you run the game again, you’ll notice that the enemies now move more slowly, making it slightly easier to dodge them and last longer. The modified file is also visible if we do a new dv status:

And, in the web app, you can click on the modified file in the Workspace tab, and select the split view at the top to compare the modified version to the previous one:

Ok so - now, let’s commit our changes in the branch, so that everyone in the team can use this branch to try out our modification and give some feedback.

You could also use the shell to commit the file by running the following command:

dv commit -m "test(core): reduce enemies speed" Main.gd

Plus, if you want, you can always compare two branches by selecting them in the dropdown at the top, and then selecting the commits to compare:

Finally, suppose the team decides to keep this change and wants to integrate it in the production version of the game. Then, to re-merge this new commit in the main branch, we just need to switch back to this branch (with dv checkout main), and use the dv merge command with our test branch name:

It’s important to remember that merging a branch doesn’t automatically destroy it (because you might want to keep working on it afterwards, depending on the situation). So to really clean up our work session here, we should also remove our test branch.

This screenshot shows the state of the branches before deletion (the first run of dv branch), the deletion of the branch (dv branch -d test/enemies-slower) and the state of the branches after deletion (the second run of dv branch):

And, as usual, you can come back to the web app to check the repo is perfectly reflected, and the test branch has indeed disappeared:

Conclusion

So there you go: you now know how to initialise, configure and update a Diversion repository for a Godot project. And you even know how to work with branches to get a more organised workflow and support your collaborative dev!

Of course, this was just a quick intro to using Diversion for version control, and more specifically for a Godot project. But of course, if you’re curious, you should definitely have a go by going to the official website, or joining their Discord to ask all your questions directly :)