DUECA/DUSIME
Some hints for using git with dueca-gproject

Introduction

The files for a DUECA project are in most cases arranged in a specific structure, so that standard build tools supplied with DUECA can compile and link the code, and (distributed) simulations can easily be set-up and run. The structure of these projects, and the use of the dueca-gproject script to create and update such a structure, is described in a [chapter on application development](appdevelg). To keep track of changes in a project, the git version control system is used by dueca-gproject. In the development work on a project, the developer will use a few dueca-gproject commands that interact with the version control system, for further version control interaction, git will be directly used. This chapter gives some recipes for managing the version control of a DUECA project.

Git interaction through dueca-gproject

Only a few of the git manipulations are done through the dueca-gproject script itself, notably:

For all other operations, the user is expected to directly use the git version control system itself. This is possible because the work done by a developer will be on the code of the cloned project, which can be completely controlled by the git version control system.

Branches, repositories, development tree

Git is a very powerful tool for version control, having a lot of flexibity in its set-up. This can make using git for version control daunting at first. As a developer, you interact with a number of different copies of your file:

Each repository can have several branches; a branch is usually used to separate different paths in the development of software. The main branch is commonly called "master".

There are some git steps to take to keep all these software versions aligned, first we discuss the interaction between your local repository and the files in your project tree:

Note that this is by no means complete, and there is a wealth of better git documentation available to properly learn git, however, we'll make do with these basics for now.

Now for the communication between your local repository, and the remote repositories (and implicitly also with your local version of the remote repositories).

Suppose you created a new branch deploy-on-simona, for recording all your actions for deployment on the SIMONA Research Simulator. You would want to have all that work also on the remote repository. After doing your commits of this work, use the following:

git push -u origin

With origin the shorthand name for the remote repository. This will create the deploy-on-simona branch on the remote repository, link your local deploy-on-simona with the origin/deploy-on-simona, and transfer the commits to the remote server. Note that the link between the branches is essential to make your life easier; git now knows that any pushes and pulls (see below), from your local branch use this remote branch.

You would have typically started this deployment on the SRS on one of the computers, and created the branch there. You now need these developments on the other computers in SIMONA as well.

On the next computer, you need this software and branch as well. If you did not yet have the project there, use:

dueca-gproject clone \
    --remote git@gitlab.tudelft.nl:<repository>/MyProject.git \
    --version deploy-on-simona

If the project is already there, use git, from the project folder:

git fetch origin

This will retrieve the latest changes from the remote repository. Git will tell you that there is a new branch since you last compared your copy and the remote repository, now ensure that you also have this branch in your checked-out folder:

git checkout --track origin/deploy-on-simona

Now you have a local branch checked out, and linked to the branch on the remote repository. Any pushes will again end up on the remote branch.

It is important to keep these changes synchronized, so commit and push after completing edits, and pull before starting your work.

Pull versus fetch and merge

A git fetch will only affect your copy of a remote repository. Your checked out files, and your local branches, will remain the same. To bring your local branches and checked-out copy in line with the remote, you would need to combine those changes, typically with a git merge, or with a git rebase; from your checked-out local branch, and using the previous example:

git merge origin/deploy-on-simona

Since this set of operations is practically always needed when you continue work, this is combined in the git pull command. Note that by default a git pull works for the currently checked-out branch; after switching branches, it does not hurt to run a git pull.

Development scenarios

New student project

Note that starting with a completely new project is rare, but it happens. Steps:

Branching of an existing project

When you are continuing with an existing project, you can create a branch in that project and work on that branch. This is useful if after your work, your changes can be fed back into the existing project, e.g., to implement a new experiment with an existing project, or add a particular module.

The remainder of the steps are common with the previous case.

Archiving a (student) project

The git@g.nosp@m.itla.nosp@m.b.tud.nosp@m.elft.nosp@m..nl:ae-cs-dueca-archive folder is intended for keeping completed DUECA projects. To archive a project there, or anywhere else, take the following steps: