Documentation/Nightly/Developers/DevelopmentWithGit

For the latest Slicer documentation, visit the read-the-docs.

Development with Git

This page helps developers in the migration of Slicer4 from subversion to git.

See also: Instructions for setting up a git repository to interact with Slicer's svn

Git

Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration. Git can be obtained as described on our Git download page.

Please see our Git resource links for third party documentation, such as the ProGit Book.

Slicer Setup

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

$ ./Utilities/SetupForDevelopment.sh

The SetupForDevelopment.sh script will setup git user info and git hooks.

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.

pre-commit

This runs during git commit before the commit message editor is fired up. It checks the identity and content of changes:

• Git user.name and user.email are 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:

Emacs	(custom-set-variables '(show-trailing-whitespace t))	Emacs configuration file
Vim	:highlight ExtraWhitespace ctermbg=red guibg=red :match ExtraWhitespace /\s\+$/
Visual Studio	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)
Notepad++ (v5.6.7)	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...)

commit-msg

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:

Fixed

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.

Further Work

• 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.
• Setting up Git aliases for better management of push/pull requests
• Possible gerrit integration