How Qri Dataset Version Control Works
Qri datasets have version control built-in. Any change to a dataset's components, large or small, constitutes a new immutable version of the dataset, but doesn't remove or alter previous versions. Versions live in a chronology, or history, and older versions can be quickly referenced and used for comparison to other versions.
Real version control means users don't need to rely on timestamps, server logs, or other artifacts to figure out what version of a dataset they are dealing with.
Likewise, two Qri users in different locations can know with certainty that they are each working with the exact same dataset.
Where Versions Come From
Versions can be created when:
- Qri.cloud runs a user's automated workflow
- A Qri.cloud user makes a manual change via the UI
- A Qri CLI user runs the
qri save
command and passes in new information for one or morecomponents
- A Qri CLI runs a transform script locally, and the code generates a different version of one more components
Commit messages
Just like with git, each version is accompanied by a message meant to describe the changes between a new version and the previous one. These can be written manually or automated. In the absence of a commit message provided by the user or set in a transform script, Qri will add a machine-generated message based on the changes detected in the new version.
Version History
Just like a git repository, a Qri Dataset has a history of commits associated with it. We refer to the latest version as HEAD
, and HEAD
is implied when referencing a dataset.
In Qri.cloud, you can inspect each dataset's version history in the History panel.
With Qri CLI, you can inspect a dataset's version history with the qri log
command.
Referencing Older Versions
Older versions of a dataset can be referenced using their hash, with the following syntax:
{username}/{datasetname}@ipfs/{versionhash}
For example,
b5/[email protected]/ipfs/QmejvEPop4D7YUadeGqYWmZxHhLc4JBUCzJJHWMzdcMe2y
references a specific version of the dataset b5/comics
Older versions of datasets have the same component structure, so you can reference body
, meta
, the same way you would with the HEAD
version.
Change is Good, Change is Required
If you attempt to create a new version of a dataset, but none of the components have changed, Qri will reject the commit because, well, it's not really a new version unless something has changed!