GIT Basics
Working with OpenMx
Here are the essential commands for an occasional developer.
git clone git@github.com:OpenMx/OpenMx.git
Clone grabs a copy of the history. You only do this once.
Build a specific version
The first step is to figure out what the team repository is named in your local GIT,
git remote -v
This command will print a two column mapping (name and remote address). Look for the name of
git@github.com:OpenMx/OpenMx.git
. It will probably be called origin or team. The next step is to fetch the most recent changes from that remote,
git fetch origin # or team depending on the output of 'git remote'
Some diagnostic output should print indicating that your repo is updated. Now check out the latest version of the master branch,
git reset --hard origin/master
Or maybe you want the stable branch,
git reset --hard origin/stable
Or maybe you want a specific version,
git reset --hard v2.6.2-6-g70ba06a
Developer process workflow
Make some changes. Commit them with
git commit -a
Here are some guidelines about writing a good commit message.
After you test your changes and are ready to publish to the rest of the team then
git fetch origin # fetch any new commits from other developers git rebase origin/master # put your changes on top of HEAD git push origin HEAD:master # publish your changes
I do not recommend 'git pull'. The user interface for 'pull' is designed for change integrators (think Torvolds), not so much for developers. There is a way to get the same effect as fetch/rebase using pull, but I recommend you do these operations as separate steps.
Merges
You can merge changes onto the master branch. However, you should not create a merge commit for no reason. A linear history is easier to understand than a history containing many merges back and forth between slightly different branches. A good reason to make a merge commit is if somebody else contributed the changes and your role is only to merge them. You might merge your own branch too if there is a sequence of commits that are related to the same logical change. However, a merge commit is not an excuse to omit testing each commit separately. Every individual commit should be 100% passing on our test suite.
Here is how to create a nice clean merge.
git checkout feature/description # a descriptive branch name is encouraged git fetch team # fetch any new commits from other developers git rebase origin/master # put your changes on top of HEAD git checkout -b master origin/master # create a branch where you can merge to git merge --no-ff feature/description # merge it git push origin HEAD:master # publish your changes
Note that before we merge the branch, we rebase it on top of origin/master. This is important to simplify (linearize) history as much as possible. Without this step, there is a chance of merge conflicts that need to be resolved in the merge. It is more transparent to resolve any merge conflicts in the branch before merging and leave the merge commit empty. This is not an absolute rule, but it is encouraged.
Enjoy GIT
- Use tig to examine history
- Learn how to do an interactive rebase
- Learn how to use git bisect to determine when a bug was introduced
Interacting with Buildbot
UVa runs a buildbot on the university's Linux compute cluster. You can request the buildbot to build and test your branch before you push your changes to the team's master branch.
git push -f origin HEAD:joshua
There are a few things to note about this command. The '-f' flag is used to force the push. This is necessary because you want to discard whatever tree is currently published in the joshua branch and replace it with your own tree. You should never use the '-f' flag when you push to the team's master branch. After you execute this command, you can monitor progress at the buildbot website. In this example, you are using joshua's branch. If you plan to use the buildbot frequently then ask the buildbot administrator to set up buildbot builder for your own personal branch.