Magpie supports revision controlling notebooks through integration with a remote Git repository, such as GitHub or Bitbucket. This can be extremely helpful for effectively managing changes to notes among multiple users within Magpie.
After enabling revision control, Magpie users will be able to use the notebook exactly as they were before, but they will also have access to the revision control features described below. Uncommitted changes are still saved in backup storage by Magpie.
Configuration
In order to get revision control set up, an organization must enter config info through the Revision Control tab in the Magpie App. If you are an admin, navigate to this page by selecting the drop down in the top right corner next to your username and clicking Revision Control.
Click the Add or Edit buttons to create a new configuration. When configuring a remote repository, keep in mind that anyone with access to the underlying repository will have access to view all of the notes and the data that gets displayed in those notes. Best practice is that only Magpie admins or a restricted system account have access to the remote repository.
The following fields will need to be configured:
Remote URL - The URL to the remote Git repository that will be used to store notebooks. (e.g.,
https://github.com/my-org/magpie-notebooks.git).Username - The GitHub or BitBucket username to authenticate from Magpie.
Access Token - The Access Token obtained through GitHub or BitBucket for Magpie to securely store and use to authenticate to the remote repository.
Once the configuration has been submitted, the remote repository and existing notebook storage will be synchronized. This could take a few minutes depending on the number of notes in your Magpie instance. Submitting a new configuration results in the loss of the existing configuration even on failure.
Using Revision Control in Magpie
The revision control toolbar allows users to commit, compare, and revert to previous commits, exactly like a Git repository. Magpie does not support branching. As an alternative to branching, users can clone notes.
For users that have not used Git previously, the revision control toolbar may be slightly less intuitive. Instructions for how to use each button in the toolbar are below.
Commit
This feature is used to checkpoint the code that you have written in your notebook. After clicking the version control button you will be prompted to enter a commit message. The commit message should be a brief overview of the changes that you have made since the last commit.
Compare Revisions
After clicking on the compare revisions button, the view will be changed to show a comparator for each paragraph in the notebook. This will allow users to see what has been changed between commits. It also allows users to compare commits against their current working copy (Head).
Set Revision
To view the commit history click on the drop down next to the compare revisions button. This will display a list of the previous commits. Click one of the commits in the drop down to open a read only version of the notebook at the time it was committed.
After selecting a commit from the drop down, the user is able use the Set Revision button. This feature will revert the notebook to the selected commit. After reverting a note, any uncommitted changes will be lost. Best practice is to commit the current Head prior to reverting.
Support
For questions about configuring or using revision control in Magpie, reach out to support@silect.is.