GitHub Guide
The official freesurfer repository is hosted on github at https://github.com/freesurfer/freesurfer. This guide is targeted towards novice github users who wish to contribute to the source code. Users who only want to build on their local machines without contributing changes can simply clone the repository directly from the github page. For step-by-step instructions on building freesurfer, please visit the build guide.
Initial Setup
The initial setup for contributing to the freesurfer source involves forking the main github repository, which creates a local copy of the source code in your github account. This local repository can be used to submit changes to the main repository. This general setup is illustrated below, followed by a more detailed description of the steps involved:
1. Sign up for a github account if you don't already have one. Users at the Martinos Center should add their nmr.mgh.harvard.edu email to their github account. This can be done during or after account creation.
2. From your github account, fork the freesurfer repository by clicking on the fork button near the top right-hand of the page. This creates a copy of the code base under your account on the github server.
3. On your local development machine, make a clone of your forked freesurfer repository:
git clone git@github.com:<git_username>/freesurfer.git
Note: If you are seeing a "Permission denied (publickey) fatal: Could not read from remote repository" error when running the git clone command above, it means you have to add your ssh key to your github profile.
4. Add the main freesurfer repository as a remote to the local clone you already have on your local disk, and set it as the upstream remote. This way, you can pull updates from the main source code into your local repository.
cd freesurfer git remote add upstream git://github.com/freesurfer/freesurfer.git
5. Run the command git remote -v to make sure you have the proper setup. The output should look something like this:
origin git@github.com:ahoopes/freesurfer.git (fetch) origin git@github.com:ahoopes/freesurfer.git (push) upstream git@github.com:freesurfer/freesurfer.git (fetch) upstream git@github.com:freesurfer/freesurfer.git (push)
Committing Changes
To contribute the freesurfer code base, users should follow the work-flow described below:
1. When you start to make changes, the first thing to do is to make sure you are in the dev branch (with git branch) and and check that everything is up to date with the upstream repo:
git pull upstream dev
2. Now create a new branch off of dev to hold your work, and start making changes:
git checkout -b nf-feature
3. When you're done making changes, commit the files to your local branch and push the branch to origin (your personal github fork):
git add <modified files> git commit -m "commit message" git push origin nf-feature
4. Finally, go to the freesurfer github page, and click pull request to send your changes to the maintainers for review. Make sure you are submitting your newly created branch into the freesurfer/dev branch. You can continue to commit new changes to this branch and push to your remote - github automatically updates your previously opened pull request.
5. Once you have submitted your pull request for your new feature, it is best practice to switch back into the dev branch and update from the upstream repository. You are then free to start the process anew (i.e. create a new branch, commit changes, submit pull request):
git checkout dev git pull upstream dev
6. Once your pull request is accepted, feel free to delete the branch you created:
git branch -D nf-feature
Frequently Asked Questions
Q: I'm seeing an "X11 forwarding request failed" warning when communicating with github.
A: This is caused by a global ssh setting in /etc/ssh/ssh_config. To prevent these forwarding requests to github servers, add the following lines to your ~/.ssh/config:
Host *github.com
ForwardX11 noQ: The github page for my fork of freesurfer/freesurfer says "This branch is 3 commits behind freesurfer:dev". How do I update my fork?
A: A fork will always trail the upstream, so it's very common to be behind in commits, and it's not a problem at all. However, if you'd like to update your fork, do this:
git checkout dev git pull upstream dev git push origin dev
Q: I have a branch, named my-branch, that I haven't worked on in a while. After I run git checkout my-branch to ensure that I'm working on that branch, how do I found out which files I modified previously?
A: git status -s will tell you the files that have changed since the last commit, git diff <filename> will show the changes for a specific file.