Comparing with Other Source Control Tools¶

FlexVault draws on ideas from Perforce, Git, and Jujutsu while adding concepts of its own. If you already use one of these, or Epic's Lore, the sections below map what you know onto FlexVault's model.

The aim here is to describe how the workflows differ, not to argue that one tool is better than another. For the concepts themselves, see the Introduction and The Revision Model.

Concept map¶

Jump to a guide: FlexVault for Git users · FlexVault for Perforce users · FlexVault for Jujutsu users · FlexVault for Lore users.

FlexVault for Git users¶

Git is distributed. You clone the entire history, and that clone is a complete repository in its own right. FlexVault is centralized: the repository holds the shared history, and your workspace holds a working copy plus your own local draft revisions. There is no local copy of the full history, and no exchanging branches directly between machines.

The closest single parallel is that fxv sync does the work of git pull --rebase: it brings in the latest published revision and rebases your unpublished drafts on top of it, in one step.

What works differently¶

FlexVault has no staging area. A snapshot captures the state of the whole workspace, so there is no equivalent of git add or of crafting a commit from selected hunks.

Before any command changes your workspace, FlexVault snapshots your current state, and you can record working snapshots at any time with fxv snapshot.

Drafts stay in your workspace until you publish them. Because published history is shared and append-only, there is no force-push or history-rewriting workflow to learn.

Branches are persistent. In Git a branch is a movable pointer: merge or squash it and delete the ref, and you can be left with commits whose branch is no longer known. In FlexVault every revision stays permanently associated with the branch it was made on, so that history is never lost. There is no branch deletion command, and a branch you have finished with is retired instead, which hides it from listings and blocks publishing to it without removing anything.

Branches are just as cheap to create as in Git, with fxv branch new, fxv branch switch, and fxv branch rename. A branch also has an owner: a bare name like main is a global branch, and alice/fix-shaders is a user branch owned by alice, with the two namespaces kept separate. What Git does with git merge between two branches has no equivalent yet, see Not yet available.

Local operations are non-destructive, and this is a key advantage of FlexVault with regards to the safety of your work and the resilience of your workspace. Every command that changes your workspace snapshots your current state first, so nothing you do locally is lost. Suppose you run fxv revert --all in the wrong window and your changes vanish. With git reset --hard or git checkout -- ., uncommitted work is simply gone; the reflog only tracks commits, not your working tree. In FlexVault the pre-command snapshot preserved everything, and the CLI prints the exact fxv goto command to return to it. The same protection covers fxv goto and fxv sync.

Revision IDs are readable and ordered. main.457 is the publish that followed main.456 on main, and main.457.2 is your second local draft on top of it, which is easier to reason about at a glance than a commit hash.

Large files¶

Git stores a complete object for every version of every file, and every clone contains all of it. Large binaries therefore inflate the repository permanently, and the cost is paid by everyone who clones it. Git LFS moves those files out of band, but it introduces a second system to configure and operate alongside Git, and it is a common source of trouble in practice.

FlexVault is built for this case rather than adapted to it. Its store is designed for large files, and for huge monorepos of co-located code and collections of large binary assets, so large binaries do not require a separate mechanism.

FlexVault for Perforce users¶

Of the three, Perforce is the closest match in terms of workflow and architecture. Both systems have a central source of truth and a workspace that you sync against it, and both are built with large binary assets in mind.

The main structural difference is what sits at the center. A Perforce setup runs a server that you administer. A FlexVault repository is an object storage bucket, so there is no server process to run, patch, or size.

What works differently¶

There is no check-out step. You edit files in your workspace directly, with no p4 edit beforehand and no need to tell the server what you intend to change.

fxv sync does more than p4 sync. As well as bringing your workspace up to the latest published revision, it merges any unpublished drafts you have on top of that revision.

Your in-progress work is real history. A pending changelist is a staging area for files you have open, whereas draft revisions are versioned snapshots you can inspect with fxv changeinfo, compare with fxv diff, and return to with fxv goto.

Published revision numbers are per branch. main.457 counts publishes to main, rather than being a single server-wide sequence like a changelist number.

Branches are not streams. There is no stream spec to define, no parent and child relationship to configure, and no re-parenting. A branch starts from a revision and continues from there, either as a global branch with a bare name like main, or as a user branch prefixed with its owner's username, such as alice/fix-shaders. Nothing is deleted: a branch you have finished with is retired, which takes it out of listings and blocks publishing to it.

Local operations are non-destructive. p4 revert discards your pending changes for good, whereas FlexVault snapshots your state before every workspace change, so an accidental revert or move can be undone with the fxv goto command it prints for you.

FlexVault for Jujutsu users¶

Jujutsu is the closest of the three in philosophy. Jujutsu treats the working copy as a commit and snapshots it automatically, which is close to FlexVault's draft revision model where working states accumulate on top of the base revision. In both systems, the question of whether you remembered to commit does not arise.

The divergence is underneath. Jujutsu is backed by Git, so it inherits Git's storage model and the large-file characteristics described above. FlexVault has its own store and a centralized repository, so there is no Git repository behind the scenes and no push and fetch of refs.

What works differently¶

Automatic rebasing has a narrower scope. Jujutsu rebases descendant changes when you rewrite something in the middle of a stack. FlexVault applies the same idea in one place: fxv sync rebases your unpublished drafts onto the newest published revision.

Revision identifiers work differently. Jujutsu separates a stable change ID from a commit ID that moves as the change is rewritten. FlexVault has a single revision ID whose position in the sequence is the meaningful part, with published and draft revisions distinguished by whether a third component is present.

Revsets have no equivalent. Jujutsu's query language for selecting sets of revisions is more expressive than what FlexVault offers, where commands take a single revision ID.

Branches are persistent, where Jujutsu's are not. Because Jujutsu is Git-backed, its bookmarks (what Jujutsu calls branches) are movable pointers that can be deleted or lost. In FlexVault a branch is permanent, and every revision stays associated with the branch it was made on. Both keep branching cheap; the difference is that FlexVault never forgets a branch.

Both protect your local work. Jujutsu snapshots the working copy before each command and records it in the operation log, so jj undo recovers from an accidental destructive command. FlexVault gives you the same safety net through its per-command snapshots and fxv goto. This is one of the closest similarities between the two, and one of the sharpest contrasts with Git and Perforce, where the equivalent mistakes can lose work outright.

FlexVault for Lore users¶

Lore is architecturally close to FlexVault, in the same way Perforce is. Both are centralized, content-addressed systems built around a repository that holds the shared history, with the remote as the source of truth for durability and conflict resolution. Both are designed for projects that combine source code with large binary assets. Lore's instance, a local working directory with its own staging and branch state, corresponds to FlexVault's workspace.

What works differently¶

Lore has a staging area. lore stage records intent, and lore commit builds the revision from what is staged, closer to Git's add-then-commit split. FlexVault has no staging step: a snapshot captures the whole workspace at once, and hashing happens at that point rather than in a separate stage.

Both let you keep working without a network connection. Lore's lore commit and lore branch create advance local pointers with no round trip, and lore sync and lore push reconcile them with the remote afterward. FlexVault's draft revisions accumulate in your workspace the same way, until fxv publish sends them to the repository.

Locking a file and protecting a branch from direct pushes are explicit commands in Lore, lore lock acquire and lore branch protect. FlexVault does not expose either yet. See Not yet available.

Branches are persistent in both, so a branch and its revisions stay around once created.

Not yet available¶

Some capabilities that experienced users of these tools expect are still in progress. See the roadmap for current status.