Skip to content

Learning Version Control Basics

If you have ever saved level.blend, then level_v2.blend, then level_final.blend, you have done version control by hand. A version control system keeps every version of your project for you, records who changed what and when, and lets you get any earlier version back.

In this guide you will set up FlexVault on your own computer, save versions of a small notes file, look back through its history, and get earlier versions back. Everything stays on your computer, so you do not need a cloud account. When you are ready to work with other people, Setting up a Shared Repository covers the next step.

This guide assumes FlexVault is installed. If it is not, follow Installing FlexVault first.

Before you start

There is more than one way to use FlexVault. Some people prefer typing commands in a terminal, and others prefer a desktop app. FlexVault Desktop, a graphical app, is in development but not yet available. FlexVault also works from inside the Unity Editor, Godot, Unreal Engine, and Visual Studio Code.

This guide uses the terminal, because every FlexVault feature is available there. Each step below shows the commands to type, followed by a recording of them running. Lines in the recordings that start with # are notes about what happens between commands, not commands you need to type.

New to the terminal?

A terminal is a window where you type commands instead of clicking.

  • Opening one: on Windows, open the Start menu, type Terminal, and open Terminal (or PowerShell on older versions of Windows). On Linux, open your Terminal app, often with Ctrl+Alt+T. On macOS, open Terminal from Applications > Utilities.
  • Where you are: the terminal always works inside one folder, shown in the prompt before the cursor, such as PS C:\Users\alice> on Windows or alice@workstation:~$ on Linux, where ~ means your home folder. A new terminal starts in your home folder.
  • Moving between folders: cd my-project moves into the my-project folder, and cd .. moves back up one level.
  • Running a command: type it, or paste it, and press Enter. To paste, use Ctrl+V in Windows Terminal, Ctrl+Shift+V in most Linux terminals, and Cmd+V on macOS.

Create a repository and a workspace

FlexVault uses two separate places:

  • The repository is where FlexVault stores the versions of your project that you publish. You never edit files in it directly.
  • The workspace is the folder you work in. It holds the current copy of your files, which you edit with your usual tools, along with the versions you have saved but not yet published.

You publish versions from the workspace into the repository, and you can bring any saved version back into the workspace. For a team, the repository lives in cloud storage and each person has their own workspace. On a single computer, both are ordinary folders, kept apart. Repository and workspace are separate places explains this in more detail.

In this step you create a repository folder called my-repo and a workspace folder called my-project next to it, and link the two. The commands use alice as the user name. Replace it with a name of your own, here and everywhere else it appears in this guide. Run these commands from your home folder:

mkdir my-repo
fxv repo new file://./my-repo --admin-username alice
mkdir my-project
cd my-project
fxv init file://../my-repo
fxv login alice

Here is what each command does:

  • mkdir my-repo creates an empty folder for the repository. In PowerShell, mkdir prints a short table describing the new folder.
  • fxv repo new turns that folder into a FlexVault repository. file:// tells FlexVault the repository is a folder on this computer, and ./my-repo means the my-repo folder inside the current folder. --admin-username creates the repository's first user with the name you give it.
  • mkdir my-project and cd my-project create the folder you will work in and move into it.
  • fxv init turns my-project into a workspace linked to the repository. ../my-repo means the my-repo folder next to my-project, since .. is the folder one level up. Keep the two folders side by side: if you move one without the other, the workspace can no longer find its repository.
  • fxv login tells FlexVault who is making changes, so each version records its author.

Save your first version

Open a text editor, such as Notepad, and save a file called notes.txt in the my-project folder with these two lines:

Level 1 notes
- Boss room needs a second exit.

Then run:

fxv status
fxv snapshot --description "Add level notes"
fxv history

fxv status shows that FlexVault has noticed the new file. fxv snapshot takes a snapshot: it saves the current state of every file in the workspace as a draft revision, a save point that only exists on your computer. The description is optional: fxv snapshot on its own works too. A short note makes a version easier to find later, though.

