Version Control
===============

.. _Nucleus_Version_Control:

Checkpoints
------------------------

:guilabel:`Nucleus 2021.2.0`

Nucleus supports historical versions of files. These versions are called "Checkpoints". A Checkpoint represents the contents of a file at a certain point in time and cannot be modified once it has been created. It is immutable.

The concept of "Branches" is also being supported although at this writing only one branch is supported - called the "default" branch. This feature is expected to grow into supporting many branches.

================  ===============================================  =============
Term              Meaning                                          Can be edited
================  ===============================================  =============
Branch            An alternate version of a file.                  Yes
Head Revision     The most recent version of a file on a branch.   Yes
Checkpoint        A historical version of a file.                  No
================  ===============================================  =============

.. _Nucleus_Version_Control_URL_Schema:

URL Schema
--------------------------

With Version Control, Nucleus URLs are using query parameters indicate branch and checkpoint. URLs without query parameters continues to work because they are assumed to reference the head revision of files on the "default" branch.

The most explicit URL for a checkpoint file states the query parameters by name and value, for example:

.. code-block:: bash
    
    omniverse://my-nucleus.company.com/Assets/car.usd?branch=default&checkpoint=5

Abbreviated versions of checkpoint URLs are also supported:

.. code-block:: bash

    omniverse://my-nucleus.company.com/Assets/car.usd?default&5
    omniverse://my-nucleus.company.com/Assets/car.usd?&5 ("default" branch is assumed)

The most explicit URL for a branch file: 

.. code-block:: bash
    
    omniverse://my-nucleus.company.com/Assets/car.usd?branch=default

Abbreviated versions of branch URLs:

.. code-block:: bash

    omniverse://my-nucleus.company.com/Assets/car.usd?default
    omniverse://my-nucleus.company.com/Assets/car.usd ("default" branch is assumed)

How are Checkpoints Created
---------------------------

Checkpoints are created by various Omniverse clients when files are created, saved, exported etc.

To find out more about version control in clients:

* `App Extensions <../../../extensions/version-control.html>`__
* `Connectors <../../../connect/version-control.html>`__

.. _Nucleus_Version_Control_Feature_Flag:

Turn Feature ON/OFF
---------------------------

Workstation
###########

Nucleus supports turning version control ON/OFF as a feature.

Please note that turning the version control feature OFF on a server that is already managing files is risky. For example, the server cannot convert existing checkpoints into "regular files" when the feature is turned off.

Run Nucleus with Checkpoints disabled: we recommend disabling the feature immediately after installation:

1. Install Nucleus Workstation.
2. Open ``[launcher installation directory]/library/nucleus-workstation-2021.1.0-rc.4/Nucleus/omni.verifier.app.config.json`` in a text editor.
3. Set ``"versioning": "%OMNI_VERSIONING%?:false"``
4. Save the file.
5. `Stop` and `Start` the `Nucleus` server from the :ref:`System Monitor <RST_System_Monitor_General>` to apply the settings.

Toggle Checkpoints ON or OFF.

1. Open ``[launcher installation directory]/library/nucleus-workstation-2021.1.0-rc.4/Nucleus/omni.verifier.app.config.json`` in a text editor.
2. Set ``"versioning": "%OMNI_VERSIONING%?:true"`` or ``"versioning": "%OMNI_VERSIONING%?:false"``
3. Save the file.
4. `Stop` and `Start` the `Nucleus` server from the :ref:`System Monitor <RST_System_Monitor_General>` to apply the settings.