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; further users are added with fxv user add. Because there is no authentication yet, the admin user is simply the first recorded identity and carries no special enforced privileges.

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.

Creating and switching between branches from the command line is not yet available; see Comparing with Other Source Control Tools.

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.

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.

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 indicates the order in which the revision was published. In the example of main.456, this was the 456^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.

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, indicating the 456^th published revision to the main branch), 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).

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 are created automatically by the FlexVault Agent as you work, and can be made manually with fxv snapshot. 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 rebased 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.

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.