Skip to content

SPM Development with Git and GitHub

We use the Git version control system for the development of SPM. GitHub is used as the collaborative code hosting platform (with a local mirror using Gitea): the authoritative copy of the SPM repository is available at spm/spm.

We provide here instructions to interact with the SPM repository using the GitHub Desktop. This mainly concerns Windows developers – we also mention the command line equivalents when relevant. For Linux users, additional steps are required to enable SSH authentication.

Git Installation

First, please install the GitHub Desktop:

Once installed, you need to authenticate with your GitHub account. To do so, follow the online instructions:

Two-factor authentication (2FA)

Two-factor authentication (2FA) is not required yet but might be by the end of 2023. See here for instructions on how to configure 2FA on your account.

You also need to install a Git command line tool. On Windows, we recommend:

During installation, you can accept most defaults. There are three options to be careful about (“PATH environment”, “line ending conversions” and “default behavior of git pull”), and you should select the choices as below:

PATH environment line ending conversions default behavior of git pull

Git Configuration

Username and commit email address

Git commits are associated with a name and email address. GitHub then uses the email address to associate commits with your account on GitHub.com. It is therefore essential to set these before making any commit (and to set them again on all computers).

The instructions to set your commit name and email address in GitHub Desktop are available here:

Git configuration

Specify your commit name and email address in GitHub Desktop.

The command line equivalent is:

git config --global user.name "Karl Friston"
git config --global user.email "k.friston@ucl.ac.uk"

If you use another personal email for most of your repositories, make sure to set the SPM repository to specifically use your institutional email address:

git config --local user.email "k.friston@ucl.ac.uk"

This can also be done with GitHub Desktop by following these instructions.

Note

Note that you can associate multiple email addresses with a single GitHub account.

Merge Strategy

The default of git pull to reconcile divergent branches is to call git merge. Here this default is changed to call git rebase instead. This has the advantage of creating a linear history, like in a traditional SVN workflow.

git config --global pull.rebase true

This is equivalent to using git pull --rebase.

To apply this setting from GitHub Desktop, you need to open the command prompt by selecting Repository then Open in Command Prompt from the top menu and enter the above command line.

Enforcing a linear commit history

Note that the option to require a linear history has been enabled on the SPM repository. This prevents from pushing merge commits to the main branch.

Git autostash

Pull with rebase will fail if you have unstaged changes. One way around this if you’re not ready to commit your changes is to stash the changed before doing a pull (git stash) and then restore then (git stash pop) afterwards. This can be automated by using the autostash option of git rebase.

git config --global rebase.autoStash true

As before, to apply this setting from GitHub Desktop, you need to open the command prompt by selecting Repository then Open in Command Prompt from the top menu and enter the above command line.

Clone the SPM repository

Follow these instructions with the SPM repository: https://github/spm/spm

Git clone

Clone the SPM repository from its GitHub URL.

From the command line, the equivalent is:

git clone git@github.com:spm/spm.git

For Linux users, authentication will require SSH key generation.

Git Commits

After editing some files in the main branch, select the changes to include in a commit, write a commit message and push the changes to origin:

From the command line, this is obtained with:

git add spm_example.m
git commit -m "<commit message>"

Ideally, “each commit should be a perfect, atomic unit of change”. Do commit related changes, commit often but don’t commit half-done work (use branch or stash instead).

Commit Messages

Use the imperative and prefix the commit message with one of:

  • New feature
  • Enhancement
  • Bug fix
  • Documentation
  • Refactoring
  • Maintenance
  • Test

You should be able to suffix a commit message to the phrase “If applied, this code will …”.

Commit messages should begin with a short summary of the changes (up to 70 characters) followed by a blank line and the body text, i.e.:

Enhancement: replace this with that in such and such

Longer description that might contain bullet points:
* item 1
* item 2

Git Workflow

We are using a Centralised Workflow. This is also called Trunk Based Development (see this article for a discussion). Popular other workflows include GitHub Flow and Gitflow.

Git clone

git pull is used to incorporate upstream changes into the repository. The --rebase option tells Git to move all of the local commits to the tip of the main branch after synchronising it with the changes from the central repository. Extracted from the Atlassian documentation.

Pull Requests

Recommendation for pull request reviewers: When merging, we generally like squash+merge. Unless it is the rare case of a PR with carefully staged individual commits that you want in the history separately, in which case merge is acceptable, but usually prefer squash+merge.

References