Skip to content

Getting started for new developers

Jump to bottom
Ramón Casero edited this page Jul 11, 2016 · 17 revisions

Admin stuff

Installing git

  • Linux users: git command line client.
  • Windows users: Git for Windows (command line and GUI) or TortoiseGit (GUI)
  • Mac OSX users: git command line client.

Setting up name and email

You need to do this once per computer.

git config --global user.name "Your Name"
git config --global user.email "your_email@whatever.com"

Dealing with end-of-line characters automatically

Different operating systems (Linux, Windows) deal with end-of-line differently. To make your system work correctly:

  • For Linux

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

  • For Windows

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

Get the whole source code to your computer

Run the following code replacing GITHUB_USERNAME by your github username

mkdir gerardus
cd gerardus
git init
git remote add origin https://GITHUB_USERNAME@github.com/vigente/gerardus
git pull origin master

Getting updates from the repository

git pull origin

Committing and pushing your code to the repository

With git, first you commit your changes locally, and then you push the commit to the repository. You can commit multiple times before a push.

  1. Do some work. Add 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  <rcasero@gmail.com>
         * 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 (copy the one you put in the ChangeLog)

     git commit origin 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 origin 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

If you make a small change, you can work directly in master. But if you are going to be making changes over several days, and you don't want to break the project, you should create and work in a separate branch. This could be your own new branch, or maybe you are going to be working in somebody else's branch:

If it's your own new branch

  • "Branch" the project, i.e. make a copy of the project that you can play with. For example, let's call the 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 origin

  • 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, commits and pushes, 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 origin --delete replace_scimat_min_by_offset

Public papers

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
  cd papers-public
  git init
  git remote add origin https://github.com/vigente/gerardus
  git pull origin 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