fxv history lists your saved versions, newest first. Each one has a revision ID, here main.-.1. main is the branch you are working on, and the - means nothing has been published yet.

Publish a version

Snapshots stay in your workspace, and only you can see them. When your work is in a state you would be happy to share, such as when a feature is finished or you are ready for your team to see it, publish it:

fxv publish --description "First notes"
fxv history

fxv publish copies your latest version into the repository as a published revision. Published revisions are numbered from main.0. This matters even when you work alone: draft revisions live inside the workspace folder, while published revisions are stored in the repository folder, separate from the files you are editing. When you later share a repository with a team, published revisions are also what everyone else sees.

Save a change and see what changed

Add a third line to notes.txt and save the file:

- Add two more enemies near the bridge.

Then take a snapshot and compare it with the published version:

fxv snapshot --description "Add enemies"
fxv diff

The new snapshot is main.0.1, the first save point after the published revision main.0. fxv diff compares your latest snapshot with the last published version and lists each changed file. Lines starting with + were added, and lines starting with - were removed. Because fxv diff compares snapshots, take a snapshot before you run it.

Look back through your history

Add one more line to notes.txt, save it, and take another snapshot:

- Move the save point closer to the boss.

fxv snapshot --description "Move save point"
fxv history
fxv changeinfo main.0.1

fxv history now lists every version so far, with its author, time, and description. To see the details of one version, give its revision ID to fxv changeinfo, which shows when it was made and which files it changed.

Go back to an earlier version

Suppose you delete most of notes.txt by accident and save it. Your last snapshot, main.0.2, still has the full file, so go back to it:

Get-Content notes.txt
fxv goto main.0.2
Get-Content notes.txt


cat notes.txt
fxv goto main.0.2
cat notes.txt

Get-Content on Windows and cat on Linux and macOS print a file's contents, so you can see the file before and after. fxv goto moves the whole workspace to the version you give it. Every file in the workspace changes to match that version, not only the one you were fixing.

Nothing is lost along the way. Before moving, fxv goto takes a snapshot of the workspace as it was, shown in the [1/3] line of its output, here main.0.3. If you change your mind, fxv goto main.0.3 brings the deleted-lines version back. From here you can keep working and taking snapshots as usual.

Restore a single file

Not yet available

The fxv copy command described here is planned but not yet part of FlexVault. Until it is available, use fxv goto.

fxv goto changes every file in the workspace. To get back an earlier version of one file and leave everything else as it is, fxv copy will copy that file's contents from any revision into your workspace and save the result as a new draft revision:

fxv copy notes.txt --from main.0.1

fxv copy copies the whole file as it was at that revision. It does not try to reapply an old change on top of your current file, so it works the same way for any kind of file, including images, models, and other binary assets.

Start over from the published version

Sometimes you try an idea and decide not to keep it. fxv revert puts a file back the way it is in the last published version. First, publish the current notes so they become the version to return to:

fxv publish --description "Enemies and save point"

Then add a line to notes.txt that you will throw away, save it, and revert the file:

fxv revert notes.txt
Get-Content notes.txt


fxv revert notes.txt
cat notes.txt

Like fxv goto, fxv revert takes a snapshot before it changes anything, here main.1.1, so the idea you threw away is still in fxv history. To revert every file in the workspace at once, use fxv revert --all.

Undo anything, including a revert

Every FlexVault command that changes your files saves what was there first, so any of them can be undone. Suppose you reverted by mistake and want that idea back after all. The snapshot fxv revert took, main.1.1, still has it:

fxv goto main.1.1
Get-Content notes.txt


fxv goto main.1.1
cat notes.txt

The line you reverted is back. The same works after a fxv goto: find the snapshot it took in fxv history and go to it. Because nothing is ever thrown away, you can try any command in this guide without worrying about losing work.

What to do next