Stacks Git

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

Commit Scopes

ci, deps, dx, release, docs, test, core, actions, arrays, auth, build, cache, cli, cloud, collections, config, database, datetime, errors, git, lint, 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
// Uses: git diff-index --quiet HEAD --
// Returns true if clean, false if dirty

CLI Commands

buddy commit                    # Interactive conventional commit
buddy commit --verbose
buddy commit -p [project]       # Target specific project

buddy changelog                 # Generate changelog
buddy changelog --quiet
buddy changelog --dry-run       # Preview without writing
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