Git Workflow

Conventional Commit Format

# BAD: vague, no type
git commit -m "changes"

# GOOD: clear type, scope, imperative mood
git commit -m "feat(auth): add OAuth2 login flow"
git commit -m "fix(api): handle null response in getUserData"
git commit -m "docs(readme): update installation steps"

Format: type(scope): description

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Breaking changes:

git commit -m "feat(api)!: remove deprecated v1 endpoints"
# Or in body:
git commit -m "feat(api): migrate to v2 endpoints

BREAKING CHANGE: v1 endpoints removed, use v2"

Setup Commit Linting

# Install commitlint
npm install --save-dev @commitlint/config-conventional @commitlint/cli

# Create config
cat > commitlint.config.js  .github/CODEOWNERS  lefthook.yml <<'EOF'
pre-commit:
  parallel: true
  commands:
    lint:
      glob: "*.{js,ts}"
      run: eslint --fix {staged_files}
    format:
      glob: "*.{js,ts,json,md}"
      run: prettier --write {staged_files}
    types:
      glob: "*.{ts,tsx}"
      run: tsc --noEmit

commit-msg:
  commands:
    commitlint:
      run: npx commitlint --edit {1}

pre-push:
  commands:
    test:
      run: npm test
    check-secrets:
      run: gitleaks detect --no-git --verbose
EOF

# Install hooks
lefthook install

Branch Strategies

Trunk-Based Development (Recommended)

# 1. Create short-lived feature branch
git checkout -b feat/user-profile

# 2. Work in small increments (1-2 days max)
git commit -m "feat(profile): add avatar upload"
git commit -m "test(profile): add avatar validation tests"

# 3. Rebase daily
git fetch origin
git rebase origin/main

# 4. Open PR when ready (same day or next day)
gh pr create --title "Add user profile avatar upload"

# 5. Squash merge to main
gh pr merge --squash

Git Flow (Complex Release Cycles)

# Long-lived branches: main, develop
# Supporting: feature/*, release/*, hotfix/*

# Start feature
git checkout develop
git checkout -b feature/payment-integration

# Finish feature
git checkout develop
git merge --no-ff feature/payment-integration
git branch -d feature/payment-integration

# Create release branch
git checkout -b release/1.2.0 develop
# Fix bugs in release/1.2.0

# Merge to main and develop
git checkout main
git merge --no-ff release/1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git checkout develop
git merge --no-ff release/1.2.0
git branch -d release/1.2.0

Only use Git Flow if:

• Multiple versions in production (e.g., SaaS with customer-specific deployments)
• Regulated industry requiring formal release process
• Large team (50+) with parallel release tracks

Troubleshooting

# Lost commits after reset
git reflog
git cherry-pick abc123  # Restore lost commit

# Committed to wrong branch
git log  # Copy commit hash
git checkout correct-branch
git cherry-pick abc123
git checkout wrong-branch
git reset --hard HEAD~1  # Remove from wrong branch

# Remove file from history (leaked secret)
git filter-repo --path secrets.env --invert-paths
# Note: force push required, coordinate with team

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

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

# Undo last commit (discard changes - CAREFUL)
git reset --hard HEAD~1

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: medy-gribkov
• Source: medy-gribkov/arcana
• License: Apache-2.0
• Homepage: https://www.npmjs.com/package/@sporesec/arcana

Install and usage instructions live in the source repository linked above.