Version control

Ensuring you can always review your previous work.

What is version control?

Every notebook can have multiple versions, which are snapshots of the notebook at a point in time. Versions cannot be edited or deleted, so are very useful in understanding the history of a notebook. You can create a version manually, and versions are also automatically created as you edit a notebook.

When you create a notebook, it begins in draft mode. This means only you can see and edit the notebook.

When you want to share, you will need to publish the notebook to the project. When publishing:

  • The notebook becomes visible to all project members.

  • A new version of the notebook is saved - you will be prompted to give this version a name.

  • The notebook can no longer be edited.

Forking

Once you, or anyone with edit permissions, wants to make changes to a published notebook, they will first need to fork it. This creates a new copy of the notebook but in draft mode, which can be edited freely.

Publish vs merge

Once you are done making edits to a forked notebook you will have the option to merge or publish your new draft.

  • Merging will append your changes to the parent notebook that was forked from. Like publishing, these changes will be saved in a new version of the parent notebook.

  • Publishing will create a brand new notebook chain with its own version history, unrelated to the original notebook.

Access the merge/publish options from within a draft notebook.

Viewing versions

The version history of a notebook can be viewed if you are an editor or above of the parent project. To access it, first click 'View code', then access it from the Document tab:

Access the version history

The version history bar displays all versions of the notebook, and highlights the one you are currently viewing.

  • If the notebook is in draft mode, you can manually save a new version by clicking the plus icon.

  • If the notebook is published, the only way to add new versions is by forking and merging.

  • Any version can be restored by clicking the menu icon in each version.

  • When publishing and merging, all versions of the draft notebook will be appended to the parent notebook.

  • All versions have a unique URL - you can copy it from the address bar while viewing a version, or copy it to the clipboard by selecting the 'Copy link' option.

Example

To demonstrate the concepts above, the diagram below illustrates what happens under the hood when editing, publishing, forking, and merging notebooks.