FlexVault Glossary¶

A¶

Admin user¶

The initial user seeded into a repository when it is created, named by fxv repo new --admin-username. It bootstraps the repository's user database, and further users are added with fxv user add.

B¶

Branch¶

A branch is an isolated line of work: a set of revisions that proceeds independently of other branches, whether for a separate work-stream or a separate project. A branch holds both draft and published revisions, not just published ones. Every repository starts with a default branch named main, and every revision ID begins with its branch name, as in main.456.

Branches are cheap to create, as in Git or Jujutsu, but unlike those systems they are persistent rather than ephemeral. In Git or Jujutsu a branch is a movable pointer: once nothing references it, or its commits are squashed away, the branch and the association between it and those commits can vanish. In FlexVault a branch is permanent, and every revision stays associated with the branch it was made on.

There are two kinds of branch. A global branch lives in the repository's global namespace and is written as a bare name, such as main. A user branch is owned by one user and is written with that owner's username as a prefix, such as alice/fix-shaders. Both are created, listed, and moved between with fxv branch, and a branch you are finished with is retired rather than deleted.

A branch's name is a label on it rather than the branch itself. fxv branch rename changes the name while the branch, its history, and its revisions stay as they were, because a branch is identified by its branch ID.

For a walkthrough of working with a team across branches, see Collaborate with Branches.

Branch ID¶

The identifier a branch is known by internally, written as bare hexadecimal and shown with a leading #, as in #0a1b2c3d4e5f6071. It is assigned when the branch is created and never changes, which is what allows a branch to be renamed without disturbing anything recorded against it.

Its visible purpose is telling apart two branches that share a name, which happens when a branch created locally has the same name as one someone else has published. fxv branch list --extended shows the ID for each branch, and --format json always includes it.

You address a branch by its name. Commands do not accept a branch ID as an argument.

C¶

Command¶

A single unit of work fxv performs on a workspace or repository, such as a sync, a publish, or a snapshot. Commands that modify the workspace are non-destructive: the workspace is snapshotted first, and local changes are preserved rather than overwritten. Every command is listed in the CLI reference.

Conflict¶

A conflict occurs when a sync finds that one of your local draft changes overlaps a change that has already been published. FlexVault flags the affected files, and they must be settled with fxv resolve before you can publish. See Merging and Conflict Resolution.

Consistent state¶

A workspace is in a consistent state when its files on disk match the revision it is recorded as being synced to, aside from any local changes you have made yourself. This is the normal state of a workspace, and it is what every command expects to start from. The opposite is an inconsistent state, which is left behind by an interrupted command and must be recovered before most commands will run.

D¶

Direct S3 mode¶

The setup in which a workspace or repository connects to an S3-compatible bucket using S3 access credentials passed on the command line. It is fully supported but interim: FlexVault does not yet have its own authentication layer, so access is governed entirely by the bucket credentials. Once a dedicated authentication layer lands, direct S3 mode will remain supported but will no longer be the recommended way to run a shared repository. See Set up a Remote Repository.

Draft revision¶

A draft revision is generated via a snapshot operation, and will have a format like <branch>.<published_revision>.<draft_revision>, for example main.456.1. The first part of the revision before the '.' character is the branch the revision is on, the second part is the published revision number of the published revision that this draft revision is based on, and the third part is the draft revision number of this draft revision on top of that published revision. In the example of main.456.1, this is the first draft revision on top of the published revision main.456. On a branch that has not been published to yet there is no published revision to build on, and the published position is written as -, as in alice/fix-shaders.-.1.

F¶

FlexVault Agent¶

A background process that periodically snapshots your workspace as you work, creating draft revisions automatically. When the agent is enabled, recent states of your workspace are recoverable even if you never run fxv snapshot yourself.

G¶

Global branch¶

A branch in the repository's global namespace, written as a bare name with no owner prefix, such as main. Every repository starts with one global branch, main. Others are created with fxv branch new --global, which requires the revision the branch is created from to be a published revision of a global branch. Because everyone refers to a global branch by name, retiring or renaming one requires --force, and the repository's default branch cannot be renamed at all.

A bare name always refers to the global branch of that name and is never an alias for a user branch, so main and alice/main are two separate branches and main does not begin referring to alice/main because someone creates one.

H¶

Head¶

The most recent revision at a given point. Your workspace head is the revision your workspace currently points at, the one new snapshots build on and that fxv goto moves. The branch head is the latest published revision on a branch. fxv status shows both.

I¶

Inconsistent state¶

A workspace may be put into an inconsistent state if an operation that modifies it was interrupted before it finished. In this state, the workspace is typically part-way between two revisions, and most commands that read or change workspace state will refuse to run until the inconsistency is resolved. You can see if your workspace is in an inconsistent state by running fxv status. Recovery is typically done with fxv resume.

L¶

Local repository¶

A repository stored on a local filesystem path rather than in object storage, created with a file:// URI. Suitable for solo or single-machine use; backup is your responsibility, and it is not supported on network storage. See Set up a Local Filesystem Repository.

