🧩Git Integration

Overview

When you connect a project to a Git remote such as Github, you unlock the ability to have multiple branches of your project, to freely switch between them, and to use the Github suite of tools for managing files and automating tasks. Of course, it's also the easiest way to backup your files outside of Collimator.

Connecting to a Git Remote

At present, the only Git remote service that is supported is Github, and all users of a project will use the same Github credentials. These simplify administration of the connection to Git, but your Github administrator will need to set the shared permissions appropriately.

Github repositories are linked to Collimator Projects, very much like how repositories correspond to software projects in text-based languages. To connect to a Collimator project to Github, a project administrator will need to go to the project page in the Dashboard and click on the 'Integrations' button in the top right of the screen:

From there, click the 'New Git Remote' button:

A dialog box will be shown where you can enter a Github Personal Access Token (PAT). You can generate a new token at https://github.com/settings/tokens/new. Depending on the settings you choose when you generate the token, you may have to generate a new one when it expires.

Once you enter your PAT, you can choose a repository from your Github account. Click 'Done' and the integration is set up.

Managing Branches

The default branch that is selected when you connect to Github is 'Main', or if you only have a single branch with a different name, that one will be selected. You can see which branch is selected on the Dashboard, and you can also which branches are available in the same place:

If you want to create a new branch, simply select that option from the 'Branch' dropdown menu. A dialog will be shown where you can create the branch. Once created, it will be automatically selected, and its contents shown in the file list.

Pushing Changes

When you first connect an active project to Github, or when you've made changes to a branch, a button will be enabled on the Dashboard to 'Push Changes'.

The far right column of the file list shows which files are different from those on the remote. Possible statuses are:

• Edited – The file in Collimator is newer than the one in Github

• Out of Date – The file in Github has been changed, and the local version is out of date

• Added – The file only exists in Collimator and not in the remote repository

• No status shown – The file in Collimator and in Github are identical

In order to push your changes to Github, you simply click on 'Push changes', add a commit message, and you should be good to go:

One possible gotcha in this process is if you've changed files locally, but there have also been remote changes since your last push, this can result in a Git error. Fortunately, if you check the option at the bottom of the dialog box to 'Force push...', that should allow the push action to complete. Just please make sure you understand what you're doing when invoking this option.

You can also reset a branch to discard any changes you've made and pull the remote version, effectively 'resetting' the local branch to the state of the remote version. The option to do this is found under the dropdown button next to 'Push changes'

And of course, you can delete a branch. Deleting a branch always deletes it from Collimator, but can optionally also delete it from Github:

Deleting branches is very useful for cleaning up branches that have been checked out, but either no longer exist on Github, or that are no longer needed.

Switching Branches

A typical workflow might be to create a new branch from 'Main', make some changes, push those changes, and then create a pull request on Github for those changes to be merged back into 'Main'. If there are multiple editors in your project, there may be multiple active branches at any given time. You can review others' work, reference their changes, and so on by switching the branch you're viewing within Collimator. To do this, click on the 'Branch' dropdown list, and select the branch of interest:

This list shows all the branches that have already been pulled by someone on your project team. If you don't see the branch that you want, click 'Browse all...'. This will open a dialog that lists all the branches available in Github:

Select the one you want, and click 'Checkout branch' to pull that branch with its file versions into your project.

You—or anyone else working on your project—can switch branches as desired. When you switch to a different branch, the one you switched from is preserved, changes and all, in a cache local to Collimator. In other words, if you switch from branch A to branch B, then switch back to branch A, all of your changes and new files should still be there, just as you left them. That said, anyone with edit access to the Collimator project can edit any files on any branch that has been checked out. This gives your team the flexibility to manage branches in whatever way makes sense for you, but it also means that communication with your teammates is important if you use shared branches. When in doubt about who changed what, when, please refer to the Version History.