Git Conventions

Conventional Commits

All commits follow the Conventional Commits format:

type(scope): description

Types

Type	When to use
`feat`	New feature, component, section, or route
`fix`	Bug fix or correction
`refactor`	Code restructuring with no behaviour change
`style`	CSS/visual changes, formatting, whitespace
`docs`	Documentation updates
`chore`	Tooling, config, dependencies, non-code maintenance
`test`	Adding or updating tests

Scopes

Use the most specific scope that applies. Scopes are platform-specific — the active agent defines appropriate scopes for the project type.

Theme projects: tokens, snippets, blocks, sections, templates, layout, locales, config, assets, docs

Hydrogen projects: components, routes, graphql, styles, sanity, lib, config, docs

Omit the scope if the change spans many areas.

Rules

Lowercase description, imperative mood (“add”, “fix”, “update” — not “added”, “fixes”)
Under 72 characters for the subject line
Focus on why the change was made, not what files were touched
Add a body (blank line after subject) only when non-obvious

Examples

feat(sections): add hero banner section with video background
fix(components): correct price formatting for multi-currency
style(tokens): update brand colour values from Figma refresh
refactor(routes): extract cart logic into shared loader
docs: update CONVENTIONS.md with new component APIs
chore: update dependencies via maintenance command

Branching

Never commit directly to main. Always work on a feature branch.
Branch naming: feature/description, fix/description, chore/description
Keep branches focused — one feature or fix per branch

Using the Commit Command

The /commit command automates the commit workflow:

commit

It reviews your changes, determines the correct type and scope, drafts the message following these conventions, and presents it for approval before committing. It is automatically suggested after commands that produce file changes.