-
Notifications
You must be signed in to change notification settings - Fork 4
Initial setup
The Versions plugin uses Git under the hood to store and archive versions. It is very important to follow all of these steps in the correct order, otherwise the plugin will not work. You will only need to follow the steps once per Kirby site. Afterwards the plugin will manage the Git repository automatically.
The terminal commands that are listed below should preferrably be run directly on the server for best results.
Note: The following commands assume that the content of your Kirby site is not already in a Git repository. Please note that it is not recommended to use the Versions plugin with a Git repository that also includes other site files as this will prevent you from deploying code changes without breaking the content versions. You should therefore create a new Git repository just for the content directory of your Kirby site.
Before you set up the Versions plugin, you need to think about which files should be managed by it and which files should be ignored.
You need to define all files that you don't want managed by the plugin (e.g. dynamic content created by forms on the site) by listing the file paths in the content/.gitignore file. Create the file if it doesn't exist. You can read more about the .gitignore format in the Git documentation.
Important: Be careful about ignoring .lock files. These are created by Kirby's content locking feature and tell the Versions plugin that someone is still editing pages, which will prevent the plugin from creating and switching versions. Ignoring these files using Git will disable the unsaved changes warning of the Versions plugin. You can use the plugin with the warning disabled, but please note that switching versions while someone still has unsaved changes may lead to lost changes (e.g. when switching to a version where the page that was being edited didn't exist). If that's fine for your use case, feel free to ignore .lock files.
# Ensure you are in the `content` directory of your Kirby site
cd /var/www/your-site/content
# Generate a name for the Git tag based on the current date
tagName="$(date +%Y%m%d_initial)"
# Initialize a new Git repository and add all files to it
git init
git add -AImportant: Please now verify using the search function of your terminal (Ctrl/Cmd F) that no .lock file was added, which would break the plugin's behavior later. If there is a .lock file listed in the output, please save or discard the changes and run git add -A again to tell Git to remove the .lock file from the index. The initial version must not have unsaved changes.
# Commit the current state as the initial version
git commit -m "Initial version"
git tag $tagName -am "Initial version"
# Switch to the new tag
git checkout $tagName
# Delete the `master` branch as the branch will not be updated;
# WARNING: Only do this if you have created the content repository
# just for the Versions plugin, otherwise keep the `master` branch
git branch -d masterNote: The $tagName variable was set at the beginning. If you run all commands in the same terminal session, you can copy-paste them 1:1 and the value of $tagName will be inserted automatically by your shell.
Congratulations, the Versions plugin should now be ready to go! Please open the Versions view in the Kirby Panel and check if it display your initial version.
If you get a Git error, you may need to configure the path to your Git binary. On the linked page you can also find details on other configuration settings you can tweak.
If you want, you can set up the following features: