The Revision Model¶

This page explains how FlexVault identifies revisions, how draft and published revisions relate to each other, and what happens to your work when you publish, sync, or move the workspace to an earlier point. If you only want the high-level picture, the Introduction covers it in a few paragraphs.

Revision IDs¶

Every revision, whether a draft revision or a published revision, is identified by a revision ID. Each ID is made up of up to three parts separated by a . character: the branch name, the published revision number, and, if present, the draft revision number.

Quick reference

Published revisions look like branch_name.number, for example main.123 or my_feature.4
Published revisions are shared across the team.
Draft revisions look like branch_name.number.draft_number, for example main.123.4 or my_feature.4.2.
Draft revisions are local to your workspace only.
The draft revision .0 is a special alias that always points to the published revision it is based on, so main.123.0 is an alias for main.123.

Working in a new workspace¶

Say you are working in the main branch. The most recent publish was main.456, meaning it is the 456^th publish to that branch. When you create a workspace and sync it, your workspace pulls in the files from main.456 and creates a local draft revision on top of it, main.456.0.

As you work, the FlexVault Agent snapshots your changes automatically, creating new draft revisions as it goes: main.456.1, then main.456.2, and so on. You can also snapshot manually with fxv snapshot.

---
title: "Draft revisions accumulating on top of `main.456`"
---
%%{init: {"themeVariables": {"git0":"#3f72bd","git1":"#2f8a72","git2":"#8b5fae","git3":"#b07d2e","gitBranchLabel0":"#ffffff","gitBranchLabel1":"#ffffff","gitBranchLabel2":"#ffffff","gitBranchLabel3":"#ffffff","commitLabelColor":"#111827","commitLabelBackground":"#f2f4f7","tagLabelColor":"#12305c","tagLabelBackground":"#dbe7f8","tagLabelBorder":"#8fb0da","lineColor":"#8b949e"}}}%%
gitGraph
    commit id: "main.454"
    commit id: "main.455"
    commit id: "main.456"
    branch main.456-drafts
    checkout main.456-drafts
    commit id: "main.456.0"
    commit id: "main.456.1"
    commit id: "main.456.2"  tag: "Head"

Publishing¶

When your work is ready, fxv publish takes your current draft revision, main.456.2, and publishes it to the repository as a new published revision, main.457. Your workspace is updated to match, and your current draft becomes main.457.0.

Note

fxv publish requires you to be logged in as a user, see fxv login. Snapshotting your work as you go does not require this.

---
title: "Publishing your draft revision as `main.457`"
---
%%{init: {"themeVariables": {"git0":"#3f72bd","git1":"#2f8a72","git2":"#8b5fae","git3":"#b07d2e","gitBranchLabel0":"#ffffff","gitBranchLabel1":"#ffffff","gitBranchLabel2":"#ffffff","gitBranchLabel3":"#ffffff","commitLabelColor":"#111827","commitLabelBackground":"#f2f4f7","tagLabelColor":"#12305c","tagLabelBackground":"#dbe7f8","tagLabelBorder":"#8fb0da","lineColor":"#8b949e"}}}%%
gitGraph
    commit id: "main.454"
    commit id: "main.455"
    commit id: "main.456"
    branch main.456-drafts
    checkout main.456-drafts
    commit id: "main.456.0"
    commit id: "main.456.1"
    commit id: "main.456.2"
    checkout main
    merge main.456-drafts id: "main.457"
    branch main.457-drafts
    checkout main.457-drafts
    commit id: "main.457.0" tag:"Head"

Syncing and rebasing¶

If someone else publishes to main while you are working, for example publishing main.458, you bring their work into your workspace with fxv sync. If you have unpublished draft revisions, FlexVault rebases them on top of the latest published revision, so your in-progress work is preserved.

