Git Workflow

Git Workflow

Enforces git best practices for consistent, traceable version control.

When to Use This Skill

• Creating commits (use conventional commit format)
• Creating branches (use standard naming)
• Opening or reviewing Pull Requests
• Auditing git history for compliance
• Setting up git hooks

Conventional Commits

Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

Breaking Changes

Add ! after type or include BREAKING CHANGE: in footer:

feat(api)!: change response format

BREAKING CHANGE: Response now returns array instead of object

Scope

Use component or module name:

• feat(qig-backend): add Fisher-Rao distance
• fix(client): handle empty state
• docs(skills): add git-workflow

Branch Naming

Format

<type>/<ticket>-<description>

Examples

Protected Branches

• main - Production-ready code
• develop - Integration branch
• release/* - Release candidates

Pull Request Hygiene

PR Title

Follow conventional commit format:

feat(auth): implement OAuth2 login flow

PR Description Template

## Summary
Brief description of changes.

## Changes
- Added X
- Modified Y
- Removed Z

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Related Issues
Closes #123

PR Checklist

• Title follows conventional commit format
• Description explains what and why
• Tests added/updated
• Documentation updated
• No merge conflicts
• CI passes
• Reviewers assigned

Gitflow Workflow

main ─────●─────────────●─────────────●───
          │             ↑             ↑
          │      release/v1.0    release/v1.1
          │             │             │
develop ──●──●──●──●────●──●──●──●────●───
             │     │       │     │
          feature/a  feature/b  feature/c

Branch Lifecycle

1. Create feature branch from develop
2. Work on feature, commit frequently
3. Open PR to develop
4. After review, merge to develop
5. Create release/* branch for release prep
6. Merge release to main and tag
7. Merge release back to develop

Git Hooks

Pre-commit

#!/bin/bash
# .git/hooks/pre-commit

# Run linting
npm run lint || exit 1

# Run type check
npm run check || exit 1

# Run purity scan
python3 scripts/qig_purity_scan.py || exit 1

Commit-msg

#!/bin/bash
# .git/hooks/commit-msg

# Validate conventional commit format
commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore|ci|build)(\(.+\))?(!)?: .{1,72}'

if ! grep -qE "$commit_regex" "$1"; then
    echo "ERROR: Commit message does not follow conventional commit format"
    echo "Format: <type>(<scope>): <description>"
    exit 1
fi

Validation Commands

# Check recent commits follow convention
git log --oneline -10

# Validate branch name
git branch --show-current | grep -E '^(feature|fix|hotfix|release|docs)/'

# Check for merge conflicts
git diff --check

# Verify clean working tree
git status --porcelain

Common Issues

Commit Message Too Long

Keep subject line under 72 characters. Use body for details:

feat(api): add user authentication endpoint

Implements JWT-based authentication with refresh tokens.
Includes rate limiting and brute force protection.

Closes #123

Merge Conflicts

1. Pull latest from target branch
2. Resolve conflicts locally
3. Test after resolution
4. Commit with clear message

Accidental Commit to Main

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Create proper branch
git checkout -b feature/proper-branch

# Commit and push
git commit -m "feat: proper commit"
git push -u origin feature/proper-branch

Converted and distributed by TomeVault — claim your Tome and manage your conversions.