Development with Git
This page helps developers in the migration of Slicer4 from subversion to git.
1. Follow instructions on Start Here page to clone the Slicer repo from Github.
2. Run the developer setup script to set up your Slicer work tree
This script will setup git user info and git hooks.
- Hooks are stored in the main Slicer4 repository under a separate branch called hooks.
- These hooks are pulled when the SetupForDevelopment script is run. They are placed in the .git/hooks directory to install them.
- The following local hooks are currently installed. See Git help on githooks for more details.
This runs during
git commit before the commit message editor is fired up. It checks the identity and content of changes:
user.emailare set to something reasonable
- Git's standard whitespace checks (see help on
git diff --check)
- The staged changes do not introduce any leading TABs in source files (we indent with spaces)
- File modes look reasonable (no executable .cxx files, scripts with shebang lines are executable)
- File size is not too large (don't commit big data files; prints limit and instructions on rejection)
- Files do not have very long lines (longer than 160 characters).
One of Git's standard whitespace checks is to reject trailing whitespace on lines that were added or modified. Many people consider extra space characters at the end of a line to be an unprofessional style (including Git's own developers). NA-MIC/Slicer4 repository requires that all trailing whitespaces be removed before committing changes. Text editors typically have a mode to highlight trailing whitespace:
(custom-set-variables '(show-trailing-whitespace t))
:highlight ExtraWhitespace ctermbg=red guibg=red :match ExtraWhitespace /\s\+$/
To toggle viewing of white space characters, with a source file document active, choose the menu item: Edit > Advanced > View White Space (2-stroke keyboard shortcut: Ctrl+R, Ctrl+W)
To eliminate trailing white space, choose the menu item: Edit > Trim Trailing Space To toggle viewing of white space characters, choose from the menu items: View > Show Symbol > (multiple items, choose one...)
This runs during
git commit after the commit message is saved. It checks the commit message format:
- The first line must be between 8 and 78 characters long. If you were writing an email to describe the change, this would be the Subject line.
- The first line must not have leading or trailing whitespace.
- NA-MIC/Slicer4 requires commit messages to start with a commit type. Valid commit types are:
BUG: - a change made to fix a runtime issue (crash, segmentation fault, exception, or incorrect result, COMP: - a fix for a compilation issue, error or warning, ENH: - new functionality added to the project, PERF: - a performance improvement, STYLE: - a change that does not impact the logic or execution of the code. (improve coding style, comments, documentation).
Note that the ':'(colon) directly follows the commit tag. For example, it is: "STYLE:" not "STYLE :"
- The second line must be blank, if present.
- The third line and below may be free-form. Try to keep paragraph text formatted in 72 columns (this is not enforced).
- GUI and text-based tools that help view history typically use the first line (Subject line) from the commit message to give a one-line summary of each commit.
This allows a medium-level view of history, but works well only if developers write good Subject lines for their commits.
- Examples of improper commit messages:
This is too short and not informative at all. It does not name a commit type either.
ENH: I did a really complicated change and I am trying to describe the entire thing with a big message entered on the command line.
This is too long and defeats the purpose of a Subject line.
- A good commit message would look something like this:
BUG: Fixed improper referencing of pointers
- Further adding the Mantis issue number to the commit message is good practice. This helps checking the history of the issue on Mantis and knowing why the change was done in the first place.
- Many CVS users develop the habit of using the "-m" commit option to specify the whole message on the command line.
This is probably because in CVS it is hard to abort a commit if it already brought up the message editor.
In Git this is trivial. Just leave the message blank and the whole commit will be aborted.
Furthermore, since commits are not published automatically it is easy to allow the commit to complete and then fix it with
git commit --amend.
Testing this setup
- You can checkout my branch from here.
- Once cloned, you can run the SetupForDevelopment script as described above to setup git hooks.
- Kindly review the changes, test the hooks and provide your valuable comments/suggestions.
- Setting up a master/next git development workflow similar to that followed by large open source projects such as git.git, ParaView. A good description on this model is provided here: http://nvie.com/posts/a-successful-git-branching-model/
- Setting up Git aliases for better management of push/pull requests
- Possible gerrit integration