|
|
| (17 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| = Local Configuration =
| |
|
| |
|
| These steps are a one-time setup per-user per-machine.
| |
|
| |
| We require all commits in TubeTK to record valid author/committer name and email information.
| |
| Use [http://www.kernel.org/pub/software/scm/git/docs/git-config.html git config] to introduce yourself to Git:
| |
|
| |
| $ git config --global user.name "Your Name"
| |
| $ git config --global user.email "you@yourdomain.com"
| |
|
| |
| Note that "Your Name" is your ''real name'' (e.g. "John Doe", not "jdoe").
| |
| While you're at it, optionally enable color output from Git commands:
| |
|
| |
| $ git config --global color.ui auto
| |
|
| |
| If less displays strange characters and no color, your LESS environment variable may already be set. You can override the less options with:
| |
|
| |
| $ git config --global core.pager "less -FXRS"
| |
|
| |
| The <code>--global</code> option stores the configuration settings in <code>~/.gitconfig</code> in your home directory so that they apply to all repositories.
| |
|
| |
| = Setup Hooks =
| |
|
| |
| The [http://www.kernel.org/pub/software/scm/git/docs/git-commit.html git commit] command creates ''local'' commits.
| |
| A separate [http://www.kernel.org/pub/software/scm/git/docs/git-push.html git push] step is needed to publish commits to a <code>public.kitware.com</code> repository.
| |
| The <code>public.kitware.com</code> server [[#update|enforces some rules]] on the commits it accepts and will reject non-conforming commits.
| |
| In order to push rejected commits, one must ''edit'' history locally to repair them before publishing.
| |
|
| |
| Since it is possible to create many commits locally and push them all at once, we provide local Git ''hooks'' to help developers keep their individual commits clean.
| |
| Git provides no way to enable such hooks by default, giving developers maximum control over their local repositories.
| |
| We recommend enabling our hooks manually in all clones.
| |
|
| |
| Git looks for hooks in the <code>.git/hooks</code> directory within the work tree of a local repository.
| |
| Create a new ''local'' repository in this directory to manage the hooks and fetch VTK's hooks into that directory.
| |
|
| |
| $ cd .git/hooks
| |
| $ git init
| |
| $ git pull git://public.kitware.com/VTK.git hooks
| |
| $ cd ../..
| |
|
| |
| where <code>''<repo>''.git</code> is the name of your project repository.
| |
|
| |
| See Git help on [http://www.kernel.org/pub/software/scm/git/docs/githooks.html githooks] for more details.
| |
|
| |
| == Pre-commit Hooks ==
| |
|
| |
| This runs during <code>git commit</code>. It checks identity and content of changes:
| |
|
| |
| * Git <code>user.name</code> and <code>user.email</code> are set to something reasonable
| |
| * Git's standard whitespace checks (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 size is 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...)
| |
| |}
| |
|
| |
| * 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
| |
|
| |
| * [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.
| |
| * 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.
| |
|
| |
| = Scripted git commands for a linear history =
| |
|
| |
| * All developments MUST use the following scripts and workflow to maintain a linear git history in TubeTK
| |
| * These scripts are published online at
| |
| ** http://www.dinnermint.org/tutorial/dead-simple-git-workflow-for-agile-teams
| |
|
| |
| == gitupdate (script) ==
| |
|
| |
| #!/bin/sh -x
| |
| # hack: Merge the latest changes from the master branch into your current branch
| |
| ref=$(git symbolic-ref HEAD 2> /dev/null) || exit 0
| |
| CURRENT="${ref#refs/heads/}"
| |
| git checkout master
| |
| git pull origin master
| |
| git checkout ${CURRENT}
| |
| git rebase master
| |
|
| |
| == gitship (script) ==
| |
|
| |
| #!/bin/sh -x
| |
| # Git workflow ship script from: http://reinh.com/blog/2008/08/27/hack-and-and-ship.html
| |
| # git name-rev is fail
| |
| ref=$(git symbolic-ref HEAD 2> /dev/null) || exit 0
| |
| CURRENT="${ref#refs/heads/}"
| |
| git checkout master
| |
| git merge ${CURRENT}
| |
| git push origin master
| |
| git checkout ${CURRENT}
| |
|
| |
| == Using the Scripts ==
| |
|
| |
| The above scripts should be used in a workflow as:
| |
|
| |
| > git branch *newTopic*
| |
| > git checkout *newTopic*
| |
| > *do some work*
| |
| > git add *files*
| |
| > git commit *files*
| |
| > gitupdate
| |
| > *do some more work*
| |
| > git add *files*
| |
| > git commit *files*
| |
| > gitupdate
| |
| > gitship
| |
|
| |
| === Hidden details ===
| |
| * The above scripts and workflow implement the following, and save you much typing and potential errors!
| |
| * Most importantly, do your work in branches, not in master!
| |
| # Keep a local master branch which only is a pointer to the gitorious master (does not contain local changes)
| |
| # Make development modification in a local branch
| |
| # When getting ready to push these changes to the origin try the following
| |
| ## Do a git pull on master to fetch and merge all changes from gitorious
| |
| ### '''git checkout master'''
| |
| ### '''git pull origin master'''
| |
| ## Do a git rebase of the topic branch onto master - That is with topic checkout do "git rebase master"
| |
| ### '''git rebase master topic'''
| |
| ## Fix any conflicts that result
| |
| ### Edit files
| |
| ### '''git add -u'''
| |
| ### '''git rebase --continue'''
| |
| ## Merge the topic branch - This will result in an fast-forward merge.
| |
| ### '''git merge topic'''
| |
| ## git push your local master branch
| |
| ### '''git push origin master'''
| |
