Git Sync
Summary¶
This page describes how sync with Git repositories works in Papeeria.
Supported plans and git repositories
Git sync works on all pricing plans, with some restrictions on free plan. With some caveats, any Git repository is supported, including custom installations, provided that they are accessible externally. Read more about possible restrictions
Premium feature
Access to private Git repositories is available on premium plan only.
Git pane¶
When you create a new project you have an option of pulling it from git repository. Projects created this way become git-enabled and can be synced with the repository when needed.
Currently only new projects can be git-enabled. It is not possible to link existing Papeeria project to git repository at the moment.
When project is git-enabled, all Git operations are accessible from the Git section of Version Control pane.
Sync branch¶
There are no restrictions on the branch which is synced with a Git-enabled project. User may choose any existing branch, create a new one and even switch between branches if necessary. The branch which is currently chosen to sync with Papeeria project is referred as papeeria-branch in these docs.
Latest sync point¶
After successful sync, no matter if it was pull-only or pull and push, we record the revision hash we synced with, referred in these docs as sync-point. It is shown in the Git pane, along with the information how long ago the sync was done.
Common use cases¶
Sections below give an overview of the most common scenarios of using Git with Papeeria. All scenarios start with clicking Sync now button in Git pane which opens Sync dialog.
Use Case 1: text changes only in Papeeria¶
If you edit text exclusively in Papeeria and never push anything to papeeria-branch from other sources then you only need to push your changes from Papeeria into Git. Check Push changes from Papeeria in the Sync dialog and specify your name, email and commit message for the purposes of version control history; we recommend to make them meaningful. Clicking Sync in the dialog will do the sync and if everything is fine you'll see the commit in the repository in a few moments.
Who can do push
Any user who has write access permissions to Papeeria project and write access permissions to the linked git repository can do push. However, SSH keys are personal, so it is necessary to authorize key of every user who needs write access to the repository.
Use Case 2: text never changes in Papeeria¶
You may edit the sources in other editors, commit using your favorite git tools and use Papeeria for compiling purposes only. In this use case you don't need to push changes from Papeeria, so leave only Pull changes from git checked when you run sync.
Who can do pull
Any user who has write access permissions to Papeeria project and read access permissions to the linked git repository can do pull. Public repositories with HTTPS access do not need any additional setup, however, for private repositories please keep in mind that SSH keys are personal, so it is necessary to authorize key of every user who needs read access to the repository.
Use Case 3: text changes both in Papeeria and in Git¶
If you both changed text in Papeeria and commited changes with your favorite text editor and git tools to papeeria-branch in the repository then you need to do both pull and push. We pull papeeria-branch first and try to merge remote changes with Papeeria changes. If merge completes successfully then we update Papeeria project. If merge fails then we leave Papeeria project intact, and you need to resolve merge conflicts manually. After successful merge you can push Papeeria changes, if any, to the same papeeria-branch. You can skip this step but we recommend to sync regularly.