• GitHowto

We are going to migrate the current Subversion (SVN) repository to another source control management (SCM) software, called Git. Migration is scheduled for January 29th, 2010.

The oustanding differences between Git and SVN are:

• Git is a decentralized SCM software: Git support an arbitrary number of repositories for a given project, and has powerful tools to synchronize and merge between these repositories
• Branching and merging is very easy in Git
• Every local working copy contains a full repository with all the history of the project: in particular, this allows user to make commits or to examine history on their local private repository when they are offline; they will later "push" their commits to a public repository when they come back online
• In Git, a revision is a photography of a full directory tree; on the contrary, in SVN, revisions are attached to individual files, not to sets of files
• The internal representation of history in Git is a directed acyclic graph (DAG): the creation of a branch occurs when a given commit has two children commit; conversely, a merge is represented by a commit which has two parents
• Git is much faster than SVN

Installing Git

On Debian or Ubuntu

Just install the "git-core" package; you may also be interested in the "git-doc" package.

Then you need to give your identity to Git (needed for identifying the commits):

$ git config --global user.name "Your Name Comes Here"
$ git config --global user.email you@yourdomain.example.com

On Windows (without Cygwin)

You need to install two packages:

• MSysGit, the core command-line utilities (use the default settings)

• TortoiseGit, the graphical interface, which also comes with an SSH client derived from PuTTY (also use the default settings)

Then you need to give your identity to Git (needed for identifying the commits): in the "TortoiseGit" menu, run the "Settings" application, and then configure your identity (fullname and e-mail address) in the "Git/Config" submenu.

On Windows (with Cygwin)

Install the "git" package.

Then you need to give your identity to Git (needed for identifying the commits):

$ git config --global user.name "Your Name Comes Here"
$ git config --global user.email you@yourdomain.example.com

Learning about Git

You can look at the documentation available in the documentation section of the Git website.

Start reading the tutorial. Also read Git for computer scientists which explains how Git internally stores data and history: this makes the understanding of commands much easier (in particular for branching/merging).

Quick start for Dynare users

For users who want to track daily development of Dynare, only two commands are needed (very much like with Subversion).

Initial setup:

git clone http://www.dynare.org/git/dynare.git

(equivalent of SVN checkout)

This will store Dynare source code in directory dynare.git.

For regular updates, go into that directory and type:

git pull

(equivalent of SVN update)

Git with Emacs

See http://www.emacswiki.org/emacs/Git

For Dynare developers

We will adopt a decentralized architecture.

Of course, there will still be a central public repository.

But along with that, each developer will have his own public repository on the Kirikou server, on which he will push his modifications.

Once these modifications are ready to be integrated in the official central repository (possibly after review by another developer), they will be integrated in the central repository by an integrator (Michel, Stéphane or Sébastien).

An important point to understand is that the "commit" command is different from SVN: in Git, when you commit, the change is only registered in your local repository (on your local computer). It will not be made public until you publish it on your personal public repository (located on Kirikou) with the "push" command.

To be more concrete, the workflow for a developer is the following:

• the developer downloads Dynare source from the central repository (using "git clone")
• the developer makes modifications and commits them on his local private repository (using "git commit")
• on a regular basis, since the central repository changes, the developer needs to merge those changes with his local copy (using "git pull")
• when the developer is happy with the modifications he made, he pushes them on his public individual repository on Kirikou server (using "git push"), and sends an email to one of the integrators (or to the dev mailing list)
• the integrator downloads the changes from the developer's public repository into his local private repository
• after validation, the integrator pushes the changes to the central repository

Access to the public individual repositories will be done using SSH, with public keys. Each developer should therefore install an SSH client and setup an SSH key.