Version Control Sync

Note: You can opt-in to this feature via the main app preferences



Version Control Sync is a feature included within Insomnia Plus and Insomnia Teams. Sync provides the following abilities on top of Insomnia:

  • The ability to snapshot the contents of a workspace
  • The ability to revert a workspace to a previous snapshot
  • The ability to share snapshots across devices or with members of your team
  • The ability to create and work on separate branches

The main features of sync can be accessed from the dropdown at the bottom of the sidebar.

Getting started

To start using Version Control, you need to first enable the feature by: 
  1. Navigating to Preferences > General
  2. Checking the "Enable version control beta" checkbox at the bottom of the preferences.

This will restart the app.

Navigate to the Workspace you want to enable sync for, and press the Setup Sync button at the bottom of the sidebar.

This will bring up a dropdown, press "Create Local Project"

You have now enabled sync for your Workspace. See the documentation below for how to push changes, and share the workspace with a team.

Creating Snapshots

Snapshots represent all data in a workspace (requests, folders, environments) at a specific point in time. Besides the data within the workspace, a snapshot also contains the author who created it, the time it was created, and a message from the author describing the changes.

Creating a snapshot requires two actions. (1) Describing the changes contained within the snapshot and (2) Selecting which changes to include.

Writing a Snapshot Message

Snapshot messages should describe the included changes in as much detail as possible, as this description will help identify the snapshot if you ever need to revert back to it.

Adding Changes to a Snapshot

Changes made to a workspace can be added on a granular level. Modifications and deletions to existing requests, folders, etc (AKA objects) will appear under  Modified Objects, while new additions will appear under Unversioned Objects and are unselected by default.

Sharing Snapshots

Once a snapshot is created, it can be shared to your Insomnia account or team. There are two ways to push snapshots:

  1. Use the Create and Push option when creating the snapshot
  2. Push unsynced snapshots from within the main sync menu

If there are new snapshots available that do not yet exist on your device (eg. from a team these will be available to pull down from within the sync menu.

Working with Branches

All snapshots created for Sync are stored a branch. Branches are identified by name and each one maintains a list of snapshots that have been created for it (ie. its history). Branches can be created or deleted at any time, shared with team members, and even merged together.

Branches can be useful for many reasons, but the two main use cases are the following:

  • Separating personal work from other team members
  • Working on experimental changes that may or may not exist long-term

Branches are managed within the branches dialog. Here, you can create local branches, merge branches, and fetch remote branches.

Sharing a Workspace

Workspaces can be shared with a team via the main sync menu.

This will give all members of the team access to the workspace. Once given access, team members will see shared workspaces appear in the app's main dropdown:

Reverting to a Previous Snapshot

At any time, it is possible to revert the current workspace to a previous snapshot.

Note: Restoring a snapshot will not modify the branch's history. Any changes made by the restore will need to be snapshotted if desired.