Skip to content

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

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.

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

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.

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.

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 456th 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 456th 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).

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 name 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 names 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.