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 (withgit rebase --continue
) operation. - if you prefer to cancel the operation instead of resolving conflicts, use
git merge --abort
orgit 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.