General instructions to use git to contribute to Gmsh

Install git

If git is not provided by your OS, you can download it from the official git website. (This website also provides nice tutorials and a complete reference guide.)

Configure git

Before starting to use git, you have to configure a few variables to specify your name, email, and your editors.

git config --global user.name "Jon Doe"
git config --global user.email johndoe@example.com
git config --global core.editor vim
git config --global diff.tool vimdiff

Replace vim by your text editor and vimdiff by your diff viewer (skip this configuration if you do not have a diff viewer).

You may also wish to set up an alias git alog which allows to easily visualize the history graph from the command line.

git config --global alias.alog "log --graph --oneline --all --decorate"

You can now use git alog to see the commit history.

Get the Gmsh source code

Clone the Gmsh official repository

If you do not have an account, you can create one in the "Register" tab of the onelab gitlab website.

git clone https://username@gitlab.onelab.info/gmsh/gmsh.git

(replace username by your login)

Create a feature branch

Never work directly on the master branch, always work on a specific branch then, when your branch is ready, check that all testcases pass and submit a request to merge your branch into master.

You can also run the tests directly on your machine, by running ctest in your build directory.

Your new branch will start from master, so first be sure that your copy of the master branch is up-to-date.

git checkout master
git pull

You can now create your branch (here called myfeature).

git checkout -b myfeature

(Use git checkout branchname to switch from one branch to another).

Make some commits

After editing the source code, you have to add to the index the files that you want to include in your commit.

git add file1.cpp file2.h

A file can be added several time if it was further modified.

git add file1.cpp

It is also possible to add a part of a file.

git add -p file3.cpp

To see the current status, use :

• git status to list the files that will be included in the next commit
• git diff --cached to list the modification that will be included
• git diff to list the modifications that won't be included.

Once a coherent set of modifications is in the index, the actual commit can be performed.

git commit

Publish a branch

Other developers work on their own branches, so you can push your branch to the server without fear of conflicts. To push a branch for the first time, use

git push --set-upstream origin myfeature

after that, you can simply push with

git push

Note that in order to push you will need to be granted developer access for gmsh: you can request access directly through gitlab on the project page, by clicking on the Request Access button.

Update a branch

If other developers contribute to the same branch, you may wish to get their commits and apply your commits on top of theirs. Be sure, that all modifications are commited (or stashed), then :

git pull --rebase

Request a merge

Once a branch is ready, it has to be merged into master. First, be sure that all the changes that are in the master branch are also in your branch.

git fetch
git merge origin/master
git push

The git push command will print a message with the url where you can create a merge request for your branch.

PS: you could also do

git checkout master
git pull
git checkout myfeature
git merge master
git push

Fix conflicts

If conflicts occur during a rebase or a merge, git will stop and you will have to fix them.

• use git status to list the files with conflicts
• fix the conflicts and add the fixed files to the index with git add
• when no conflict remains, resume the merge (with git merge --continue) or rebase (with git rebase --continue) operation.
• if you prefer to cancel the operation instead of resolving conflicts, use git merge --abort or git rebase --abort.

(For Gmsh "masters") Accept a merge request

First check that the commits in the branch do not break the testcases (the gitlab server should put a green icon beside the commit and on the page of the merge request) and that the code looks good. If it's not the case, you can discuss the modifications on the page of the merge request on gitlab and ask for changes. Once the branch is satisfactory, merge it into master.

You can do the merge right from gitlab's interface, or on the command line:

git fetch
git checkout master
git merge --no-ff myfeature
git push

Finally, delete the branch locally and on the server

git branch -d myfeature
git push origin --delete myfeature

(Optional) Clean a branch

Before requesting a merge of your branch into master, you may wish to clean its history (e.g. to combine a commit with another commit that fixes it). Always do it in a copy of your branch.

git fetch
git checkout -b myfeatyre-clean myfeature
git rebase -i origin/master

Then follow the instructions.

(Optional) Revert modifications

• git checkout file.cpp: revert the file to its state at the last commit
• git reset --soft: undo the last commit but do not touch the files in your workspace and put all the modifications in the index, ready for a new commit
• git reset --mixed: undo the last commit but do not touch the files in your workspace, and empties the index
• git reset --hard: undo the last commit, including the files in your workspace

Never reset a branch in a way that would remove or alter commits that are already pushed to the server. If you want to remove changes already pushed to the server, you can either

• create a new branch, fix its history then push it
• or create a new commit that will revert the changes introduced by a previous commit using git revert rev (replace rev by the hash of the commit).

(Optional) Others

Here are some commands that you may find useful (use git help command for more information, e.g. git help stash):

• git stash/git stash pop: put changes aside for later use
• git bisect: find regression in history
• git blame filename.c: list which is the last commit affecting each line
• git grep: search for an expression in the history
• git cherry-pick rev: apply a single commit from another branch

References

• Read the Git Pro Book, it's good!
• [Atlassian Git] (https://www.atlassian.com/git/tutorials/comparing-workflows) has a good descriptions of various workflow with git.
• [This presentation] (ThirdGmshWorkshop/lambrechts-git.pdf) during the third Gmsh workshop provided a relatively long introduction to git.