0
# Yorkie
1

2
Yorkie is a Git hooks management tool that provides an easy way to configure and manage Git hooks in JavaScript projects. It's a fork of husky with specific improvements for monorepo environments, prioritizing package.json files located next to .git directories and using a cleaner gitHooks configuration format.
3

4
## Package Information
5

6
- **Package Name**: yorkie
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install yorkie`
10

11
## Core Imports
12

13
Yorkie primarily works through npm lifecycle hooks and provides programmatic access to its core functions:
14

15
```javascript
16
const installFrom = require('yorkie/src/install');
17
const uninstallFrom = require('yorkie/src/uninstall');
18
```
19

20
Utilities can be imported individually:
21

22
```javascript
23
const findHooksDir = require('yorkie/src/utils/find-hooks-dir');
24
const findParent = require('yorkie/src/utils/find-parent');
25
const getHookScript = require('yorkie/src/utils/get-hook-script');
26
const { huskyOrYorkie, ghooks, preCommit } = require('yorkie/src/utils/is');
27
```
28

29
## Basic Usage
30

31
### Git Hooks Configuration
32

33
Configure Git hooks in your package.json using the `gitHooks` field:
34

35
```json
36
{
37
  "name": "my-project",
38
  "scripts": {
39
    "test": "jest",
40
    "lint": "eslint ."
41
  },
42
  "gitHooks": {
43
    "pre-commit": "npm run lint",
44
    "pre-push": "npm test",
45
    "commit-msg": "commitizen --cz-conventional-changelog"
46
  },
47
  "devDependencies": {
48
    "yorkie": "^2.0.0"
49
  }
50
}
51
```
52

53
### Automatic Installation
54

55
Yorkie automatically installs Git hooks when the package is installed:
56

57
```bash
58
npm install yorkie
59
# Git hooks are automatically set up during installation
60
```
61

62
### Environment Variables
63

64
Control yorkie's behavior with environment variables:
65

66
```bash
67
# Skip installation in CI environments (overrides default CI detection)
68
export YORKIE_IGNORE_CI=1
69

70
# Skip installation entirely during npm install
71
export YORKIE_SKIP_INSTALL=1
72

73
# Legacy husky compatibility: skip installation in CI
74
export HUSKY_IGNORE_CI=1
75

76
# Legacy husky compatibility: skip installation entirely  
77
export HUSKY_SKIP_INSTALL=1
78
```
79

80
**Environment Variable Behavior:**
81
- **CI Detection**: Yorkie automatically detects CI environments using the `is-ci` package and skips installation by default
82
- **Override CI**: Set `YORKIE_IGNORE_CI=1` or `HUSKY_IGNORE_CI=1` to force installation in CI environments
83
- **Skip Installation**: Set `YORKIE_SKIP_INSTALL=1` or `HUSKY_SKIP_INSTALL=1` to completely bypass hook installation
84
- **Legacy Support**: Both HUSKY_* and YORKIE_* prefixed variables are supported for compatibility
85

86
## Capabilities
87

88
### Hook Installation
89

90
Automatically installs Git hooks for all supported hook types during npm package installation.
91

92
```javascript { .api }
93
/**
94
 * Install Git hooks from a yorkie dependency directory
95
 * @param {string} depDir - Path to the yorkie dependency directory
96
 */
97
function installFrom(depDir);
98
```
99

100
**Supported Git Hooks:**
101
- `applypatch-msg`, `pre-applypatch`, `post-applypatch`
102
- `pre-commit`, `prepare-commit-msg`, `commit-msg`, `post-commit`
103
- `pre-rebase`, `post-checkout`, `post-merge`
104
- `pre-push`, `pre-receive`, `update`, `post-receive`, `post-update`
105
- `push-to-checkout`, `pre-auto-gc`, `post-rewrite`, `sendemail-validate`
106

107
### Hook Uninstallation
108

109
Removes yorkie-managed Git hooks during package uninstallation.
110

111
```javascript { .api }
112
/**
113
 * Uninstall Git hooks from a yorkie directory
114
 * @param {string} huskyDir - Path to the yorkie directory
115
 */
