| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
|
#acl LcnGroup:read,write,delete,revert All:read <<TableOfContents>> This page is targeted at users who wish to contribute changes to the Freesurfer code base. Members of the public who simply want to clone the repo and build on their home machine, but dont plan on contributing changes, should consult the [[http://surfer.nmr.mgh.harvard.edu/fswiki/freesurfer_linux_developers_page|read-only git repo]]. Lastly, users who just want access to the code can clone directly from the official Freesurfer github page: https://github.com/freesurfer/freesurfer == Initial Setup == The first thing users at the Martinos Center need to do is '''prepend''' the directory {{{/usr/pubsw/packages/git-annex/current/bin}}} to their PATH so that the proper version of git is beeing used. The initial setup for contributing to the Freesurfer repository involves the user forking off the Freesurfer !GitHub repo, cloning the users fork into a local repository, then adding the Freesurfer repository as an upstream remote. This setup is illustrated below, followed by a more detailed description of the steps involved: {{attachment:github_workflow6.jpeg}} 1. Sign up for a [[https://github.com/|github]] account if you don't already have one. Users at the Martinos Center should add their <username>@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 [[https://github.com/freesurfer/freesurfer|Freesurfer project repository]] by clicking on the 'Fork' button near the top right-hand of the page. This creates a copy of the Freesurfer code base under your account on the !GitHub server. {{attachment:fork.jpeg}} 3. On your local machine, make a clone of your Freesurfer repository (the one you forked): {{{ git clone git@github.com:<git_username>/freesurfer.git }}} '''Note:''' If you are seeing an "{{{Permission denied (publickey) fatal: Could not read from remote repository.}}}" error when issuing the git clone command above, it means you have to add your ssh key to your github profile. To add your ssh key to your github profile, copy the contents of ~/.ssh/id_rsa.pub into Profile -> Settings -> SSH and GPG keys -> New SSH key. 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: {{{ cd freesurfer git remote add upstream git://github.com/freesurfer/freesurfer.git }}} 5. Type the following command to make sure you have the proper setup: {{{ git remote -v origin git@github.com:zkaufman/freesurfer.git (fetch) origin git@github.com:zkaufman/freesurfer.git (push) upstream git@github.com:freesurfer/freesurfer.git (fetch) upstream git@github.com:freesurfer/freesurfer.git (push) }}} '''Note:''' If you are seeing an "{{{X11 forwarding request failed}}}" warning when communicating with github, 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 no }}} == Committing Changes == To contribute the the Freesurfer code base, users should 1) Update their code 2) Create a new branch off the {{{dev}}} branch 3) Commit the changes and push the branch to their fork ({{{origin}}}) 4) Submit a '''Pull Request''' into {{{freesurfer/dev}}} to get those changes into the Freesurfer code base. This workflow is illustrated below, followed by a more detailed description of the steps involved: {{attachment:github_workflow5.JPG}} 1. When you start to make changes, the first thing to do is make sure you are in the dev branch and everything is up to date with the upstream repo: {{{ git branch * dev }}} {{{ git pull upstream dev }}} 2. Then create a new branch (off {{{dev}}}) to hold your work and start making changes. Ideally, use a prefix signaling the purpose of the branch: {{{ git checkout -b nf-my-feature }}} * {{{nf-}}} for new features * {{{bf-}}} for bug fixes * {{{rf-}}} for refactoring * {{{doc-}}} for documentations contributions. * {{{test-}}} for test related contributions. 3. Work on this copy on your computer using Git to do the version control. When you're done editing, commit the files to the local branch and push the branch to {{{origin}}} (your personal !GitHub account): {{{ git add <modified_files> git commit -m "Commit message" git push origin nf-my-feature }}} 4. Finally, go to the !GitHub web page of your fork of the Freesurfer repo, 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}}}. This will send an email to the committers. You can commit new changes to this branch and keep pushing to your remote -- github automagically adds them to your previously opened Pull request. {{attachment:new_pull_request.JPG}} {{attachment:compare_changes.jpeg}} 5. Once you have submitted your pull request for the {{{nf-my-feature}}}, it is best practice to switch back into {{{dev}}} and do an update. 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 }}} === Cleanup steps (Optional) === 6. Once your pull request is accepted (you should get an email), feel free to delete the branch you created: {{{ git branch -D nf-my-feature }}} == Developing == Instructions on how to further work with the Freesurfer source code, including building, testing, and adding a binary to the tree, should consult the Freesurfer Developers Guide: https://surfer.nmr.mgh.harvard.edu/fswiki/DevelopersGuide_git == Data files (optional) == A default clone of the repo will only give the user source code. Data files are stored in git annex, exist as broken symlinks by default, and need to be specially requested. To request a datafile, first add the remote repository that stores all the Freesurfer data files (you only need to this once): ## Data files represent a special case for source code repositories and generally speaking data files should not be stored in a source code repo. Rather they should be stored in a separate storage area, reserved for times when retrieval is required (e.g. updating test data, performing local installations, etc). Think of "source code" as files which are made up of text, are required for compilation, and can be easily inspected by the human eye (and diff'ed by the '''diff''' program). Think of "data files" as files stored as binary and not required for compilation. {{{ (Users outside the Center) git remote add datasrc https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/repo/annex.git git fetch datasrc (Users within the Center) git remote add datasrc file:///space/freesurfer/repo/annex.git git fetch datasrc }}} Your list of remote repositories should now look something like this: {{{ git remote -v datasrc https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/repo/annex.git (fetch) datasrc https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/repo/annex.git (push) origin git@github.com:zkaufman/freesurfer.git (fetch) origin git@github.com:zkaufman/freesurfer.git (push) upstream git@github.com:freesurfer/freesurfer.git (fetch) upstream git@github.com:freesurfer/freesurfer.git (push) }}} Now you can just specifically request whatever datafile you need: {{{ git annex get GEMS2/Testing/test.txt.gz ######################################################################## 100.0% (checksum...) ok (recording state in git...) }}} Or just get everything (Not recommended): {{{ git annex get . }}} For more information on how to work with the data files and git annex in general, see the following page: https://surfer.nmr.mgh.harvard.edu/fswiki/GitAnnex == FAQ == * '''Q:''' The github.com 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, but to update your fork, assuming you have cloned it on your local machine, and have confirmed through {{{git remote -v}}} that your upstream is correct (per instructions above), then do this: {{{ git checkout dev git fetch upstream git merge upstream/dev git push origin git pull upstream dev }}} <<BR>> * '''Q:''' I have a branch, named mybranch, that I haven't worked on in a while. After I run 'git checkout mybranch' to ensure I am working in that branch, how do i found out which files I modified in the past? * '''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, {{{gitk}}} is a helpful gui. * '''A2:''' {{{git diff --stat master...}}} will show which files were modified in this branch (assuming that it was created on top of the master branch). Compare to {{{git diff --stat master..}}} (two periods, not three) which will show which files differ from current state of the master branch (which might have progressed forward and was not merged into mybranch in its last "version") <<BR>> * '''Q:''' How can I look at code from older commits? * '''A:''' The short answer is to look at the git log (of commit history) and identify the commit hash you want, then git checkout that hash (and optionally give it a readable name). Here's a step-by-step example, going back to Andre's first commit in 2001: {{{ mkdir oldcode cd oldcode git clone https://github.com/freesurfer/freesurfer.git cd freesurfer git log > git.log }}} Now look at the git.log file and search for a point in time where you want the code, ex. andre's first commit, and copy the hash string (the long number next to 'commit'). Now we're going to 'get' that version with the following commands, which will modify all the files in your existing tree to match the code from that commit. {{{ git checkout b66f3061610c973ee1e1cab7325a913a481d5cb8 git checkout -b code2001 }}} ## This page is provided for !Freeurfer developers to assist in the CVS -> git transition. ##This page is not meant to be a comprehensive guide for using git. Git is a feature loaded version control system which at times can be a bit of a hurdle to learn. However, when used in its simplest form, it can be very similar to most all other version control systems, including CVS. Below are many of the basic CVS commands used by !FreeSurfer developers the git equivalent of that command. ##The following sites are great resources for those who want to dig deeper and and learn more about git and its features. ## * [[https://www.atlassian.com/git/tutorials/what-is-git|Atlassian]] ## * [[https://git-scm.com/doc|git-scm]] |
- Diff for "Freesurfer_github"