|
|
| (One intermediate revision by the same user not shown) |
| Line 1: |
Line 1: |
| == Pre-commit Hooks ==
| |
|
| |
|
| This runs during <code>git commit</code>. It checks identity and the content of changes. It ensures that:
| |
|
| |
| * Git <code>user.name</code> and <code>user.email</code> are set to something reasonable
| |
| * Git's standard whitespace checks pass (see help on <code>git diff --check</code>)
| |
| * 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 sizes are not too large (don't commit big data files; prints limit and instructions on rejection)
| |
| * Submodule updates are staged alone or explicitly allowed (prints instructions on rejection)
| |
|
| |
| 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), but some don't care.
| |
| Text editors typically have a mode to highlight trailing whitespace:
| |
|
| |
| {|
| |
| |-
| |
| |width=20%|Emacs
| |
| |
| |
| (custom-set-variables '(show-trailing-whitespace t))
| |
| |-
| |
| |width=20%|Vim
| |
| |
| |
| :highlight ExtraWhitespace ctermbg=red guibg=red
| |
| :match ExtraWhitespace /\s\+$/
| |
| |-
| |
| |width=20%|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''')
| |
| |-
| |
| |width=20%|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...)
| |
| |-
| |
| |width=20%|Qt Creator (v2.0.1)
| |
| |
| |
| To eliminate trailing white space, choose the menu item:
| |
|
| |
| '''Tools > Options > Behavior > Clean whitespace'''
| |
|
| |
| To toggle viewing of white space characters, choose from the
| |
| menu items:
| |
|
| |
| '''Tools > Options > Display > Visualize whitespace'''
| |
| |}
| |
|
| |
| * Optional: KWStyle style check (aborts commit on style check failure).
| |
| Disabled by default, but can be enabled to run a style check with [http://public.kitware.com/KWStyle/ KWStyle].
| |
| To enable this hook:
| |
| git config hooks.KWStyle true
| |
|
| |
| * Optional: [http://uncrustify.sourceforge.net/ uncrustify] code beautification.
| |
| Disabled by default, but can be enabled to propose style changes to the code.
| |
| To enable this hook:
| |
| git config hooks.uncrustify true
| |
|
| |
| Proposed style changes are not added to the commit until they have been manually brought in by the developer.
| |
| This is performed with the developer's favorite merge program. For more information and a list of supported merge applications, see
| |
| git help mergetool
| |
|
| |
| To configure your preferred merge program
| |
| git config merge.tool <toolname>
| |
|
| |
| == Commit-msg Hooks ==
| |
|
| |
| This runs during <code>git commit</code>. 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. <br> They MUST begin with 'ENH:', 'COMP:' 'STYLE:' or 'BUG:' prefixes.
| |
| 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 (enhancement)
| |
| STYLE: - a change that does not impact the logic or execution of the code.
| |
| (improve coding style, comments, documentation).
| |
| * The first line must not have leading or trailing whitespace.
| |
| * 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:
| |
|
| |
| BUG: Fixed
| |
|
| |
| This is too short and not informative at all.
| |
|
| |
| 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.
| |
|
| |
| 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 <code>git commit --amend</code>.
| |
|
| |
| == Server Hooks ==
| |
|
| |
| Many <code>public.kitware.com</code> repositories have server-side hooks.
| |
|
| |
| == Update Hooks ==
| |
|
| |
| The update hook runs when someone tries to update a ref on the server by pushing.
| |
| The hook checks all commits included in the push:
| |
|
| |
| * Commit author and committer must have valid email address domains (DNS lookup succeeds).
| |
| * Commit message does not start with "<code>WIP:</code>". (Use the prefix locally for work-in-progress that must be rewritten before publishing.)
| |
| * Changes to paths updated by robots (such as Utilities/kwsys) are not allowed.
| |
| * No "large" blobs may be pushed. The limit is set on a per-repository basis and is typically 1MB or so.
| |
| * No CRLF newlines may be added in the repository (see core.autocrlf in <code>git help config</code>).
| |
| * Submodules (if any) must be pushed before the references to them are pushed.
| |