---
title: "Syncing and rebasing drafts from `main.457` onto `main.458`"
---
%%{init: {"themeVariables": {"git0":"#3f72bd","git1":"#2f8a72","git2":"#8b5fae","git3":"#b07d2e","gitBranchLabel0":"#ffffff","gitBranchLabel1":"#ffffff","gitBranchLabel2":"#ffffff","gitBranchLabel3":"#ffffff","commitLabelColor":"#111827","commitLabelBackground":"#f2f4f7","tagLabelColor":"#12305c","tagLabelBackground":"#dbe7f8","tagLabelBorder":"#8fb0da","lineColor":"#8b949e"}}}%%
gitGraph
    commit id: "main.457"
    branch main.457-drafts
    checkout main.457-drafts
    commit id: "main.457.0"
    commit id: "main.457.1"
    commit id: "main.457.2"
    checkout main
    commit id: "main.458"
    branch main.458-drafts
    checkout main.458-drafts
    merge main.457-drafts id: "main.458.1" tag: "Head"

If any of your draft changes conflict with what was published, sync completes with those files flagged as conflicts, and you resolve them with fxv resolve before you can publish. See Merging and Conflict Resolution for how the merge itself works.

From here you continue as normal, and publishing again produces main.459.

Moving to an earlier revision¶

You can move your workspace to any earlier revision, published or draft, with fxv goto. This is non-destructive: your current state is snapshotted first, so nothing is lost and you can always move back.

Say you are working at main.459.7 and want to return to main.459.3. Running fxv goto main.459.3 updates your workspace to the files as they were at that draft revision, while main.459.4 through main.459.7 remain in your history.

---
title: "Workspace moved back to `main.459.3` from `main.459.7`"
---
%%{init: {"themeVariables": {"git0":"#3f72bd","git1":"#2f8a72","git2":"#8b5fae","git3":"#b07d2e","gitBranchLabel0":"#ffffff","gitBranchLabel1":"#ffffff","gitBranchLabel2":"#ffffff","gitBranchLabel3":"#ffffff","commitLabelColor":"#111827","commitLabelBackground":"#f2f4f7","tagLabelColor":"#12305c","tagLabelBackground":"#dbe7f8","tagLabelBorder":"#8fb0da","lineColor":"#8b949e"}}}%%
gitGraph
    commit id: "main.458"
    commit id: "main.459"
    branch main.459-drafts
    commit id: "main.459.0"
    commit id: "main.459.1"
    commit id: "main.459.2"
    commit id: "main.459.3"  tag: "Head"
    commit id: "main.459.4"
    commit id: "main.459.5"
    commit id: "main.459.6"
    commit id: "main.459.7"

You can return to main.459.7 at any time by running fxv goto main.459.7. If instead you carry on working from main.459.3, new draft revisions branch off from that point, and your earlier drafts remain available in the history.

---
title: "Work continuing from `main.459.3`"
---
%%{init: {"themeVariables": {"git0":"#3f72bd","git1":"#2f8a72","git2":"#8b5fae","git3":"#b07d2e","gitBranchLabel0":"#ffffff","gitBranchLabel1":"#ffffff","gitBranchLabel2":"#ffffff","gitBranchLabel3":"#ffffff","commitLabelColor":"#111827","commitLabelBackground":"#f2f4f7","tagLabelColor":"#12305c","tagLabelBackground":"#dbe7f8","tagLabelBorder":"#8fb0da","lineColor":"#8b949e"}}}%%
gitGraph
    commit id: "main.458"
    commit id: "main.459"
    branch main.459-drafts
    commit id: "main.459.0"
    commit id: "main.459.1"
    commit id: "main.459.2"
    commit id: "main.459.3"
    branch main.459-drafts-2
    checkout main.459-drafts-2
    checkout main.459-drafts
    commit id: "main.459.4"
    commit id: "main.459.5"
    commit id: "main.459.6"
    commit id: "main.459.7"
    checkout main.459-drafts-2
    commit id: "main.459.8"
    commit id: "main.459.9"
    commit id: "main.459.10"  tag: "Head"