ParaView/Git/Simple

Introduction

This document is intended to give the bare minimum to get up and running with ParaView - to develop and commit code to the main ParaView repository. There is a one page PDF cheat sheet intended to be a desk reference. Remember when developing/committing in the submodules you must follow the guidelines of those projects. Please refer to the general ParaView/Git guide for more details on Git configuration, the branchy workflow employed and the topic stage used for integration of topic branches.

All work should be developed in a topic branch, which is branched from the master branch. The topic branch should be staged and merged into master when ready. This facilitates a workflow where big changes can be made, tested and integrated into the mainline development tree (master) when ready for inclusion.

Initial Setup

Assuming you have your SSH key set up correctly. Run the following to clone ParaView:

$ git clone --recursive git://paraview.org/ParaView.git ParaView
$ cd ParaView
$ ./Utilities/SetupForDevelopment.sh

The last step initializes the Git submodules, adds the topic stage, installs local hooks and sets up some useful Git aliases that will be used later.

Updating ParaView

To update all of ParaView using an alias (including submodules):

$ git checkout master
$ git pullall

Starting a Topic Branch

To start a new topic branch:

$ git fetch
$ git checkout -b my_topic origin/master

Develop on this topic branch, make commits using, (omit the -m to use an editor)

$ git add file1 file2 file3
$ git commit -m 'My commit message....'

Publishing a Topic for Review (Optional)

You can optionally publish a topic branch for review in Gerrit. You must set up an account in Gerrit, then in settings choose a username and upload your public SSH key. You can then input your chosen username when running the Utilities/SetupForDevelopment.sh script.

You can check what you are about to push with the first line, and the second pushes the commits to Gerrit for review.

$ git prepush
$ git gerrit-push

Staging and Publishing a Topic to Master

From your topic branch, to merge your change(s) into master:

$ git stage-push
$ git stage-merge

Deleting Topic Branches

Once you are done, you should delete your topic branch (as it is merged into master and done).

$ git checkout master
$ git pullall
$ git branch -d my_topic

The last line will only succeed if you have correctly merged your branch to master. Using -D instead of -d will force the deletion of an unmerged topic branch (warning - you could lose commits).

Updating VTK and Other Submodules

You should commit and push changes to submodules, according to their development policy before updating the submodule hash. The submodule update should be the only thing in that commit, and will usually be one of the final commits in a topic branch bringing in new features/fixes from a submodule. The topic is staged and merged in the normal way.