0
# Git Operations
1

2
The Git plugin provides comprehensive Git functionality for repository operations including commits, tags, pushes, and validation. It handles branch requirements, working directory cleanliness, and rollback capabilities.
3

4
## Capabilities
5

6
### Git Plugin Class
7

8
Main Git operations plugin extending the base Plugin class.
9

10
```javascript { .api }
11
/**
12
 * Git operations plugin for repository management
13
 * Handles commits, tags, pushes, and Git validation
14
 */
15
class Git extends Plugin {
16
  /**
17
   * Check if Git plugin should be enabled
18
   * @param options - Git plugin options
19
   * @returns Promise resolving to boolean indicating if Git repo exists
20
   */
21
  static isEnabled(options: any): Promise<boolean>;
22
  
23
  /** Initialize Git plugin with validation checks */
24
  init(): Promise<void>;
25
  
26
  /** Enable rollback functionality for Git operations */
27
  enableRollback(): void;
28
  
29
  /** Disable rollback functionality */
30
  disableRollback(): void;
31
  
32
  /** Rollback Git changes (delete tag, reset commits) */
33
  rollback(): void;
34
  
35
  /** Hook called before release - stage files and show changeset */
36
  beforeRelease(): Promise<void>;
37
  
38
  /**
39
   * Execute Git release operations (commit, tag, push)
40
   * @returns Promise resolving to boolean indicating if push was performed
41
   */
42
  release(): Promise<boolean>;
43
  
44
  /** Hook called after release - disable rollback */
45
  afterRelease(): void;
46
}
47
```
48

49
### Repository Validation
50

51
Methods for validating Git repository state and requirements.
52

53
```javascript { .api }
54
/**
55
 * Check if current branch matches required branch pattern
56
 * @param requiredBranch - Branch pattern or array of patterns (supports ! negation)
57
 * @returns Promise resolving to boolean
58
 */
59
isRequiredBranch(requiredBranch?: string | string[]): Promise<boolean>;
60

61
/**
62
 * Check if current branch has upstream tracking
63
 * @returns Promise resolving to boolean
64
 */
65
hasUpstreamBranch(): Promise<boolean>;
66

67
/**
68
 * Check if Git tag exists
69
 * @param tag - Tag name to check
70
 * @returns Promise resolving to boolean
71
 */
72
tagExists(tag: string): Promise<boolean>;
73

74
/**
75
 * Check if working directory is clean (no uncommitted changes)
76
 * @returns Promise resolving to boolean  
77
 */
78
isWorkingDirClean(): Promise<boolean>;
79

80
/**
81
 * Get number of commits since latest tag
82
 * @param commitsPath - Optional path to filter commits
83
 * @returns Promise resolving to commit count
84
 */
85
getCommitsSinceLatestTag(commitsPath?: string): Promise<number>;
86
```
87

88
### File Staging Operations
89

90
Methods for staging files and directories before commits.
91

92
```javascript { .api }
93
/**
94
 * Stage specific files for commit
95
 * @param files - File path or array of file paths to stage
96
 * @returns Promise that resolves when staging completes
97
 */
98
stage(files: string | string[]): Promise<void>;
99

100
/**
101
 * Stage entire directory for commit
102
 * @param options - Staging options
103
 * @returns Promise that resolves when staging completes
104
 */
105
stageDir(options?: StageDirOptions): Promise<void>;
106

107
interface StageDirOptions {
108
  /** Base directory to stage (default: ".") */
109
  baseDir?: string;
110
}
111

112
/**
113
 * Reset/unstage files
114
 * @param files - File path or array of file paths to reset
115
 * @returns Promise that resolves when reset completes
116
 */
117
reset(files: string | string[]): Promise<void>;
118

119
/**
120
 * Get Git status showing staged/unstaged changes
121
 * @returns Promise resolving to Git status output
122
 */
123
status(): Promise<string>;
124
```
125

126
### Commit Operations
127

128
Methods for creating Git commits with customizable messages and arguments.
129

