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"
  }
}

Resolving a merge or rebase conflict

Resolve by intent, traced back to each side's primary source, never by picking lines that look plausible.

1. See the current state. git status, git log --oneline --graph -20, and the conflicting files. Know which operation you are in the middle of, a merge or a rebase, before touching anything.
2. Find the primary source for each side. Read the commit messages, the PR, the issue. Understand deeply why each change was made and what it was for. A conflict is two intents colliding, and you cannot resolve it while you only know one.
3. Resolve each hunk. Preserve both intents where possible. Where they are genuinely incompatible, pick the one matching the merge's stated goal and note the trade-off. Do not invent new behaviour to bridge them. Always resolve, never --abort.
4. Run the checks. ./buddy lint, ./buddy typecheck, ./buddy test. In this framework two conflict classes survive a clean textual merge and only show up here: a model changed on both sides, where the generated migrations diverged and one has to be regenerated, and a registry file (app/Routes.ts, app/Events.ts, app/Middleware.ts) where a dropped entry fails silently rather than failing to compile.
5. Finish the operation. Stage everything and commit, or continue the rebase until every commit is replayed.

Credit: adapted from Matt Pocock's resolving-merge-conflicts skill (MIT), https://github.com/mattpocock/skills.

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