��������

In this post we present the main steps required to use git version control while developing a new OpenFOAM case/code and how to collaborate with your team on a OpenFOAM repository hosted in Github.

Step 1) Clone the repository

Let��s suppose that your lead engineer has created a repo on github called ��https://github.com/CodeDev�� and you want to work on it and add some contributions.

[Notation convention : in the present post, all the command you need to input in the linux terminal are highlighted with bold blue. ]

First it is necessary to clone the repository into your machine using the ��git clone�� command:

git clone git [at] github.com:CodeDev.git

A new directory CodeDev will be created. Enter the directory

cd CodeDev 

ls -la  # among the hidden file you will notice the .git file, indicating that the folder ��CodeDev�� is a git working tree under git version control

git status  # after a fresh clone git will just output that you are on the branch main, and there is nothing to commit, working directory clean

Step 2) Create your local branch to implement your modifications

It is preferable to not work directly on the main branch. Instead create a feature branch with the following command:

git branch yourGitBranch 

git checkout yourGitBranch # ��checkout�� command is used to activate your branch, so that all your new commits will be recorded on ��yourGitBranch�� and not on the main branch you previously cloned.

Step 3) Make your modification and commit locally

Start making your modifications, change the files you find in the CodeDev directory and/or add new files, directories. From time to time use the ��git add�� command to track the files you are working on, and do a commit to keep history of your modifications:

git add . # use the ��.�� to track all the files in the current directory

git commit -m "my Description of commit 1" # add an exhaustive description of your commit

git push origin yourGitBranch # push your local branch to remote

If after your first commit, you need to add new files, for example you needed to add a new STL file for your OpenFOAM case, repeat the same process:

git add .

git commit -m "updated the STL geometry"

git push origin yourGitBranch

Step 4) Fetch updates from remote

When your modifications are completed and you are ready to share them with your team, first  use the fetch command to make sure that when you merge your changes back to the main branch you are up to date.  

git fetch  # the fetch commands downloads commits, files and references from the remote repository into your local repo

Step 5) Compress your commits into a single commit

To keep things neat and clean, before merging your contribution to the main branch, it is better to summarize all your micro-commits into a single macro-commit, so that the main branch has a clean history with only the main commits describing the main steps of development and disregarding the minor modifications.

git rebase -i origin/main   # once this command is launched, you will see the interactive rebase tool, with a content similar to the following :

            pick 7a3b599 commit1

            pick d44f2a0 commit2

Suppose that we want to merge commit2 into commit1, then we need to delete the word ��pick�� and put ��s�� instead, as shown below:

            pick 7a3b599 updated installation instructions

            s d44f2a0 updated installation instructions 2

Then save your modification (in case you are using VIM, with the command ��.wq!�� )  

Now instead of 2 commits, you will have a single neat commit. 

Step 6) Merge your changes to the main branch

Now we are ready to move back to the main branch and merge our contribution:

git checkout main

git merge yourGitBranch

git push origin main    # pushing your local master branch to remote

Step 7) Clean up

Since your branch is no more needed you can clean it up using the following commands:

git push origin :yourGitBranch  # remove your remote feature branch

git branch -d yourGitBranch # remove your local branch

In the picture below, we summarize all the above steps:

���ʤ��Ϥ碌