General instructions to use git to contribute to Gmsh
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.)
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 firstname.lastname@example.org git config --global core.editor vim git config --global diff.tool vimdiff
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://email@example.com/gmsh/gmsh.git
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
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
git checkout -b myfeature
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 statusto list the files that will be included in the next commit
git diff --cachedto list the modification that will be included
git diffto list the modifications that won't be included.
Once a coherent set of modifications is in the index, the actual commit can be performed.
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
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
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
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
If conflicts occur during a rebase or a merge, git will stop and you will have to fix them.
git statusto list the files with conflicts
- fix the conflicts and add the fixed files to the index with
- 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 --abortor
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).
Here are some commands that you may find useful (use
git help command for more information, e.g.
git help 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
- 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.