You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+57-33
Original file line number
Diff line number
Diff line change
@@ -20,23 +20,23 @@ Here's what happens when we use Hookz on Hookz itself:
20
20
21
21
## Installation
22
22
23
-
To install hookz, [download the latest release](https://github.com/devops-kung-fu/hookz/releases) , make is executable, rename it to _hookz_ and toss it in your ```/usr/local/bin``` directory for Linux, or on your path for other operating systems.
23
+
To install hookz, [download the latest release](https://github.com/devops-kung-fu/hookz/releases) , make is executable, rename it to ```hookz``` and toss it in your ```/usr/local/bin``` directory for Linux, or on your path for other operating systems.
Hookz uses a configuration file to generate hooks in your local git repository. This file needs to be in the root of your repository and must be named *.hookz.yaml*
34
+
Hookz uses a configuration file to generate hooks in your local git repository. This file needs to be in the root of your repository and must be named ```.hookz.yaml```
35
35
36
36
### Example Configuration
37
37
38
38
```yaml
39
-
version: 2.1
39
+
version: 2.1.1
40
40
hooks:
41
41
- type: pre-commit
42
42
actions:
@@ -59,9 +59,9 @@ hooks:
59
59
args: ["-e", "Done!"]
60
60
```
61
61
62
-
Hooks will read this example configuration and create a pre-commit hook and a post-commit hook based on this yaml.
62
+
Hooks will read this example configuration and create a ```pre-commit``` hook and a ```post-commit``` hook based on this yaml.
63
63
64
-
An action with an URL will download the binary from the defined URL and configure the hook to execute the command with the defined arguments before a commit happens.
64
+
An action with an ```URL``` will download the binary from the defined URL and configure the hook to execute the command with the defined arguments before a commit happens.
65
65
66
66
The post-commit in this configuration will execute a command named "dude" with the arguments "Hello World" after a commit has occurred. Note that the _dude_ command must be on your path. If it isn't this post-commit will fail because the command isn't found.
67
67
@@ -71,16 +71,16 @@ The following notes apply to the elements in the YAML:
71
71
72
72
|Attribute|Notes|
73
73
|---|---|
74
-
|URL|If this exists, then exec and script are ignored. The URL must be a link to an executable binary|
75
-
|exec|If this exists then URL and script are ignored|
76
-
|script|If this exists then URL, exec, and args are ignored|
77
-
|args|Optional in all cases|
74
+
|```URL```|If this exists, then exec and script are ignored. The URL must be a link to an executable binary|
75
+
|```exec```|If this exists then URL and script are ignored|
76
+
|```script```|If this exists then URL, exec, and args are ignored|
77
+
|```args```|Optional in all cases|
78
78
79
79
### Inline scripting
80
80
81
-
Scripts can be embedded into the .hookz.yaml in multiline format such as follows:
81
+
Scripts can be embedded into the ```.hookz.yaml``` in multiline format such as follows:
82
82
83
-
__NOTE:__ There needs to be a \n at the end of a line if a multi-line statement exists in the script: node, and special characters need to be escaped properly.
83
+
__NOTE:__ There needs to be a \n at the end of a line if a multi-line statement exists in the ```script``` node, and special characters need to be escaped properly.
84
84
85
85
``` yaml
86
86
- type: pre-commit
@@ -96,35 +96,41 @@ If you have args flags set, they can be referenced as $1, $2, etc. in your scrip
96
96
97
97
### Support for multiple commands in a hook
98
98
99
-
If multiple hooks are defined in the configuration with the same type (ie: pre-commit) they will be configured to run in the order they appear in the file. There is no need to group types together, they will be written to the appropriate hooks.
99
+
If multiple hooks are defined in the configuration with the same type (ie: ```pre-commit```) they will be configured to run in the order they appear in the file. There is no need to group types together, they will be written to the appropriate hooks.
100
100
101
101
### Hook types
102
102
103
103
Hook types that will execute are the same as supported by _git_. Examples are as follows:
104
104
105
-
* applypatch-msg
106
-
* commit-msg
107
-
* fsmonitor-watchman
108
-
* post-commit
109
-
* post-update
110
-
* pre-applypatch
111
-
* pre-commit
112
-
* pre-update
113
-
* prepare-commit-msg
114
-
* pre-push
115
-
* pre-rebase
116
-
* pre-receive
117
-
* update
105
+
* ```applypatch-msg```
106
+
* ```commit-msg```
107
+
* ```fsmonitor-watchman```
108
+
* ```post-commit```
109
+
* ```post-update```
110
+
* ```pre-applypatch```
111
+
* ```pre-commit```
112
+
* ```pre-update```
113
+
* ```prepare-commit-msg```
114
+
* ```pre-push```
115
+
* ```pre-rebase```
116
+
* ```pre-receive```
117
+
* ```update```
118
118
119
119
### Return Codes
120
120
121
121
Any non-zero return code from a command executed in a hook will return a FAIL.
122
122
123
+
### Security
124
+
125
+
**IMPORTANT:** the ```URL``` element will download a binary, store it in your .git/hookz folder and mark it executable. It is important to ensure that **YOU KNOW THE SAFETY** of the executable that you are downloading. A more secure way is to use the ```exec``` attribute to run an application which is already locally installed, or embed a script in the ```script``` element to download and check the ```shasum``` of the file.
126
+
127
+
For additional security notes, view the [SECURITY.md](SECURITY.md)
128
+
123
129
## Running Hookz
124
130
125
131
126
132
127
-
To generate the hooks as defined in your configuration simply execute the following command in the _root of your local repository_ where the .hookz.yaml file resides:
133
+
To generate the hooks as defined in your configuration simply execute the following command in the _root of your local repository_ where the ```.hookz.yaml``` file resides:
128
134
129
135
``` bash
130
136
hookz initialize # you can also use the init alias
@@ -143,26 +149,28 @@ hookz update
143
149
```
144
150
145
151
### Applying changes to the .hookz.yaml
146
-
If there is a modification to the .hookz.yaml file in your application, you'll need to apply the changes using the following:
152
+
If there is a modification to the ```.hookz.yaml``` file in your application, you'll need to apply the changes using the following:
147
153
148
154
``` bash
149
155
hookz reset
150
156
```
151
157
152
158
### Verbose option
153
159
154
-
The initialize (init) and reset command optionally take a verbosity flag to indicate extended output should be displayed when a hook executes. This is handy for debugging or seeing errors that may be suppressed by hookz.
160
+
The ```initialize``` (init) and ```reset``` command optionally take a verbosity flag to indicate extended output should be displayed when a hook executes. This is handy for debugging or seeing errors that may be suppressed by hookz.
155
161
156
162
```
157
163
hookz init --verbose
158
164
hookz reset --verbose
159
165
```
166
+
167
+
160
168
## Example Hooks
161
169
162
170
### Recursively tidy all go.mod files in subdirectories
163
171
164
172
```yaml
165
-
version: 2.1.0
173
+
version: 2.1.1
166
174
hooks:
167
175
- type: pre-commit
168
176
actions:
@@ -176,7 +184,7 @@ hooks:
176
184
### Update all go modules to the latest version before committing
177
185
178
186
```yaml
179
-
version: 2.1.0
187
+
version: 2.1.1
180
188
hooks:
181
189
- type: pre-commit
182
190
actions:
@@ -188,14 +196,30 @@ hooks:
188
196
### Pull from your remote branch before committing
189
197
190
198
```yaml
191
-
version: 2.1.0
199
+
version: 2.1.1
192
200
hooks:
193
201
- type: pre-commit
194
202
actions:
195
203
- name: "Git Pre-Commit Pull"
196
204
exec: git
197
205
args: ["pull"]
198
206
```
207
+
### Check for open source component vulnerabilities
__NOTE:__ The ```|| true``` on the end of the command makes the hook always return a success return code. If you want to break the commit on a failure, then remove this directive.
0 commit comments