Skip to content

Commit 4bb4b83

Browse files
igorsgmigorsgm
committed
Update README.md
1 parent 1fd8fb5 commit 4bb4b83

File tree

1 file changed

+251
-21
lines changed

1 file changed

+251
-21
lines changed

‎README.md

Lines changed: 251 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,266 @@
1-
# Very short description of the package
1+
<h1 align="center">🪝 Laravel Git Hooks</h1>
22

3-
[![Latest Version on Packagist](https://img.shields.io/packagist/v/igorsgm/laravel-git-hooks.svg?style=flat-square)](https://packagist.org/packages/igorsgm/laravel-git-hooks)
4-
[![Total Downloads](https://img.shields.io/packagist/dt/igorsgm/laravel-git-hooks.svg?style=flat-square)](https://packagist.org/packages/igorsgm/laravel-git-hooks)
5-
![GitHub Actions](https://github.com/igorsgm/laravel-git-hooks/actions/workflows/main.yml/badge.svg)
3+
<p align="center">A powerful and easy-to-use package for managing Git hooks within your Laravel projects. Improve your code quality, reduce the time spent on code reviews, and catch potential bugs before they make it into your repository.</p>
64

7-
This is where your description should go. Try and limit it to a paragraph or two, and maybe throw in a mention of what PSRs you support to avoid any confusion with users and contributors.
5+
<p align="center">
6+
<a href="https://packagist.org/packages/igorsgm/laravel-git-hooks">
7+
<img src="https://img.shields.io/packagist/v/igorsgm/laravel-git-hooks.svg?style=flat-square" alt="Latest Version on Packagist">
8+
</a>
9+
<a href="https://github.com/igorsgm/laravel-git-hooks/actions/workflows/main.yml/badge.svg">
10+
<img src="https://img.shields.io/github/actions/workflow/status/igorsgm/laravel-git-hooks/main?style=flat-square" alt="Build Status">
11+
</a>
12+
<a href="https://packagist.org/packages/igorsgm/laravel-git-hooks">
13+
<img src="https://img.shields.io/packagist/dt/igorsgm/laravel-git-hooks.svg?style=flat-square" alt="Total Downloads">
14+
</a>
15+
</p>
816

9-
## Installation
17+
<hr/>
1018

11-
You can install the package via composer:
19+
<p align="center">
20+
<img src="" alt="Laravel Git Hooks usage sample">
21+
</p>
1222

23+
## ✨ Features
24+
25+
- **Pre-configured Hooks:** Laravel Git Hooks comes with pre-configured pre-commit hooks for popular tools, such as Laravel Pint, PHPCS, ESLint, Prettier, Larastan, Enlightn, and Blade Formatter, making it easy to enforce coding standards and style guidelines right away.
26+
- **Manage Git Hooks:** Easily manage your Git hooks in your Laravel projects with a streamlined and organized approach.
27+
- **Edit Commit Messages:** Gain control over your commit messages by customizing them to meet your project requirements and maintain a clean Git history.
28+
- **Create Custom Hooks:** Add and integrate custom hooks tailored to your specific project needs, ensuring better code quality and adherence to guidelines.
29+
- **Artisan Command for Hook Generation:** The package includes a convenient Artisan command that allows you to effortlessly generate new hooks of various types. Such as: `pre-commit`, `prepare-commit-msg`, `commit-msg`, `post-commit`, `pre-push`
30+
- **Code Quality:** The package is thoroughly tested, with 100% of code coverage, ensuring its reliability and stability in a wide range of Laravel projects.
31+
32+
## 1️⃣ Installation
33+
34+
- You can install the package via composer:
35+
```bash
36+
composer require igorsgm/laravel-git-hooks --dev
37+
```
38+
39+
- Publish the config file and customize it in the way you want:
40+
```bash
41+
php artisan vendor:publish --tag=laravel-git-hooks
42+
```
43+
44+
- Now whenever you make a change in your `config/git-hooks.php` file, please register your git hooks by running the artisan command:
45+
```bash
46+
php artisan git-hooks:register
47+
```
48+
49+
Once you've configured and registered the hooks, you're all set!
50+
51+
## 2️⃣ General Usage
52+
### Usage of the configured pre-commit hooks
53+
To use the already created pre-commit hooks of this package, you can simply edit the `pre-commit` section of git-hooks.php config file. Here's an example of how to configure them:
54+
```php
55+
'pre-commit' => [
56+
\Igorsgm\GitHooks\Console\Commands\Hooks\PintPreCommitHook::class, // Laravel Pint
57+
\Igorsgm\GitHooks\Console\Commands\Hooks\PHPCodeSnifferPreCommitHook::class, // PHPCS (with PHPCBF autofixer)
58+
\Igorsgm\GitHooks\Console\Commands\Hooks\LarastanPreCommitHook::class, // Larastan
59+
\Igorsgm\GitHooks\Console\Commands\Hooks\EnlightnPreCommitHook::class, // Enlightn
60+
\Igorsgm\GitHooks\Console\Commands\Hooks\ESLintPreCommitHook::class, // ESLint
61+
\Igorsgm\GitHooks\Console\Commands\Hooks\PrettierPreCommitHook::class, // Prettier
62+
],
63+
```
64+
65+
### Creating Custom Git Hooks
66+
1) If you need to create a custom Git hook for your project, Laravel Git Hooks makes it easy with the `git-hooks:make` Artisan command. To create a new custom hook, simply run the following command:
67+
```bash
68+
php artisan git-hooks:make
69+
```
70+
This command will prompt you to choose the type of hook you want to create (e.g., `pre-commit`, `post-commit`, etc.) and to provide a name for the hook. Once you've provided the required information, the command will generate a new hook class in the `app/Console/GitHooks` directory.
71+
2) To start using your custom hook, open the generated file and implement the `handle()` method with your desired logic.
72+
3) Add your custom hook to the appropriate array in the git-hooks.php config file:
73+
```php
74+
'pre-commit' => [
75+
// Other pre-commit hooks...
76+
\App\Console\GitHooks\MyCustomPreCommitHook::class,
77+
],
78+
```
79+
4) Finally register your custom hook by running the artisan command:
1380
```bash
14-
composer require igorsgm/laravel-git-hooks
81+
php artisan git-hooks:register
1582
```
1683
17-
## Usage
84+
## 3️⃣ Handling Git Hooks
85+
### Pre-commit Hook
86+
> The pre-commit hook is run first, before you even type in a commit message. It's used to inspect the snapshot that's
87+
> about to be committed, to see if you've forgotten something, to make sure tests run, or to examine whatever you need to
88+
> inspect in the code. Exiting non-zero from this hook aborts the commit, although you can bypass it with git commit
89+
> --no-verify. You can do things like check for code style (run lint or something equivalent), check for trailing
90+
> whitespace (the default hook does exactly this), or check for appropriate documentation on new methods.
1891
1992
```php
20-
// Usage description here
93+
// config/git-hooks.php
94+
return [
95+
...
96+
'pre-commit' => [
97+
\App\Console\GitHooks\MyPreCommitHook::class,
98+
],
99+
...
100+
];
21101
```
22102
103+
```php
104+
// App/Console/GitHooks/MyPreCommitHook.php
105+
106+
namespace App\Console\GitHooks;
107+
108+
use Closure;
109+
use Igorsgm\GitHooks\Git\ChangedFiles;
110+
111+
class MyPreCommitHook implements \Igorsgm\GitHooks\Contracts\PreCommitHook
112+
{
113+
// ...
114+
115+
public function handle(ChangedFiles $files, Closure $next)
116+
{
117+
// TODO: Implement your pre commit hook logic here.
118+
119+
// If you want to cancel the commit, you have to throw an exception.
120+
// i.e: throw new HookFailException();
121+
122+
// Run the next hook in the chain
123+
return $next($files);
124+
}
125+
}
126+
```
127+
128+
### Prepare-commit-message Hook
129+
> The prepare-commit-msg hook is run before the commit message editor is fired up but after the default message is
130+
> created. It lets you edit the default message before the commit author sees it. This hook takes a few parameters: the
131+
> path to the file that holds the commit message so far, the type of commit, and the commit SHA-1 if this is an amended
132+
> commit. This hook generally isn't useful for normal commits; rather, it's good for commits where the default message is
133+
> auto-generated, such as templated commit messages, merge commits, squashed commits, and amended commits. You may use it
134+
> in conjunction with a commit template to programmatically insert information.
135+
136+
```php
137+
// config/git-hooks.php
138+
return [
139+
...
140+
'prepare-commit-msg' => [
141+
\App\Console\GitHooks\MyPrepareCommitMessageHook::class,
142+
],
143+
...
144+
];
145+
```
146+
147+
```php
148+
// App/Console/GitHooks/MyPrepareCommitMessageHook.php
149+
150+
namespace App\Console\GitHooks;
151+
152+
use Closure;
153+
use Igorsgm\GitHooks\Git\CommitMessage;
154+
use Igorsgm\GitHooks\Contracts\MessageHook;
155+
156+
class MyPrepareCommitMessageHook implements \Igorsgm\GitHooks\Contracts\MessageHook
157+
{
158+
// ...
159+
160+
public function handle(CommitMessage $message, Closure $next)
161+
{
162+
// TODO: Implement your prepare commit msg hook logic here.
163+
164+
$currentMessage = $message->getMessage();
165+
// You can update commit message text
166+
$message->setMessage(str_replace('issue', 'fixed', $currentMessage));
167+
168+
// If you want to cancel the commit, you have to throw an exception.
169+
// i.e: throw new HookFailException();
170+
171+
// Run the next hook in the chain
172+
return $next($message);
173+
}
174+
}
175+
```
176+
177+
### Commit-msg Hook
178+
> The commit-msg hook takes one parameter, which again is the path to a temporary file that contains the commit message
179+
> written by the developer. If this script exits non-zero, Git aborts the commit process, so you can use
180+
181+
182+
```php
183+
// config/git-hooks.php
184+
return [
185+
...
186+
'commit-msg' => [
187+
\App\Console\GitHooks\MyCommitMessageHook::class,
188+
],
189+
...
190+
];
191+
```
192+
193+
The class structure of the `commit-msg` hook is the same as the `prepare-commit-msg` hook, shown right above.
194+
195+
### Post-commit Hook
196+
> After the entire commit process is completed, the post-commit hook runs. It doesn't take any parameters, but you can
197+
> easily get the last commit by running git log -1 HEAD. Generally, this script is used for notification or something
198+
> similar.
199+
200+
```php
201+
// config/git-hooks.php
202+
return [
203+
...
204+
'post-commit' => [
205+
\App\Console\GitHooks\MyPostCommitHook::class,
206+
],
207+
...
208+
];
209+
```
210+
211+
```php
212+
// App/Console/GitHooks/MyPrepareCommitMessageHook.php
213+
214+
namespace App\Console\GitHooks;
215+
216+
use Closure;
217+
use Igorsgm\GitHooks\Git\CommitMessage;
218+
use Igorsgm\GitHooks\Contracts\PostCommitHook;
219+
220+
class MyPostCommitHook implements \Igorsgm\GitHooks\Contracts\PostCommitHook
221+
{
222+
// ...
223+
224+
public function handle(Log $log, Closure $next)
225+
{
226+
// TODO: Implement post commit hook logic here.
227+
228+
// You can interact with the commit log
229+
$hash = $log->getHash();
230+
$author = $log->getAuthor();
231+
$date = $log->getDate();
232+
$message = $log->getMessage();
233+
234+
// If you want to cancel the commit, you have to throw an exception.
235+
// i.e: throw new HookFailException();
236+
237+
// Run the next hook in the chain
238+
return $next($log);
239+
}
240+
}
241+
```
242+
243+
### Pre-push Hook
244+
> The pre-push hook runs during git push, after the remote refs have been updated but before any objects have been
245+
transferred. It receives the name and location of the remote as parameters, and a list of to-be-updated refs through
246+
stdin. You can use it to validate a set of ref updates before a push occurs (a non-zero exit code will abort the push).
247+
248+
```php
249+
// config/git-hooks.php
250+
return [
251+
...
252+
'pre-push' => [
253+
\App\Console\GitHooks\MyPrePushHook::class,
254+
],
255+
...
256+
];
257+
```
258+
259+
The class structure of the `pre-push` hooks is the same as the `post-commit` hook shown right above, but implementing `\Igorsgm\GitHooks\Contracts\PrePushHook` interface.
260+
23261
### Testing
24262
25-
```bash
263+
``` bash
26264
composer test
27265
```
28266
@@ -34,19 +272,11 @@ Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recen
34272
35273
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
36274
37-
### Security
38-
39-
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
40-
41275
## Credits
42276
43-
- [Igor Moraes](https://github.com/igorsgm)
44-
- [All Contributors](../../contributors)
277+
- [Igor Moraes](https://github.com/igorsgm)
278+
- [Pavel Buchnev](https://github.com/butschster)
45279
46280
## License
47281
48282
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
49-
50-
## Laravel Package Boilerplate
51-
52-
This package was generated using the [Laravel Package Boilerplate](https://laravelpackageboilerplate.com).

0 commit comments

Comments
 (0)