Skip to content

Getting started for new developers

Jump to bottom
Ramón Casero edited this page Nov 3, 2015 · 17 revisions

Admin stuff

  • Ask Ramon to add you
  • as a contributor to the GitHub repository
  • to both mailing lists, the public ([email protected]) and the private
  • Ask support to create an account for you on the private subversion repository (called private-gerardus)
  • Any public communications should be carried on the mailing list ([email protected])

Installing git

  • Linux users: git command line client.
  • Windows users: [http://msysgit.github.io/ msysgit] (command line) or [https://tortoisegit.org/ TortoiseGit] (GUI)
  • Mac OSX users: git command line client.

Setting up name and email

From http://githowto.com/setup.

Run this with your git client:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Options for line endings in different operating system

From http://githowto.com/setup.

For Linux/Mac:

git config --global core.autocrlf input
git config --global core.safecrlf true

For Windows:

git config --global core.autocrlf true
git config --global core.safecrlf true

Downloading ("cloning") gerardus to your computer

Create directory for Gerardus code

mkdir gerardus
cd gerardus

Say that this directory is going to be under Git control (this creates a hidden .git directory)

git init

Link the directory to the gerardus repository. After this, whenever you need to refer to the URL you can use the label "gerardus"

git remote add gerardus https://github.com/rcasero/gerardus

Download ("pull") the code

git pull gerardus master

Check the status of the repository

git status

Refreshing your local copy of gerardus

To get the most up to date code, run

git pull gerardus status

Sending your code to the repository

  1. Create new files, or edit existing ones.

  2. Add an entry to the ChangeLog file explaining the commit that you are about to make. For example:

      2015-04-27  Ramon Casero  <[email protected]>
         * matlab/ItkToolbox/elastix_bspline_grid.m: (0.1.3)
         
         - Fix bug. The displacement vector was being reshaped in the wrong
         way. Now it's first reshaped to the elastix grid size, and only
         then the rows and columns are swapped.

  3. Stage the file(s) that you are going to commit together with the ChangeLog

     git add ChangeLog newfunction.m anotherfunction.m

  4. Commit the file(s), writing a meaningful log message (you can copy the one you put in the ChangeLog)

     git commit gerardus master

  5. You may want to do more commits (go back to step 2.).

  6. Once you have done all the commits you want, push your changes onto the repository

     git push gerardus master

    Note: when you push code, you may be told that the repository has changed, and you no longer have the latest version of the code. In that case, you need to pull again and let git merge the repository with your local copy before pushing.

Branching the project

Git is strongly based on "branching", which means that for significant changes, you should not just push your stuff to the master branch. Instead, what you do is the following:

If you need to create a new branch

  • "Branch" the project, i.e. make a copy of the project that you can play with. We are going to call that new branch "replace_scimat_min_by_offset"

      git branch replace_scimat_min_by_offset

  • Switch from the master branch to the new branch

      git checkout replace_scimat_min_by_offset

If you are going to use somebody else's branch

  • "Fetch" the project, i.e. update the information about the project branching

      git fetch gerardus

  • Switch from the master branch to the new branch

      git checkout replace_scimat_min_by_offset

After that

  • Now make your changes, create new files, delete others, make several commits, push your changes to the respository, etc. This could take a few days.

  • Once you are done with all your changes, switch back to the master branch

      git checkout master

  • Merge the new branch with the master branch. This will put all your new stuff into the master branch

      git merge replace_scimat_min_by_offset

  • If the merge went well, delete locally the branch you created, as it's no longer needed

      git branch -d replace_scimat_min_by_offset

  • To delete the branch on the github server, you also have to run

      git push gerardus --delete replace_scimat_min_by_offset

Downloading ("cloning") the papers directory to your computer

Basically, the papers directory is an orphan branch. This means that it lives outside of master, i.e. we are going to use a separate directory that is outside of "gerardus".

To clone it,

  • Create a directory in your computer for the papers, outside of the "gerardus" directory. Otherwise, it won't work because you'll have two separate branches overlapping.

      mkdir papers-public

  • Initialize the directory as a git directory

      cd papers-public
  git init

  • Associate the URL of the gerardus repository to the "gerardus" label

      git remote add gerardus https://github.com/rcasero/gerardus

  • Pull the papers branch

      git pull gerardus papers

  • Remember that when you commit and push in this directory, you use "papers" instead of "master" as the target branch.

Learning resources

Clone this wiki locally