# Committing Changes

> Commit via feature branch + PR + git hooks; never push main, never merge.

- Skill: `swell-agents/committing-changes` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add swell-agents/committing-changes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/swell-agents/committing-changes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: swell-agents (https://skillmd.com/u/swell-agents)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/swell-agents/committing-changes

---


## Workflow

1. **Install hooks** (once per repo).
   From inside the repo, run the installer that ships with this skill:
   ```
   bash <skills>/committing-changes/scripts/install-hooks.sh
   ```
   This copies `commit-msg` and `pre-push` into `.git/hooks/` and makes them executable. Idempotent.

   Then install the PR-size CI workflow:
   ```
   bash <skills>/committing-changes/scripts/install-pr-size-workflow.sh
   ```
   This drops `.github/workflows/pr-size.yml` and appends `.gitattributes` exclusions. Idempotent.

2. **Branch check.** If on `main`, switch to a feature branch:
   ```
   git checkout -b <type>/<description>
   ```
   Valid `type` prefixes: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `infra`, `ai-native`.

3. **Auto-fix before commit.** Run the project's linter/formatter (e.g., `ruff format && ruff check` for Python, `golangci-lint run` for Go, `forge fmt && solhint` for Solidity). The pre-commit hook (if installed) runs the project's full quality gate.

4. **Commit & push.**
   ```
   git add <specific paths>
   git commit -m "<subject conforming to rules below>"
   git push -u origin <branch>
   ```

5. **Sync with main.**
   ```
   git fetch origin main
   git merge origin/main
   ```
   Resolve conflicts; commit the merge; push.

6. **PR creation** (first push only).
   ```
   gh pr list --head <branch>
   gh pr create --fill   # if no PR exists yet
   ```

7. **Branch cleanup** (after the user has merged).
   ```
   git fetch --prune
   git branch --merged main | grep -v '^\*\|main' | xargs -r git branch -d
   ```

## Rules

- **Never push directly to `main`.** Always feature branches + PRs. The `pre-push` hook blocks this.
- **Never merge branches or PRs.** Always let the user merge.
- **Never force-push.** No `--force`, no `--force-with-lease`. Create new commits instead.
- **One logical change per commit.**
- **PR size**: ≤1000 changed lines per PR (excluding tests, docs, lockfiles, generated). Enforced by `.github/workflows/pr-size.yml`.
- **Commit-message subject** (enforced by `commit-msg` hook):
  - Capital start (imperative mood: "Add", "Fix", "Refactor", not "added"/"adds").
  - ≤ 72 chars.
  - No trailing period.
  - No `Co-Authored-By:` lines.

## Why this discipline

Each rule traces to a specific failure mode:
- *No direct push to main* → no broken `main`, every change is reviewable.
- *No agent-side merge* → the human keeps the merge decision; agents never close the loop unilaterally.
- *No force-push* → preserves history; reviewers can trust commit hashes.
- *One logical change per commit* → bisect works; reverts are surgical.
- *Subject rules* → consistent log readability; no noisy attribution lines.

## Cross-references

- `shell-discipline` — issue these `git`/`gh` commands one per call, no `&&` chains.
- `engineering-philosophy` — "Small Steps" and "Investigate, Don't Mask" map directly to one-logical-change-per-commit and don't-disable-failing-hooks.

## Reference

- [scripts/commit-msg](scripts/commit-msg) — subject-line rules enforcer.
- [scripts/pre-commit](scripts/pre-commit) — runs project's lint/format/test before commit.
- [scripts/pre-push](scripts/pre-push) — blocks direct push to `main`/`master`.
- [scripts/install-hooks.sh](scripts/install-hooks.sh) — idempotent installer.
- [templates/pr-size.yml](templates/pr-size.yml) — GitHub Actions workflow that labels PR size and fails when >1000 changed lines (excluding tests, docs, lockfiles, generated).
- [templates/gitattributes.example](templates/gitattributes.example) — `linguist-generated`/`linguist-vendored` entries appended to `.gitattributes` so GitHub collapses generated files in PR diffs.
- [scripts/install-pr-size-workflow.sh](scripts/install-pr-size-workflow.sh) — idempotent installer for the workflow + `.gitattributes` block.
- [reference/commit-md-original.md](reference/commit-md-original.md) — original Claude-Code `commit.md` command verbatim.
- [reference/git-rule.md](reference/git-rule.md) — original `rules/git.md` verbatim.
- [reference/hook-troubleshooting.md](reference/hook-troubleshooting.md) — common failure modes + fixes.