| name | stacks-git |
| description | Use when working with git in a Stacks application — commit conventions, git hooks, changelog generation, commit scopes/types, or GitHub API types. Covers @stacksjs/git, config/git.ts, config/commit.ts, and the git hooks system. |
| license | MIT |
| compatibility | Bun >= 1.3.0, TypeScript |
| allowed-tools | Read Edit Write Bash Grep Glob |
Stacks Git
Key Paths
- Core package:
storage/framework/core/git/
- Git config:
config/git.ts
- Commit config:
config/commit.ts
- Git hooks config:
storage/framework/core/git-hooks.config.ts
- Git utilities:
storage/framework/core/utils/src/git.ts
- Commit action:
storage/framework/core/actions/src/commit.ts
- Buddy commands:
storage/framework/core/buddy/src/commands/commit.ts, changelog.ts
- GitHub API types:
storage/framework/types/git.ts
- Core types:
storage/framework/core/types/src/git.ts
Git Configuration (config/git.ts)
interface GitOptions {
hooks: GitHooks
scopes: string[]
types: { value: string, name: string, emoji: string }[]
messages: {
type: string, scope: string, customScope: string, subject: string
body: string, breaking: string, footer: string, confirmCommit: string
}
}
Hooks
hooks: {
'pre-commit': 'lint-staged'
}
Commit Types
| Value | Emoji | Description |
|---|
| feat | ✨ | A new feature |
| fix | 🐛 | A bug fix |
| docs | 📝 | Documentation only changes |
| style | 💄 | Changes that don't affect meaning |
| refactor | ♻️ | Code change without fix or feature |
| perf | ⚡️ | Performance improvement |
| test | ✅ | Adding/adjusting tests |
| build | 📦️ | Build system or dependencies |
| ci | 🎡 | CI configuration changes |
| chore | 🔨 | Other changes not affecting src/test |
| revert | ⏪️ | Reverts previous commit |
Commit Scopes
ci, deps, dx, release, docs, test, core, actions, arrays, auth, build, cache, cli, cloud, collections, config, database, datetime, errors, git, lint, x-ray, modules, notifications, objects, path, realtime, router, buddy, security, server, storage, strings, tests, types, ui, utils
Commit Configuration (config/commit.ts)
Based on cz-git UserConfig:
{
rules: { 'scope-enum': [2, 'always', [...scopes]] },
prompt: {
useEmoji: false,
allowCustomScopes: true,
allowEmptyScopes: true,
allowBreakingChanges: ['feat', 'fix'],
breaklineNumber: 100,
breaklineChar: '|',
issuePrefixs: [{ value: 'closed', name: 'closed: ISSUES has been processed' }],
maxHeaderLength: Infinity,
maxSubjectLength: Infinity,
}
}
Git Utilities
import { isGitClean } from '@stacksjs/utils'
function isGitClean(): boolean
CLI Commands
buddy commit
buddy commit --verbose
buddy commit -p [project]
buddy changelog
buddy changelog --quiet
buddy changelog --dry-run
buddy changelog -p [project]
GitHub API Types
GitHubCommit
interface GitHubCommit {
sha: string
commit: {
author: { name: string, email: string, date: string }
committer: { name: string, email: string, date: string }
message: string
verification: { verified: boolean, reason: string }
}
url: string, html_url: string
author: { login: string, id: number, avatar_url: string }
}
WorkflowRun
interface WorkflowRun {
id: number, name: string, head_branch: string, head_sha: string
run_number: number, event: string, status: string, conclusion: string
workflow_id: number, created_at: string, updated_at: string
actor: { login: string, id: number }
run_attempt: number, run_started_at: string
jobs_url: string, logs_url: string, artifacts_url: string
head_commit: { id: string, message: string, timestamp: string }
}
Package Dependencies
{
"name": "@stacksjs/git",
"devDependencies": {
"@stacksjs/gitlint": "^0.1.5",
"@stacksjs/gitit": "^0.2.5",
"bun-git-hooks": "^0.3.1"
}
}
Gotchas
@stacksjs/git is mostly re-exports — actual functionality in @stacksjs/gitlint, @stacksjs/gitit, bun-git-hooks
- Pre-commit runs lint-staged — the only default hook
- Emoji disabled by default —
useEmoji: false but emoji mappings exist for each type
buddy commit runs npm run commit — delegates to commitizen/cz-git flow
- Scopes dynamically extended — component and function names merged into scopes at runtime
- Breaking changes only for feat/fix —
allowBreakingChanges: ['feat', 'fix']
- No max header length —
maxHeaderLength: Infinity
- Git hooks config re-exports —
git-hooks.config.ts just re-exports from config/git.ts