116
function uninstallFrom(huskyDir);
117
```
118

119
### Hook Execution
120

121
The runner executes Git hook commands defined in package.json. This is automatically invoked by installed Git hooks and is not intended for direct programmatic use.
122

123
**Runner Process** (src/runner.js - executable script):
124
- Reads package.json from current working directory
125
- Extracts commands from `gitHooks` field
126
- Executes the appropriate command for the triggered Git hook
127
- Exits with proper status codes
128

129
Note: The runner is an executable Node.js script, not a module that exports functions for programmatic use.
130

131
### Directory Utilities
132

133
Utilities for finding Git and package directories in complex project structures.
134

135
```javascript { .api }
136
/**
137
 * Find the Git hooks directory for a given project directory
138
 * @param {string} dir - Project directory to search from
139
 * @returns {string|undefined} Path to .git/hooks directory or undefined if not found
140
 */
141
function findHooksDir(dir);
142

143
/**
144
 * Find parent directory containing a specific file or directory
145
 * @param {string} currentDir - Starting directory for search
146
 * @param {string} name - Name of file/directory to find
147
 * @returns {string|undefined} Absolute path to parent directory or undefined if not found
148
 */
149
function findParent(currentDir, name);
150
```
151

152
### Hook Script Generation
153

154
Generates shell scripts for Git hooks with platform-specific Node.js environment setup.
155

156
```javascript { .api }
157
/**
158
 * Generate a complete shell script for a Git hook
159
 * @param {string} hookName - Name of the Git hook (e.g., 'pre-commit')
160
 * @param {string} relativePath - Relative path from Git root to package.json
161
 * @param {string} runnerPath - Path to yorkie's runner.js
162
 * @returns {string} Complete shell script content
163
 */
164
function getHookScript(hookName, relativePath, runnerPath);
165
```
166

167
**Generated Script Features:**
168
- Cross-platform Node.js path setup (Windows, macOS, Linux)
169
- NVM integration for version management
170
- Proper error handling and exit codes
171
- Git parameter passing via `GIT_PARAMS` environment variable
172

173
### Hook Detection
174

175
Utilities for detecting existing Git hook managers to handle migration scenarios.
176

177
```javascript { .api }
178
/**
179
 * Check if a hook file was created by husky or yorkie
180
 * @param {string} filename - Path to hook file
181
 * @returns {boolean} true if created by husky/yorkie
182
 */
183
function huskyOrYorkie(filename);
184

185
/**
186
 * Check if a hook file was created by ghooks
187
 * @param {string} filename - Path to hook file
188
 * @returns {boolean} true if created by ghooks
189
 */
190
function ghooks(filename);
191

192
/**
193
 * Check if a hook file was created by pre-commit
194
 * @param {string} filename - Path to hook file
195
 * @returns {boolean} true if created by pre-commit
196
 */
197
function preCommit(filename);
198
```
199

200
## Architecture
201

202
Yorkie follows a simple architecture designed for reliability and monorepo compatibility:
203

204
### Installation Flow
205
1. **npm install** triggers `bin/install.js`
206
2. Environment checks (CI detection, skip flags)
207
3. `src/install.js` analyzes project structure
208
4. Prioritizes package.json next to .git directory
209
5. Generates hook scripts for all supported Git hooks
210
6. Handles migration from other hook managers (ghooks, pre-commit, husky)
211

212
### Execution Flow
213
1. Git triggers installed hook (e.g., `.git/hooks/pre-commit`)
214
2. Hook script sets up Node.js environment and paths
215
3. `src/runner.js` reads package.json `gitHooks` configuration
216
4. Executes corresponding command with proper error handling
217
5. Returns appropriate exit code to Git
218

219
### Key Design Principles
220
- **Monorepo-first**: Prioritizes package.json location relative to .git directory
221
- **Migration-friendly**: Automatically migrates from other hook managers
222
- **Environment-aware**: Handles CI environments and manual skip flags
223
- **Cross-platform**: Works on Windows, macOS, and Linux with proper path handling
224

225
## Error Handling
226

227
Yorkie handles several error scenarios gracefully:
228

229
- **Missing .git directory**: Skips installation with warning message
230
- **CI environments**: Automatically skips installation unless overridden
231
- **Nested node_modules**: Prevents installation from sub-dependencies
232
- **Existing user hooks**: Preserves user-created hooks rather than overwriting
233
- **Missing gitHooks config**: Runner exits gracefully if no hooks configured
234
- **Command failures**: Proper exit codes passed to Git with descriptive error messages
235

236
## Differences from Husky
237

238
Yorkie addresses specific limitations in husky for monorepo environments:
239

240
1. **Package.json Discovery**: Prioritizes package.json next to .git directory instead of upward search
241
2. **Configuration Format**: Uses `gitHooks` object instead of npm script names
242
3. **Monorepo Compatibility**: Prevents conflicts when multiple packages depend on hook managers
243
4. **Installation Logic**: Better handling of nested node_modules structures