version 0.5.0
Git usage for Notus developers

Getting started

Git configuration

Follow these instructions to setup essential information on your machine.

  1. User information.

    Your name and your email address must be joined to your commits. These commands set values to use (change "First Last" by your first and last names and change first.last@domaine.tld by your e-mail address):

    git config --global user.name "First Last"
    git config --global user.email first.last@domaine.tld
    
  2. Interface preferences.

    Set your preferred text editor to edit commit messages:

    git config --global core.editor emacs
    

    Enable colored messages in your terminal, which is more convenient to read:

    git config --global color.diff auto
    git config --global color.status auto
    git config --global color.branch auto
    

    Caution: Git uses the less pager which may not display colors correctly (as in condor). If you encounter this issue, type the following command:

    git config --global core.pager "less -R"
    

New Git users

New Git users are invited to read some guides to get familiar with vanilla Git concepts and commands. Some guides available online:

  • À partir de zéro sur le site d'OpenClassrooms, in French.
  • Basic and advanced guide with the git-book, in English, French, and many other languages.

Nevertheless, some good practice must be recalled here:

  1. When do commit.
    • Commit compiling and working code as much as possible.
    • Commit small, coherent sets of modifications. This helps debugging, rebasing, and merging.
    • Put variable and function renaming that affect the whole code apart.
  2. Writing commit messages.
    • Commit message must comprise a one-line summary, a blank line, and the detailed message.
    • The one-line summary is mandatory, the detailed message is optional.
    • The one-line summary may start with a topic title enclosed in brackets.
    • Although, the one-line summary must remain as short as possible, while remaining descriptive.
    • Wrap your commit message to 80 characters or less.
    • Please, use correct English.
    • Your detailed message must emphasize the reasons of your modifications and your design choices. It is not very useful to simply describe your modifications: we can do a git show of your commit, but we cannot do a git show of your brain.
      [Cooking] Add the new "raclette" recipe.
      
      This recipe follows the structure of the existing reciepe... using
      the global variable `savoie` added with this commit.
      
      It uses the cheese provided by the module mod_foo, that does already
      the job.
      
      This recipe may be activated by setting the boolean `chalet` to true
      in the input file.
      

Global organization

Official branches

The Notus repository is based on a simplified version of the [git-branching-model][Git branching model] of Vincent Driessen.

That is, Notus repository have two main branches:

  • master: contains the stable versions of Notus;
  • dev: contains the development version of Notus.
Warning
Developers must not commit into the master nor the dev branches.

Instead, developers should create their own feature branches, push them into their public repository, and, once ready, ask the Notus maintainer to merge their modification into the dev branch. Figure 1 below illustrates the branching organization.

fig-git-branching-model.png
Figure 1: Notus branches.

Repositories

Notus sources are accessible in the [official] repository (read-only access). Notus developers have a public repository [user/public], in which they publish their feature branches. Developers are encouraged to work in a different repository [user/private], to keep their public repository clean, and to work directly on their targeted machines.

    [official]      [user1/public]     [user2/public]   ...

                    [user1/private]    [user2/private]  ...

The development is thus organized as follows:

  1. The developer get the latest official version of Notus:
     [official]      [user/public]
         │
         └─────────> [user/private]
    
  2. The developer publishes its modifications in his public repository:
     [official]      [user/public] <─┐
                                     │
                     [user/private] ─┘
    
  3. The Notus maintainer retrieves the modifications he wants to integrate into Notus:
     [official] <─── [user/public]
    
                     [user/private]
    
  4. The developer can update its repositories:

     [official]      [user/public]
         │
         └─────────> [user/private]
    

    Which is similar to step 1, and working on the next modifications.

Official Notus repository

Notus uses a self-hosted GitLab website: https://git.notus-cfd.org/notus/notus.

Common manipulations

Here is a list of common manipulations that are specific to the Notus organization, and are intended to help any inexperienced user.

Update your private and public repositories to the official version

  1. Import the official version to your private repository
    git checkout master
    git pull official master
    git checkout dev
    git pull official dev
    
  2. Export the official version to your public repository
    git push
    

Code into Notus

  1. Create a new branch from the dev branch:

    git checkout dev
    git branch new_branch
    git checkout new_branch
    

    where new_branch is a name of your choice.

  2. Make developments, do commits.

    Get the status of your modifications:

    git status
    

    Add a file or a file modification to prepare next commit:

    git add file_name
    

    Commit your modifications (write a clear commit message):

    git commit
    

    Fix up the last commit:

    git commit --amend
    

    Some shortcuts to use with caution:

    Add ALL file modifications to prepare next commit:

    git add -u
    

    Add AND commit at the same time:

    git commit -a
    
  3. Push your finished work into your public repository

    git push
    

    Please, mind that you should not modify your commits once you pushed them.

  4. Synchronize your repository with the official repository

    Fetch all the modifications of distant repositories

    git remote update -p
    

    Update your local and public dev branch

    git checkout dev
    git pull official dev
    git push origin
    

    Rebase your local branch to dev

    git checkout local_branch
    git rebase dev
    
  5. Miscellaneous Git commands

    Cancel a file modification

    git checkout filename
    

    Cancel last commit

    git reset --hard HEAD^