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.

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, 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; Getting Started walks through creating one. For solo or local projects it can live on your local filesystem instead, at the cost of making backup your own responsibility. Local filesystem repositories are not supported on network storage such as NFS or SMB, because FlexVault's locking guarantees are untested there. See Use a Local Filesystem Repository.

Your local history is tracked for you. As long as the FlexVault Agent is enabled, it snapshots your local changes periodically in the background, creating draft revisions as you work, so you keep a trail of your progress even if you never snapshot manually.

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, both in the CLI output and in the app. 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 rebases your drafts onto other people's work, and how to move back to an earlier revision.

Where to next