Skip to content

Use the Visual Studio Code Extension

The FlexVault Visual Studio Code extension integrates FlexVault version control directly into your editor. It drives the fxv command-line interface to track file status in the Source Control panel, show line-by-line gutter diffs, streamline snapshot and publish workflows, resolve conflicts, and browse repository history.

Install the extension from the Visual Studio Marketplace or Open VSX.

Compatibility

The extension supports Visual Studio Code 1.85.0 or newer.

The extension enforces semantic version checks against the fxv binary and blocks incompatible CLI versions. If your installed fxv is out of range, the extension displays a notification specifying the required range.

Before you begin

Confirm the following prerequisites before using the extension:

  1. Visual Studio Code 1.85.0 or newer is installed on your computer.
  2. The FlexVault CLI is installed and available on your system PATH (see Install FlexVault). If installed in a non-standard location, configure the executable path in extension settings.
  3. Your project folder is an initialized FlexVault workspace containing a .fxv_workspace directory.
  4. You have set your user identity via fxv login from the terminal or using the extension login command.

Install the extension

Choose either method to install the extension:

Method 1: Install from the Visual Studio Marketplace

  1. Open Visual Studio Code.
  2. Open the Extensions view by clicking the Extensions icon in the Activity Bar or pressing Ctrl+Shift+X (macOS: Cmd+Shift+X).
  3. Search for FlexVault.
  4. Locate the extension published by flexvault and click Install. You can also open the extension page directly on the Visual Studio Marketplace.

Method 2: Install from Open VSX

For VS Code-compatible editors such as VSCodium, Cursor, and Windsurf, install the extension from Open VSX using your editor's extension marketplace or its command-line install flag.

Method 3: Install from the command line

Run the following command in your terminal:

code --install-extension flexvault.flexvault-vscode

Configure extension settings

The extension discovers the fxv binary automatically from standard system installation directories and your system PATH. To customize behavior, open Settings (Ctrl+, or Cmd+,) and navigate to Extensions > FlexVault:

Setting Type Default Description
flexvault.cliPath string "" Absolute path to the fxv binary if not located on your system PATH.
flexvault.readTimeoutSeconds number 60 Timeout in seconds for read commands (status, history, cat). Set to 0 to disable.
flexvault.writeTimeoutSeconds number 0 Timeout in seconds for mutating commands (sync, goto, revert). Defaults to 0 (disabled) to avoid terminating operations mid-flight.
flexvault.refreshDebounceMs number 300 Debounce delay in milliseconds before refreshing status after file modifications.
flexvault.watchEnabled boolean true Enables or disables the internal file system watcher.
flexvault.watchExclude string[] [] Additional glob patterns excluded from file watching.
flexvault.contentCacheSizeMB number 512 Maximum size in megabytes for the on-disk diff content cache.
flexvault.historyLimit number 50 Maximum number of revisions retrieved in the History view.
flexvault.logLevel string "info" Output channel log verbosity (off, error, info, debug).

Work with the Source Control panel

When you open a folder containing a FlexVault workspace, the extension activates and registers as an SCM provider in the Source Control panel (Ctrl+Shift+G or Cmd+Shift+G).

Files appear across three groups depending on their status:

  • Conflicts: Files with unresolved merge conflicts that require resolution.
  • Unpublished: Revisions recorded locally that have not yet been published to the remote repository.
  • Workspace: Files with modifications, additions, or deletions on disk that have not been snapshotted.

Status updates automatically when you save, create, or delete files. To trigger an immediate status refresh, click the Refresh icon in the Source Control title bar or run FlexVault: Refresh from the Command Palette.

Save local work with snapshots

A snapshot records current workspace modifications as a local draft revision. Snapshots remain private to your machine until you publish them.

To take a snapshot manually:

  1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
  2. Run FlexVault: Snapshot.

The current state of your files is preserved, and the changes transition into the Unpublished group.

Share work with publish

The publish action transfers your local revisions to the remote repository:

  1. Open the Source Control panel.
  2. Enter a description in the commit message box. A description is required to publish.
  3. Click the Publish button or run FlexVault: Publish from the Command Palette.

The extension validates user authentication, snapshots pending changes, checks whether the local branch is behind remote revisions, synchronizes remote updates, and publishes your changes. If remote changes conflict with local work, the publish sequence pauses and places the conflicting files in the Conflicts group.

Synchronize updates from teammates

To download new revisions published by team members:

  1. Click the status bar item showing your branch and sync status, or click the Sync icon in the Source Control panel title bar.
  2. Alternatively, run FlexVault: Sync from the Command Palette.

The extension pulls published revisions from the remote branch and rebases your unpublished draft revisions on top of the new branch head.

Review changes with diffs and gutters

The extension integrates with editor diff tools:

  • Gutter decorations: Colored indicators in the editor gutter display modified, added, and deleted lines relative to the base revision.
  • Side-by-side diffs: Clicking a file in the Source Control panel opens a comparison view showing differences between your working copy and the base revision.
  • Diff caching: File contents for comparisons are cached in memory and on disk according to flexvault.contentCacheSizeMB. Run FlexVault: Clear Content Cache if you want to flush cached content.

Resolve merge conflicts

When a synchronization command detects conflicting edits between local changes and incoming revisions, affected files appear in the Conflicts group.

Hover over or right-click a conflicting file to choose a resolution action:

  • Resolve (Keep Mine): Keeps your local version and discards incoming modifications.
  • Resolve (Take Theirs): Accepts the remote version and replaces local modifications.
  • Resolve (Undo): Reverts the chosen resolution if you need to inspect the conflict again.

Once all conflicts are resolved, proceed with publishing.

Inspect revision history

The FlexVault History view in the Source Control container displays past revisions:

  1. Open the Source Control panel.
  2. Expand the FlexVault History tree view.
  3. Browse past revisions showing revision spec, author attribution, relative timestamp, and commit message.
  4. Expand any revision to list changed files. Clicking a file opens a diff against its parent revision.

Right-click a revision to access contextual actions, such as copying the revision spec or jumping to that revision with Go to Revision.

Recover from interrupted operations

If a network interruption, system shutdown, or process termination halts a mutating command mid-flight (CLI exit code 98), the workspace enters an inconsistent state.

The extension detects the journal state automatically and presents a recovery notification with two choices:

  • Finish: Resumes the interrupted operation and applies pending journal changes (fxv resume --continue).
  • Undo: Rolls back incomplete changes to return the workspace to its prior state (fxv resume --rollback).

Troubleshooting and support

  • Check logs: Run FlexVault: Show Log from the Command Palette to open the FlexVault output channel. Sensitive credentials and file paths are redacted.
  • Safety guards: The extension blocks mutating operations when open editor tabs have unsaved changes or while a debug session is running. Save open files or stop debugging before retrying.
  • Community support: Join the FlexVault Discord to report issues or request assistance.