• GitHowto

Dynare repository has now migrated from Subversion (SVN) to Git.

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
• In Git, the "trunk" is called "master"

Installing and configuring Git

Under Windows

You need to install two packages (actually the first package is enough if you are familiar with the command line):

• Git for Windows, the core command-line utilities:

  • Download and run the latest package whose name begins with "Git-...". See some config hints below.
  • In the setup window entitled "Adjusting your PATH environment", choose "Use Git bash only"
  • In the setup window entitled "Choosing the SSH executable", choose "Use (Tortoise) Plink"
  • In the setup window entitled "Choosing the line ending conventions", choose "Checkout as-is, commit as-is"

• TortoiseGit, the graphical interface, which also comes with an SSH client derived from PuTTY. Choose "TortoisePlink" as SSH client.

If you also have Cygwin installed, make sure that the git package of Cygwin is not installed, or if it is installed it is not in your system path. Otherwise it will create conflicts.

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.

Under Linux

Just install the "git" package (or "git-core" for older distributions); 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

Workflow for Dynare users

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

Under Windows

Open an explorer window to the place where you want to put your working copy, then right click in the window and select « Git clone... ». In the Url entry, enter:

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

For getting regular updates, right-click on the directory of the local copy, and click "Git sync...", then "Pull".

Under Linux

Initial setup:

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

(equivalent of SVN checkout)

This will store Dynare source code in local directory dynare.

For regular updates, go into that directory and type:

git pull

(equivalent of SVN update)

Workflow for Dynare developers

We have adopted a decentralized architecture, similar to that of Github (see there).

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

But along with that, each developer has his own public repository on the Kirikou server, on which he pushes 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 (see below).

Under Windows

Initial setup

If you don't already have an account on Kirikou, generate an SSH key for identifying yourself on Kirikou: from the "TortoiseGit" application menu, run the "PuttyGen" application. Enter a passphrase to protect your key. Save the private key on a file on your hardrive (with PPK extension). Then send the public key (given in the box titled « Public key for pasting into OpenSSH... ») to SébastienVillemot.

In return, you will get by e-mail a login on Kirikou. A personal public repository will also be created on Kirikou.

You can download a working copy of Dynare Git repository:

• From the "TortoiseGit" application menu, run "Pageant". You should now have a computer with a "hat" in the bottom right corner of your desktop. Right-click on that icon, select "Add key", and choose your private key file. Enter your passphrase.

• Open an explorer window to the place where you want to put your working copy, then right click in the window and select « Git clone... ». In the Url entry, enter:

  ssh://yourlogin@kirikou.dynare.org/srv/d_kirikou/git/dynare.git

  (replacing "yourlogin" by your real login name). Then click "Ok".

• Check that the SSH key fingerprint of Kirikou corresponds to: 5b:c9:22:3c:34:50:06:da:cf:77:15:98:e2:1c:5b:6d. If it matches, accept it: you should get a working copy of the repository in a local directory called "dynare".

Now you have a clone of the public central repository of Dynare. From the point of view of Git, this repository is called "origin".

You now need to configure the address of your personal public repository on Kirikou:

• Right click on the "dynare" directory, and in the "TortoiseGit..." menu, select "Settings"

• Go to the "Git/Remote" tab
• Add a new remote, giving it the name you want (for example "personal"), without key, and with the following URL:

  ssh://yourlogin@kirikou.dynare.org/srv/d_kirikou/git/dynare-yourlogin.git

  (replacing "yourlogin" at two places in the address)

• Right click on the "dynare" directory, and in the "TortoiseGit..." menu, select "Fetch". In the dialog box, select "personal", and then Ok.

Daily workflow

Note: you should keep Pageant always running when you are interacting with the Git server. The purpose of Pageant is to keep your SSH key and its passphrase in memory, so that you don't have to type the passphrase or specify the key every time you interact with the server.

• Download other developers' modification using "Git sync..." in the contextual menu, selecting "origin" as the remote URL, and clicking on the "Pull" button (equivalent of an SVN update)

• Add new or remove files with the "Add" and "Delete" commands of the « TortoiseGit » menu, much like SVN

• Commit all modified files with the « Git commit... » command in the contextual menu: contrary to SVN, this only commits the modifications in your local git repository (every working copy comes with its local repository, it does not send them automatically to the server)
• Send your modifications to the server using "Git sync..." in the contextual menu, selecting "personal" as the remote URL, and clicking on the "Push" button. The modifications will be sent to your personal public repository, you need to ask Sébastien, Stéphane or Michel to merge them in the central repository

For Linux users

Initial setup

If you don't already have an account on Kirikou, generate your SSH key with ssh-keygen (don't forget to protect it with a password), and send it to Sébastien Villemot. You will get your login in return.

Create your working copy with the following command:

git clone ssh://yourlogin@kirikou.dynare.org/srv/d_kirikou/git/dynare.git

(replace yourlogin by your real login, and verify that the SSH key fingerprint corresponds to: 5b:c9:22:3c:34:50:06:da:cf:77:15:98:e2:1c:5b:6d)

Add a remote corresponding to your personal repository:

git remote add -f personal ssh://yourlogin@kirikou.dynare.org/srv/d_kirikou/git/dynare-yourlogin.git

(replace yourlogin by your real login at two places)

Daily workflow

• Download other developers' modifications with:

  git pull

• Add and remove files with:

  git add ...
  git rm ...

• Commit all modified files with:

  git commit -a -m "Your commit message"

  (don't forget the « -a » option, unless you know what you are doing): contrary to SVN, this only commits the modifications in your local git repository (every working copy comes with its local repository, it does not send them automatically to the server
• Send your modifications to the server with:

  git push personal

  The modifications will be sent to your personal public repository, you need to ask Sébastien, Stéphane or Michel to merge them in the central repository

More 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).

There are Emacs modes for Git, see http://www.emacswiki.org/emacs/Git.