Getting started

Git configuration

Follow these instructions to setup essential information on your machine.

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
```
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:

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

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:

The developer get the latest official version of Notus:

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

The developer publishes its modifications in his public repository:

 [official]      [user/public] <─┐
                                 │
                 [user/private] ─┘

The Notus maintainer retrieves the modifications he wants to integrate into Notus:
```
 [official] <─── [user/public]

                 [user/private]
```
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

Import the official version to your private repository

git checkout master
git pull official master
git checkout dev
git pull official dev

Export the official version to your public repository
```
git push
```

Code into Notus

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.
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
```
Push your finished work into your public repository
```
git push
```
Please, mind that you should not modify your commits once you pushed them.
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
```
Miscellaneous Git commands

Cancel a file modification
```
git checkout filename
```
Cancel last commit
```
git reset --hard HEAD^
```