Using Git within Noteable
Noteable makes it easy for you to work with data and files from a remote git repo.
Noteable allows you to create a new project from a clone of a remote Git repository. In this project, you may work within Noteable on all the data and files from that remote git repo.
Currently, Noteable supports integration with GitHub and GitLab. Contact us at [email protected] if the Git integration you’d like to use is not yet available.
To create a new Noteable project based on a clone of a remote Git repo:
- Click Create New Project
- Give the project a name and (optionally) a description.
- Select the “Clone from GitHub” checkbox to have the new project be a clone of an existing remote GitHub repo.
- Enter the URL for the GitHub Repository.
- Enter the branch you’d use.
- (Optional) Enter your personal access token.
After you create the project, you will see all of the files and folders contained in the remote Git repository at the time of the project’s creation. You can open, modify, delete, or create new files within Noteable.
Once a git project is cloned into Noteable, Noteable will begin tracking any changes made to the files within the project using a micro-commit branch. The micro-commit branch holds many smaller commits for each time the server persists those to disk. Any changes made to notebooks or files are automatically tracked both in git and in blob storage.
Files within the project that have been modified, deleted, or added are identified in the sidebar with a git affordance. The total number of files modified, deleted, or added will be shown at the top of the project file tree. Clicking on that will open a new panel in the sidebar which will detail all of the locally modified files. These changes are exclusive to Noteable’s environment until they are synchronized with the upstream repository.
As a Noteable Project, a Project based on a remote git repository provides Noteable’s rich collaboration experience. You can invite collaborators to the project or specific files. Collaborators can work with you on notebook files, comment, and exchange ideas.
The Project’s creator has responsibility for updating the remote repository that they cloned. If collaborators also wish to contribute their changes directly to the remote repository, they should create a personal clone of the remote repository as a Noteable Git-based Project.
To manage your git project, such as updating the personal access token used for authentication, click the “Manage Git Project” button on the Project page.
Noteable pulls from the remote branch that was selected during the project creation
To pull in changes from the remote repo, enter the git menu from the notebook sidebar. Click
Pull Remote and pull in the remote changes. Performing a pull action brings in the latest git history which will be immediately reflected in the project files you see within Noteable for all users in the project.Noteable performs automatic conflict resolution by optimistically resolving in favor of the user’s local changes (more on that below).
When Noteable encounters a conflict upon pulling from the remote repo, we will optimistically resolve in favor of the user’s local changes.
When there are conflicts of notebook files, Noteable will resolve in favor of the users local changes but will automatically create a version of the notebook that was the remote side of the conflict. Users wishing to review the remote side of the conflict can open the notebook version sidebar and view the most recent version named Remote Version with the timestamp of the sync action.
If desired, the user can “restore” that version, which will overwrite the current/live version of the notebook. Note that in doing so, the file will be shown as modified locally, and would need to be sync’d back to the original remote repo to see the changes in the git repo.
For conflicts in non-Notebook files, Noteable will still resolve in favor of the user’s local changes. However there won’t be a version to look at to see the remote side of the conflict, but instead the user can use Git commands like git diff to review the git history and perform any subsequent changes.
Additional changes to the git history via
!git commands within the notebook will be respected and applied to the upstream on next sync. However, a few git commands are disabled when using a git based project: namely direct branch manipulation requests such as branch checkouts.Sync is both a pull and a push, with a pull being performed first along with any conflict resolution as described above.
When performing a sync, all local changes in the micro-commits and will be pushed.
To be able to sync with a remote repository, the user must have push access to the branch. If after making changes the user tries to push those changes to a protected branch, you can use cell-level git commands described here to push those changes to a different remote branch manually.
Like any other git project, sync’s from noteable are added to the git history and can be later reviewed or reverted using standard git practices.
To avoid having very large notebook files, Noteable instead uses an output reference within each cell. When notebooks are sync’d back to Github you can see that reference in the cell metadata, but the output is left within Noteable. Note that if you download a notebook using the file-> download menu, the notebook will contain all of the outputs.
Currently, users will see all of the microcommits in their git history when they perform a sync of Noteable local changes to their remote repo. Users who prefer to have the history squashed could use a pull request from that branch to their main branch in order to do the squashes.
Additionally, if desiring to do standard code reviews using Git workflows, it’s recommended to sync to a development branch and review through standard pull request workflows. Since outputs aren’t included in the notebook file, the diffs should be more manageable.
Last modified 5mo ago