Git Workflow

This page gives a concise overview of the Git commands used in the MNE-CPP development workflow. For a deeper introduction, see this Git tutorial video. For the full contribution process — from forking to pull request — see the Contribution Guide.

Branch Model

MNE-CPP uses a Main – Staging – Feature branch model:

Branch	Purpose
main	Stable / release-ready code. Updated only from staging.
staging	Active development integration branch. Feature branches merge here.
feature/*	Short-lived branches for individual changes (bug fixes, features, docs).

See the Release Guide for a detailed description of the branch model and release process.

Initial Setup

As described in the Build from Source guide, start by cloning your fork and adding the upstream remote:

git clone https://github.com/<YourGitUserName>/mne-cpp.git
git remote add upstream https://github.com/mne-tools/mne-cpp.git
git fetch --all
git rebase upstream/staging

Daily Workflow

The general workflow is covered by the following steps:

• Create a new feature branch from staging:

git checkout -b my-feature upstream/staging

• Get the latest changes and rebase:

git fetch upstream
git rebase upstream/staging

• Solve merge conflicts, if they occur.

• Make your changes and check the status:

git status

• Add unstaged changes (shown in red) to prepare the next commit:

git add <changedFileName>
# or add all changes:
git add --all

• Commit the staged files (shown in green) with a meaningful message following our commit policy:

git commit -m "FIX: meaningful commit message"
# or commit all tracked changes:
git commit --all

• If you make small changes related to the previous commit, amend them:

git commit -m "FIX: meaningful commit message" --amend

• Push your changes to origin (your fork on GitHub). Note that a force push (-f) may be necessary after a rebase:

git push origin my-feature
# or force push after rebase:
git push origin my-feature -f

• Open a pull request targeting the staging branch on the upstream repository.

Useful Commands

Command	Purpose
git log --oneline -20	Show the last 20 commits in compact form
git diff	Show unstaged changes
git diff --staged	Show staged changes
git stash / git stash pop	Temporarily shelve and restore changes
git branch -d <name>	Delete a local branch after merging
git remote -v	List configured remotes