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) ```typescript 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 ```typescript 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`, `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: ```typescript { 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 `gitCredentialEnvironment({ url, username, password })` from `@stacksjs/git` returns environment variables for a child Git process. Pass the caller's base environment as its second argument, then merge the result after that base. Existing runtime Git configuration is preserved. The HTTP(S) URL must identify one repository without userinfo, query or fragment. The helper supplies credentials only for that protocol, host and repository path, refuses redirects for that URL, disables interactive prompts, and writes no credential or Git config file. Never log the returned environment. Use a credential scoped to the repository and the operation; this helper does not grant server permissions. ```typescript import { gitCredentialEnvironment } from '@stacksjs/git' const child = Bun.spawn(['git', 'ls-remote', 'origin'], { cwd: workspace, env: { ...process.env, ...gitCredentialEnvironment({ url: repositoryUrl, username: 'x-access-token', password: jobToken }, process.env) }, }) ``` The child and its descendants receive the credential. Use this for trusted job steps, never to transfer a host credential into an isolated guest. `buddy release` atomically pushes its commit and version tag to the branch's configured upstream remote and branch. A worktree on `codex/example` tracking `origin/main` releases to `origin/main`; it does not create a remote feature branch. Without an upstream it uses `origin` and the current branch. Detached HEAD, incomplete upstreams, local-only remotes and non-branch or ambiguous upstreams are rejected before the version bump. ```typescript import { isGitClean } from '@stacksjs/utils' function isGitClean(): boolean // Uses: git diff-index --quiet HEAD -- // Returns true if clean, false if dirty ``` ## CLI Commands ```bash 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 ```typescript 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 ```typescript 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 ```json { "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 ### Setting up pre-commit checks The current Matt Pocock `setup-pre-commit` workflow maps to Stacks' existing hooks, rather than adding Husky, lint-staged, or Prettier. Inspect `package.json`, the installed `better-dx` tooling, `config/git.ts`, and CI. Keep staged formatting on pickier and run the repository's actual typecheck and test commands at the appropriate gate. Preserve existing hook actions. Prove a deliberate temporary violation fails, restore it, and prove the valid state passes. Do not create a commit merely to exercise a hook. See [NOTICE.md](NOTICE.md) and [the Stacks adaptation rules](../stacks-flow/ENGINEERING.md). - **`@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`