O¶

Object storage¶

An S3-compatible storage service (such as AWS S3, Google Cloud Storage, Cloudflare R2, or Tigris) that holds a remote repository. FlexVault reads and writes it directly over the S3 API. See Set up a Remote Repository.

Operation¶

A synonym for a command. The terms may be used interchangeably throughout this documentation.

P¶

Publish¶

To publish a file or set of files is to push those files from your local workspace to the central repository.

Published revision¶

A published revision is generated via a publish operation, and will have a format like <branch>.<published_revision>, for example main.456. The first part of the revision before the '.' character is the branch that the revision was published to, and the second part is the published revision number, which counts publishes to that branch in order. Numbering starts at 0, so a branch's first publish is main.0 and the example main.456 is the 457^th publish to the main branch. To publish a revision, the fxv publish command is used.

R¶

Remote repository¶

A repository stored in S3-compatible object storage, which is how a repository is shared between people and machines. See Set up a Remote Repository.

Repository¶

A centralized store for files, typically shared between team members. A repository is either a remote repository in object storage or a local repository on a filesystem path.

Retired branch¶

A branch marked as finished with fxv branch retire. Retiring hides the branch from the default fxv branch list output and blocks fxv publish to it.

Nothing else changes. The branch's history is still readable, fxv branch switch still moves onto it, a new branch can still be created from one of its revisions, and local work can still be snapshotted on it. A snapshot on a retired branch warns that publishing is blocked, saves the work anyway, and keeps the retired status, so publishing again requires fxv branch restore.

Nothing is deleted, and FlexVault has no command that fully deletes a branch.

Revision¶

A revision may refer to one of two states: a published revision or a draft revision.

Revision ID¶

A revision ID is a string that uniquely identifies a published revision or a draft revision. Depending on the type, the format string will be different, but as summary, a published revision will be of the format <branch>.<published_revision> (e.g. main.456, a published revision on the main branch, whose number counts publishes to that branch starting from 0), and a draft revision will be of the format <branch>.<published_revision>.<draft_revision> (e.g. main.456.1, indicating the first draft revision on top of the published revision main.456).

A branch with nothing published on it yet writes - in the published position, so the first draft revision on a newly created branch is alice/fix-shaders.-.1.

RPC server¶

The RPC server is a mode of the fxv executable, started with fxv rpc, that operates on a workspace by exchanging JSON messages over its standard input and standard output instead of being run once per command. It exists so a long-running program can query the same workspace repeatedly without starting a process for each call. See the RPC section.

S¶

Snapshot¶

A snapshot records the current state of your workspace as a new draft revision on the current branch. Snapshots can be created with fxv snapshot, automatically before commands that modify the workspace, or automatically by game engine plugins as you work. A snapshot is local to your workspace until you publish.

Sync¶

Bringing your workspace to a published revision of its branch, performed with fxv sync. By default it syncs to the latest published revision; you can also specify an earlier revision to sync backwards to it, an advanced move used mainly to roll back bad changes. Any unpublished draft revisions you have are merged on top of the target revision, so your in-progress work is preserved. Changes that collide with already-published changes are flagged as conflicts.

U¶

User¶

A user is an identity recorded in the connected repository's canonical user database (managed via fxv user), used to attribute publishes and commits to a real person rather than an unattributed local author. There is no authentication yet - a workspace is logged in as a user via fxv login, which only checks that the username refers to an active (not deactivated) user. A logged-in user is required to publish; draft-side commits (snapshot, sync, goto, resolve) attribute to the logged-in user opportunistically but do not require one.

User branch¶

A branch owned by one user, written with that owner's username as a prefix, such as alice/fix-shaders. Created by fxv branch new without --global, which takes the name on its own and reports the full name of the branch it created.

Branch names are unique per owner rather than across the repository, so alice/fix-shaders, bob/fix-shaders and a global branch called fix-shaders are three different branches. A user branch is always written in full, including your own.

A user branch keeps its owner for life. fxv branch rename changes only the name, and rejects a new name prefixed with someone else's username, because a rename does not transfer the branch.

Ownership is advisory. There is no authentication yet, so it records who a branch belongs to rather than restricting who can work on it.

W¶

Workspace¶

A workspace is you (the user's) local copy of a set of files from the central repository. This is where you make changes to your files in order to eventually publish then back to said central repository.

Workspace path¶

How every FlexVault command interprets a file path you give it. A plain path is relative to your current directory, exactly as it would be for any other command line tool, so fxv cat notes.txt reads the notes.txt next to you. A path that starts with a separator is anchored at the workspace root instead, so fxv cat /docs/notes.txt refers to the same file from anywhere in the workspace.

Both forms must land inside the workspace. .. is allowed as long as the result stays within it, and a path that leaves the workspace, resolves to the workspace root itself, or points into the workspace's own .fxv_workspace directory is rejected. Symbolic links are not followed.