From 786e70ac5ef9ef5996bb335352f30852f7895186 Mon Sep 17 00:00:00 2001 From: Tony Date: Mon, 2 Dec 2013 12:54:52 -0500 Subject: Updated README to use markdown & edited for grammar, phrasing, and clarity --- README | 57 --------------------------------------------------- README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+), 57 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 530e5e7..0000000 --- a/README +++ /dev/null @@ -1,57 +0,0 @@ -git-hooks - A tool to manage project, user, and global Git hooks for multiple git repositories. - -git-hooks lets hooks be installed inside git repositories, users home directory, and globally. When a hook is called by git, git-hooks will check each of these locations for the hooks to run. - -************************************ -Install - -Add git-hooks to your PATH environment variable so 'git hooks' can be run. - -Run 'git hooks --install' Inside a git project to change that projects git hooks to use git-hooks hooks. 'git hooks --uninstall' can be run at any time to go back to the old hooks that were installed before (typically the default which does nothing). - -Run 'git hooks --installglobal' to force any new git repository or any git repository you clone to have a reminders to install git hooksi. (It can't be on by default for security reasons of course) - -************************************ -Overview - -Hooks can be very powerful and useful. Some common hooks include: - -- Spell check the commit message. -- Check that the code builds. -- Verify that any new files contain a copyright with the current year in it. - -Hooks can be very project specific such as: - -- Verify that the project still builds -- Verify that autotests matching the modified files still pass with no errors. -- Pre-populate the commit message with the 'standard' format. -- Verify that any new code follows the 'standard' coding style. - -or very specific to one person such as: - -- Don't allow a push to a remote repository after 1am in case I break something and will be asleep. -- Don't let me commit between 9-5 for projects in ~/personal/ as I shouldn't be working on them during work hours. - -For more details on the different Git hooks that can be installed checkout the online documentation at http://www.kernel.org/pub/software/scm/git/docs/githooks.html - -************************************ -Locations - -git-hooks provide a way to manage and share your hooks by allowing for the installation of hooks in three locations: - - User hooks that are installed in ~/.git_hooks/ - - Project hooks that are installed in the git_hooks directory inside of each project. - - Global hooks that are specified with the hooks.global configuration option. - The contrib directory includes a number of useful hooks and can be set by doing the following: - git config --global hooks.global $PWD/contrib/ - -Multiple global hooks directories can be specified by using a space between each path. - -************************************ -Creating hooks - -To keep things organized git-hooks looks for scripts in sub directories named after the git hook name. For example this project has the following pre-commit script in the following location: - -git_hooks/pre-commit/bsd - -When you run 'git hooks' with no arguments it will list all of the hooks installed on the system. It will run the hooks with the --about argument to generate the description that is shown. Checkout the hooks in contrib for some examples. - diff --git a/README.md b/README.md new file mode 100644 index 0000000..8ad8db9 --- /dev/null +++ b/README.md @@ -0,0 +1,70 @@ +**git-hooks** - A tool to manage project, user, and global Git hooks for multiple git repositories. + +git-hooks lets hooks be installed inside git repositories, users home directory, and globally. +When a hook is called by `git`, git-hooks will check each of these locations for the hooks to run. + + +Install +======= + +Add git-hooks to your `PATH` environment variable so `git hooks` can be run. + +Run `git hooks --install` in a git project tell it to use git-hooks hooks. You can run `git hooks --uninstall` at any time to revert to your previous hooks. (These are usually the default hooks, which do nothing.) + +Run `git hooks --installglobal` to force any new git repository or any git repository you clone to have a reminder to install git hooks. (It can't be on by default for security reasons.) + + +Overview +======== + +Hooks are powerful and useful. Some common hooks include: + +- Spell check the commit message. +- Verify that the code builds. +- Verify that any new files contain a copyright with the current year in it. + +Hooks can be very project-specific such as: + +- Verify that the project still builds +- Verify that autotests matching the modified files still pass with no errors. +- Pre-populate the commit message with a "standard" format. +- Verify that any new code follows a "standard" coding style. + +Or very person-specific hooks, such as: + +- Don't allow a `push` to a remote repository after 1AM, in case I break something and will be asleep. +- Don't allow a commit between 9-5 for projects in `~/personal/`, as I shouldn't be working on them during work hours. + +For more details about the different hooks available to you, check out: + + http://www.kernel.org/pub/software/scm/git/docs/githooks.html + + + +Locations +========= + +git-hooks provide a way to manage and share your hooks using three locations: + + - **User hooks**, installed in `~/.git_hooks/` + - **Project hooks**, installed in `.git/git_hooks/` in a project. + - **Global hooks**, specified with the `hooks.global` configuration option. + +The `contrib/` directory includes a number of useful hooks, and can be set by doing the following: + + git config --global hooks.global $PWD/contrib/ + +You can even specify _multiple_ directories for your global hooks! Simply separate each path with spaces. + + +Creating hooks +============== + +To keep things organized, git-hooks looks for scripts in **sub-directories** named after the git hook name. For example, this project has the following `pre-commit` script in the following location: + + git_hooks/pre-commit/bsd + +When `git hooks` is run without arguments, it lists all hooks installed on your system. It will run the hooks with the `--about` argument to generate the description shown. + +Check out the hooks in `contrib/` for some examples. + -- cgit v1.2.3