Skip to content

Introduction to FlexVault

This page is a high-level overview of FlexVault's core concepts for people who are new to the product or to version control in general.

If you already use another version control system, Comparing with Other Source Control Tools maps FlexVault onto the concepts you know.

FlexVault is under active development

FlexVault is evolving quickly. Commands and workflows described here can change, and you may run into rough edges as features land and settle. We are continually making improvements, so expect this documentation to move with the product.

Core concepts

Version control systems are ultimately shared file storage with structured history and auditing attached. The goal is to store files safely, to be able to go back in time and see how they changed, and to see who changed them.

Repository and workspace are separate places

In FlexVault, the central store for shared files is the repository. Users keep a copy of some or all of those files on their own machine in a workspace. The workspace is where you add, remove, and edit files, such as an existing project you already have, and those changes accumulate as draft revisions. When the work is ready, you publish it, which sends it to the repository and makes it available to everyone else.

A repository normally lives in S3-compatible object storage, which keeps the distinction automatic since your workspace is a local directory and the repository is not. For solo or local projects, a repository can live on your local filesystem instead, at the cost of making backup your own responsibility; in that case the repository is still a directory of its own, similar to a database directory, and should stay separate from any workspace directory rather than pointing both at the same path. Local filesystem repositories are not supported on network storage such as NFS or SMB, because FlexVault's locking guarantees are untested there. See Set up a Local Filesystem Repository.

Your local history is tracked for you. When you make changes, snapshot your local progress with fxv snapshot to create draft revisions. If you work in a supported game engine, the editor plugins for Unity, Godot, and Unreal Engine take draft snapshots automatically as you work.

Your local work is safe

Almost everything you do in FlexVault can be undone. Before any command changes your workspace, FlexVault snapshots your current state, so local operations are reversible by design. If you run the wrong command and your work seems to disappear, that snapshot preserved it, and FlexVault shows you the exact fxv goto command to return to where you were in the CLI output. You do not have to have snapshotted manually, and you do not have to reconstruct anything by hand.

Revisions at a glance

Every revision has a revision ID built from the branch name and one or two numbers. Published revisions look like main.457. Draft revisions add a third part, like main.457.2.

The distinction that matters day to day: published revisions are shared with everyone on the branch, while draft revisions exist only in your workspace until you publish them.

---
title: "Draft revisions in your workspace, published revisions in the repository"
---
%%{init: {"themeVariables": {"git0":"#3f72bd","git1":"#2f8a72","git2":"#8b5fae","git3":"#b07d2e","gitBranchLabel0":"#ffffff","gitBranchLabel1":"#ffffff","gitBranchLabel2":"#ffffff","gitBranchLabel3":"#ffffff","commitLabelColor":"#111827","commitLabelBackground":"#f2f4f7","tagLabelColor":"#12305c","tagLabelBackground":"#dbe7f8","tagLabelBorder":"#8fb0da","lineColor":"#8b949e"}}}%%
gitGraph
    commit id: "main.456"
    commit id: "main.457"
    branch main.457-drafts
    checkout main.457-drafts
    commit id: "main.457.0"
    commit id: "main.457.1"
    commit id: "main.457.2" tag: "Head"

The Revision Model covers the rest: how draft numbers advance, what publishing does to your workspace, how syncing merges your drafts onto other people's work, and how to move back to an earlier revision.

Where to next