Set up a Local Filesystem Repository¶

A FlexVault repository normally lives in S3-compatible object storage, as described in Set up a Remote Repository. It can also live on a local filesystem path, which is useful for solo projects or for trying FlexVault out without setting up a bucket.

When to use one¶

A local filesystem repository suits:

• Solo projects that live on a single machine.
• Evaluating FlexVault before committing to a storage provider.

Use object storage instead when the repository is shared between people or machines, or when you need the durability guarantees of a hosted service.

With a local filesystem repository, both the repository and your workspace are ordinary directories on the same disk, so it is worth being clear on the difference before creating either: see Repository and workspace are separate places. In short, point fxv init at your project folder, not at the repository directory; one repository can back workspaces for several projects or machines.

Create the repository¶

The target directory must already exist, and the path in the URI must be absolute.

On Linux and macOS the URI has three slashes, as in file:///path/to/my-repo: two belong to the URI scheme and the third is the root of the filesystem. On Windows, a drive letter takes the place of that third slash, as in file://c:/path/to/my-repo.

mkdir -p /path/to/my-repo
fxv repo new file:///path/to/my-repo --admin-username alice --admin-email alice@example.com

New-Item -ItemType Directory -Force -Path C:\path\to\my-repo | Out-Null
fxv repo new file://c:/path/to/my-repo --admin-username alice --admin-email alice@example.com

None of the --s3-* flags apply here. As with an object storage repository, --admin-username is required and seeds the repository's first user.

Link a workspace to the repository¶

fxv init creates your workspace and links it to the repository you just created, so that publishing from this directory sends history to that repository and no other. Give it the repository's file:// URI, and use --path to say which directory should become the workspace. You do not need to cd there first: fxv init creates the workspace at --path regardless of your current directory. Run the command below from wherever is convenient, such as the terminal you already have open, but note that ./my-workspace is relative to wherever that is; use an absolute path instead if you want to be sure where the workspace ends up:

fxv init file:///path/to/my-repo --path ./my-workspace

fxv init file://c:/path/to/my-repo --path ./my-workspace

./my-workspace is a placeholder, not a required name. Replace it with the path to whatever directory you want to work in. fxv init creates that directory if it does not exist yet, and adds tracking in place if it already does, such as for an existing game project you want to bring under FlexVault. Run the command from wherever is convenient and pass the project's path, or cd into the project first and omit --path to use the current directory:

cd /path/to/my-existing-project
fxv init file:///path/to/my-repo

cd C:\path\to\my-existing-project
fxv init file://c:/path/to/my-repo

This adds FlexVault's tracking to the project in place. The repository directory stays wherever you created it in the previous step, separate from the project.

From here the workflow is identical to the object storage setup: add a user, log in, snapshot, and publish. See Add your user and publish.

Back up the repository yourself¶

There is no remote copy of a local filesystem repository. The repository directory holds your published history, and if you lose it, that history is gone. Back that directory up the same way you back up anything else important on the machine.

Your workspace is not a backup. It holds your local draft revisions and a copy of the files you are working on, not the repository's full published history.

Local-only workspaces are another quick-and-dirty option¶

fxv init --local-only creates a workspace with no external repository at all, rather than a workspace connected to a separate filesystem repository. Everything, including published revisions, is stored inside the workspace's .fxv_workspace directory.

fxv init --local-only

This creates the workspace in the current directory. It is the least durable option: deleting .fxv_workspace destroys all history irrevocably. --local-only does not take a path, and cannot be combined with a repository URI. Prefer a file:// repository over --local-only, since it at least separates your repository from your working files.

Unlike fxv repo new, --local-only does not seed an admin user, so there is no user to log in as yet. Before you can publish, add yourself as a user and log in, the same as for any other workspace:

fxv user add alice --email alice@example.com
fxv login alice

See Add your user and publish for the full snapshot and publish workflow.

When you outgrow it¶

Once the project involves other people or another machine, create a repository backed by object storage and work against that instead. Set up a Remote Repository covers choosing a provider and creating the repository.