130
```javascript { .api }
131
/**
132
 * Create Git commit
133
 * @param options - Commit options
134
 * @returns Promise that resolves when commit completes
135
 */
136
commit(options?: CommitOptions): Promise<void>;
137

138
interface CommitOptions {
139
  /** Commit message template (supports context interpolation) */
140
  message?: string;
141
  /** Additional arguments to pass to git commit */
142
  args?: string[];
143
}
144
```
145

146
### Tag Operations
147

148
Methods for creating and managing Git tags.
149

150
```javascript { .api }
151
/**
152
 * Create Git tag with annotation
153
 * @param options - Tag options
154
 * @returns Promise that resolves when tag is created
155
 */
156
tag(options?: TagOptions): Promise<void>;
157

158
interface TagOptions {
159
  /** Tag name (defaults to context tagName) */
160
  name?: string;
161
  /** Tag annotation template (supports context interpolation) */
162
  annotation?: string;
163
  /** Additional arguments to pass to git tag */
164
  args?: string[];
165
}
166
```
167

168
### Push Operations
169

170
Methods for pushing commits and tags to remote repositories.
171

172
```javascript { .api }
173
/**
174
 * Push commits and tags to remote repository
175
 * @param options - Push options
176
 * @returns Promise that resolves when push completes
177
 */
178
push(options?: PushOptions): Promise<void>;
179

180
/**
181
 * Get upstream arguments for push command
182
 * @param pushRepo - Repository URL or name
183
 * @returns Promise resolving to array of push arguments
184
 */
185
getUpstreamArgs(pushRepo?: string): Promise<string[]>;
186

187
/**
188
 * Get remote repository URL
189
 * @returns Promise resolving to remote URL
190
 */
191
getRemoteUrl(): Promise<string>;
192

193
/**
194
 * Get remote name for current branch
195
 * @returns Promise resolving to remote name
196
 */
197
getRemote(): Promise<string>;
198

199
/**
200
 * Get remote name for specific branch
201
 * @param branch - Branch name
202
 * @returns Promise resolving to remote name
203
 */
204
getRemoteForBranch(branch: string): Promise<string>;
205

206
/**
207
 * Get current Git branch name
208
 * @returns Promise resolving to branch name
209
 */
210
getBranchName(): Promise<string>;
211

212
/**
213
 * Get latest Git tag name
214
 * @returns Promise resolving to tag name
215
 */
216
getLatestTagName(): Promise<string>;
217

218
/**
219
 * Get second latest Git tag name
220
 * @param latestTag - Latest tag name
221
 * @returns Promise resolving to second latest tag name
222
 */
223
getSecondLatestTagName(latestTag: string): Promise<string>;
224

225
/**
226
 * Fetch from remote repository
227
 * @param remoteUrl - Remote URL to fetch from
228
 * @returns Promise that resolves when fetch completes
229
 */
230
fetch(remoteUrl: string): Promise<void>;
231

232
/**
233
 * Check if string is a remote name vs URL
234
 * @param remoteUrlOrName - String to check
235
 * @returns Boolean indicating if it's a remote name
236
 */
237
isRemoteName(remoteUrlOrName: string): boolean;
238

239
/**
240
 * Rollback tag push on remote (used in error scenarios)
241
 * @returns Promise that resolves when rollback completes
242
 */
243
rollbackTagPush(): Promise<void>;
244

245
interface PushOptions {
246
  /** Additional arguments to pass to git push */
247
  args?: string[];
248
}
249
```
250

251
### Git Configuration Options
252

253
Complete configuration options for the Git plugin.
254

