/ork:commit

/ork:commit
/ork:commit fix typo in auth module

COMMIT_MSG = "$ARGUMENTS"  # Optional commit message, e.g., "fix typo in auth module"
# If provided, use as commit message. If empty, generate from staged changes.
# $ARGUMENTS[0] is the first token (CC 2.1.59 indexed access)

# CRITICAL: Verify we're not on dev/main
BRANCH=$(git branch --show-current)
if [[ "$BRANCH" == "dev" || "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
  echo "STOP! Cannot commit directly to $BRANCH"
  echo "Create a feature branch: git checkout -b issue/<number>-<description>"
  exit 1
fi

# Backend (Python)
poetry run ruff format --check app/
poetry run ruff check app/
poetry run mypy app/

# Frontend (Node.js)
npm run format:check
npm run lint
npm run typecheck

git status
git diff --staged   # What will be committed
git diff            # Unstaged changes

# Stage files
git add <files>
# Or all: git add .

# Commit with conventional format (with agent attribution if ledger exists)
git commit -m "<type>(#<issue>): <brief description>

- [Change 1]
- [Change 2]

Agents Involved:
  backend-system-architect — API design + data models (2m14s)
  security-auditor — Dependency audit (0m42s)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: ork:backend-system-architect <noreply@orchestkit.dev>
Co-Authored-By: ork:security-auditor <noreply@orchestkit.dev>"

# Verify
git log -1 --stat

Write(".claude/chain/committed.json", JSON.stringify({
  "phase": "commit", "sha": "<commit-sha>",
  "message": "<commit-message>", "branch": "<branch>",
  "files": [<staged-files>]
}))

git add . && git commit -m "fix(#123): Fix typo in error message

Co-Authored-By: Claude <noreply@anthropic.com>"

[x] Does ONE logical thing
[x] Leaves the codebase in a working state (tests pass)
[x] Commit message doesn't need "and" in the title
[x] Can be reverted independently without breaking other features
[x] A reviewer can understand the full change without external context

# ATOMIC: Related files in same domain
src/auth/login.ts
src/auth/login.test.ts
src/auth/types.ts

# NOT ATOMIC: Unrelated directories
src/auth/login.ts        ← auth feature
src/billing/invoice.ts   ← billing feature
config/webpack.config.js ← build config

# NOT ATOMIC: feat + fix in one commit
feat: Add user dashboard
fix: Resolve login timeout     ← separate commit

# NOT ATOMIC: feat + chore in one commit
feat: Add API caching
chore: Update eslint config     ← separate commit

# OK: 15 files, all test fixtures for one feature
tests/fixtures/user-*.json (15 files)

# NOT OK: 12 files across 6 unrelated modules

# Fails "and" test → split it
"Add user authentication AND fix logging format"

# Passes "and" test → atomic
"Add JWT token validation for login endpoint"

# Mixed commit spanning unrelated areas
git add src/auth/login.ts \
        src/billing/invoice.ts \
        config/webpack.config.js
git commit -m "feat: Add login AND fix invoice AND update webpack"
# Three unrelated changes - can't revert independently!

# Commit 1: Auth feature + its tests (related)
git add src/auth/login.ts src/auth/login.test.ts
git commit -m "feat(#123): Add JWT token validation for login endpoint"

# Commit 2: Billing feature + its tests (related)
git add src/billing/invoice.ts src/billing/invoice.test.ts
git commit -m "feat(#124): Add invoice generation service"

# Commit 3: Config change (separate concern)
git add config/webpack.config.js
git commit -m "chore: Update webpack for tree shaking"

# Issue-linked (preferred)
issue/<number>-<brief-description>
issue/123-add-user-auth

# Type-based (when no issue exists)
feature/<description>
fix/<description>
hotfix/<description>

git checkout main
git commit -m "quick fix"
git push origin main

git checkout -b fix/issue-123
git commit -m "fix(#123): Resolve auth bug"
git push -u origin fix/issue-123
gh pr create --base main

# Stage changes interactively
git add -p

# Options at each hunk:
# y - stage this hunk
# n - skip this hunk
# s - split into smaller hunks (if hunk has gaps)
# e - manually edit the hunk boundaries
# q - quit, leave remaining unstaged

# Review what's staged vs unstaged
git diff --staged    # Will be committed
git diff             # Won't be committed

# Commit the staged portion
git commit -m "feat(#123): Add user validation"

# Repeat for next logical change
git add -p
git commit -m "fix(#456): Resolve timeout in auth"

# Stage only auth-related files
git add src/auth/login.ts src/auth/login.test.ts
git commit -m "feat(#123): Add login validation"

# Stage only billing-related files
git add src/billing/invoice.ts src/billing/invoice.test.ts
git commit -m "feat(#124): Add invoice generation"

# Stash everything
git stash

# Apply and stage only what you need
git stash pop
git add -p  # Stage only feature A
git stash   # Re-stash the rest
git commit -m "feat: Feature A"

# Recover remaining changes
git stash pop
git add -p  # Stage feature B
git commit -m "feat: Feature B"

# Step 1: Format first (separate commit)
npx prettier --write src/
git add -A
git commit -m "style: Format files with prettier"

# Step 2: Now make your logical changes
# ... edit files ...
git add -p
git commit -m "feat(#123): Add user dashboard"

# Staging all files including mixed changes
git add .
git commit -m "feat: Add login and fix billing and update config"
# Unreviewable, can't revert parts!

# Stage auth changes interactively
git add -p src/auth/login.ts
# y - stage login validation hunks
# n - skip other hunks
git add src/auth/login.test.ts
git commit -m "feat(#123): Add login validation"

# Stage billing changes interactively
git add -p src/billing/invoice.ts
git add src/billing/invoice.test.ts
git commit -m "fix(#456): Resolve invoice calculation bug"

# Stage config separately
git add config/webpack.config.js
git commit -m "chore: Update webpack config"

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

[optional body]

[optional footer]
Co-Authored-By: Claude <noreply@anthropic.com>

# Issue reference (preferred)
feat(#123): Add user authentication

# Module name
fix(auth): Resolve token expiration

# No scope (acceptable for small changes)
chore: Update dependencies

# With ! marker (bumps MAJOR)
feat(api)!: Change authentication endpoint structure

# With footer
feat(api): Change auth endpoints

BREAKING CHANGE: /api/auth/login now requires email instead of username

[x] Imperative mood ("Add feature" not "Added feature")
[x] No period at end
[x] < 72 characters (< 50 preferred)
[x] Lowercase after colon
[x] Meaningful — describes WHY, not just WHAT

Fixed the bug.                          # Past tense, period, no type
feat: stuff                             # Vague
feat: Add user authentication and fix billing  # Two concerns
FEAT: Add Auth                          # Uppercase

feat(#123): Add JWT token validation for login
fix(#456): Resolve race condition in payment processing
refactor: Extract database connection pool to shared module

git commit -m "$(cat <<'EOF'
feat(#123): Add rate limiting to API endpoints

Applied token bucket algorithm with 100 req/min per user.
Redis-backed for distributed deployments.

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

# Squash WIP commits before pushing
git rebase -i HEAD~3

# In the editor:
pick abc1234 feat(#123): Add user validation
fixup def5678 WIP: more validation
fixup ghi9012 fix typo

git commit --fixup HEAD        # Auto-squash into previous
git commit --fixup HEAD~2      # Auto-squash into specific commit

# Before pushing, auto-squash all fixups
git rebase -i --autosquash HEAD~5

abc1234 WIP
def5678 fix
ghi9012 more fixes

git rebase -i --autosquash HEAD~4
# Result: One clean commit
abc1234 feat(#123): Add user validation with edge case handling

# Issue number in scope
git commit -m "fix(#42): resolve null pointer in auth handler"

# Issue number in body
git commit -m "feat(auth): add OAuth2 support

Implements #42"

# Closing reference
git commit -m "fix(api): validate input length

Closes #42"

# No issue reference on an issue branch
git commit -m "fix: resolve null pointer in auth handler"

# Issue number without # prefix
git commit -m "fix(42): resolve null pointer"

# On branch: issue/42-fix-auth
# No issue reference - breaks traceability!
git commit -m "fix: resolve null pointer in auth handler"

# On branch: issue/42-fix-auth
# Issue number in scope
git commit -m "fix(#42): resolve null pointer in auth handler"

# Or in body
git commit -m "fix(auth): resolve null pointer in auth handler

Fixes #42"

git fetch origin
git rebase origin/main

# If conflicts: resolve, stage, continue
git add <resolved-files>
git rebase --continue

# If rebase goes wrong
git rebase --abort

# SAFE: Force push your own feature branch
git push --force-with-lease origin issue/123-feature

# DANGEROUS: Never force push protected branches
git push --force origin main  # NEVER DO THIS

git checkout feature-branch
git merge origin/main  # Creates noisy merge commits

git checkout feature-branch
git rebase origin/main
git push --force-with-lease

git checkout feature/auth-service
git merge main  # Creates unnecessary merge commit

# Rebase dependent branches in order:
git checkout feature/auth-service
git rebase feature/auth-base
git push --force-with-lease

git checkout feature/auth-ui
git rebase feature/auth-service
git push --force-with-lease

git checkout main && git pull origin main

# Retarget PR #2 to main
gh pr edit 102 --base main

# Rebase PR #2 on updated main
git checkout feature/auth-service
git rebase main
git push --force-with-lease

# One 1500-line PR that takes days to review
git checkout -b feature/auth
gh pr create --title "feat: Add complete auth system"

# PR 1: User model (base) — targets main
git checkout -b feature/auth-base
gh pr create --base main --title "feat(#100): Add User model [1/3]"

# PR 2: Auth service — targets PR 1's branch
git checkout -b feature/auth-service
gh pr create --base feature/auth-base --title "feat(#100): Add auth service [2/3]"

# PR 3: Login UI — targets PR 2's branch
git checkout -b feature/auth-ui
gh pr create --base feature/auth-service --title "feat(#100): Add login UI [3/3]"

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

[optional body]

[optional footer(s)]

feat!: drop support for Node 14

BREAKING CHANGE: Node 14 is no longer supported

feat(#123): add user profile page

- Create ProfilePage component
- Add profile API endpoint
- Include unit tests

Co-Authored-By: Claude <noreply@anthropic.com>

fix(#456): prevent XSS in comment display

Sanitize HTML in user comments before rendering.

Co-Authored-By: Claude <noreply@anthropic.com>

# Save work to new branch
git checkout -b issue/<number>-<description>

# Reset original branch
git checkout dev
git reset --hard origin/dev

# Return to feature branch
git checkout issue/<number>-<description>

git reset --soft HEAD~1

git reset --hard HEAD~1

# Fix message only
git commit --amend -m "new message"

# Add forgotten files
git add forgotten-file.txt
git commit --amend --no-edit

git revert <commit-hash>
git push

git restore --staged <file>

# Single file
git restore <file>

# All files
git restore .