255
```javascript { .api }
256
interface GitOptions {
257
  /** Enable/disable Git plugin entirely */
258
  disabled?: boolean;
259
  
260
  /** Require clean working directory before release */
261
  requireCleanWorkingDir?: boolean;
262
  
263
  /** Required branch pattern (string or array, supports ! for negation) */
264
  requireBranch?: string | string[];
265
  
266
  /** Require upstream branch to be configured */
267
  requireUpstream?: boolean;
268
  
269
  /** Require commits since last tag */
270
  requireCommits?: boolean;
271
  
272
  /** Fail if no commits found (when requireCommits is true) */
273
  requireCommitsFail?: boolean;
274
  
275
  /** Path to check for commits (when requireCommits is true) */
276
  commitsPath?: string;
277
  
278
  /** Include untracked files when staging directory */
279
  addUntrackedFiles?: boolean;
280
  
281
  /** Enable commit creation */
282
  commit?: boolean;
283
  
284
  /** Commit message template (supports ${version}, ${changelog}, etc.) */
285
  commitMessage?: string;
286
  
287
  /** Additional arguments for git commit command */
288
  commitArgs?: string[];
289
  
290
  /** Enable Git tag creation */
291
  tag?: boolean;
292
  
293
  /** Tag annotation template (supports ${version}, ${changelog}, etc.) */
294
  tagAnnotation?: string;
295
  
296
  /** Additional arguments for git tag command */
297
  tagArgs?: string[];
298
  
299
  /** Enable push to remote repository */
300
  push?: boolean;
301
  
302
  /** Remote repository URL or name for push */
303
  pushRepo?: string;
304
  
305
  /** Additional arguments for git push command */
306
  pushArgs?: string[];
307
  
308
  /** Pattern to match tags for getLatestTagFromAllRefs */
309
  tagMatch?: string;
310
  
311
  /** Get latest tag from all refs instead of just current branch */
312
  getLatestTagFromAllRefs?: boolean;
313
}
314
```
315

316
**Usage Examples:**
317

318
```javascript
319
// Basic Git operations configuration
320
const result = await runTasks({
321
  git: {
322
    requireCleanWorkingDir: true,
323
    commit: true,
324
    commitMessage: "Release ${version}",
325
    tag: true,
326
    tagAnnotation: "Release ${version}\\n\\n${changelog}",
327
    push: true
328
  }
329
});
330

331
// Advanced Git configuration with branch requirements
332
const result = await runTasks({
333
  git: {
334
    requireBranch: ["main", "master"],          // Must be on main or master
335
    requireUpstream: true,                      // Must have upstream configured
336
    requireCommits: true,                       // Must have commits since last tag
337
    addUntrackedFiles: true,                    // Include untracked files
338
    commit: true,
339
    commitMessage: "chore: release v${version}",
340
    commitArgs: ["--no-verify"],               // Skip pre-commit hooks
341
    tag: true,
342
    tagAnnotation: "Release ${version}",
343
    tagArgs: ["--sign"],                       // GPG sign tags
344
    push: true,
345
    pushArgs: ["--follow-tags"]                // Push tags with commits
346
  }
347
});
348

349
// Git configuration for feature branch releases
350
const result = await runTasks({
351
  git: {
352
    requireBranch: "!main",                    // Must NOT be on main branch
353
    requireUpstream: false,                    // Don't require upstream
354
    commit: true,
355
    commitMessage: "feat: ${version}",
356
    tag: false,                                // Don't create tags
357
    push: true,
358
    pushRepo: "origin"                         // Push to origin
359
  }
360
});
361
```
362

363
### Git Context Variables
364

365
The Git plugin provides context variables for templates:
366

367
- `${version}` - New release version
368
- `${latestVersion}` - Previous version  
369
- `${changelog}` - Generated changelog
370
- `${tagName}` - Computed tag name
371
- `${name}` - Package/project name
372
- `${repo.remote}` - Remote repository URL
373
- `${repo.owner}` - Repository owner
374
- `${repo.repository}` - Repository name
375

376
### Error Handling and Rollback
377

378
The Git plugin includes sophisticated error handling:
379

380
- **Rollback on Interrupt**: Automatically rollbacks changes on SIGINT
381
- **Tag Rollback**: Removes local and remote tags on push failure
382
- **Commit Reset**: Resets commits on error (when enabled)
383
- **Working Directory Protection**: Validates clean state before operations
384

385
### Branch Pattern Matching
386

387
Branch requirements support flexible patterns:
388

389
```javascript
390
{
391
  "git": {
392
    "requireBranch": "main"              // Exact match
393
  }
394
}
395

396
{
397
  "git": {
398
    "requireBranch": ["main", "master"]  // Multiple allowed branches
399
  }
400
}
401

402
{
403
  "git": {
404
    "requireBranch": "!main"             // Must NOT be main
405
  }
406
}
407

408
{
409
  "git": {
410
    "requireBranch": ["develop", "!temp-*"]  // Must be develop, not temp-*
411
  }
412
}
413
```