# Git

> git, commit message, Conventional Commits, feat/fix/chore/docs, branch name, branching, PR, pull request, opening a PR, PR review, code review of a diff, merge, rebase, push, AI attribution, Co-Authored-By. Use when creating a branch, writing a commit or PR body, reviewing a PR, or deciding how a change gets recorded in git.

- Skill: `htkoca/git` (Agent Skill)
- Install (CLI): `npx skillmds@latest add htkoca/git`
- Raw SKILL.md: https://api.skillmd.com/api/skills/htkoca/git/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: htkoca (https://skillmd.com/u/htkoca)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/htkoca/git

---


# Git

How change is recorded.

## Workflow

1. **Work on the branch defined for the task at hand.** Never push directly to `main`.
2. **Create new commits rather than amending.** Never force-push or skip hooks without explicit permission.
3. **Task PRs target their milestone branch; milestone PRs target the latest `main`.** Work outside a milestone stays on a feature branch and PRs only when explicitly asked.

## SSH agent timeouts

1. **Pushes and fetches occasionally time out.** The 1Password SSH agent backs the
   `github.com-*` host aliases, and it intermittently stalls — surfacing as
   `Operation timed out` on port 22, or `Please make sure you have the correct access
   rights and the repository exists`.
2. **This is expected and transient. Wait and retry first.** It is not a credential,
   permission, or connectivity fault, and it does not mean the remote, the key, or
   the repo is misconfigured.
3. **If it persists, fall back to a token-authenticated HTTPS push or fetch**, passing
   the URL explicitly on the command line:

   ```sh
   git push https://github.com/<owner>/<repo>.git HEAD:<branch>
   git fetch --prune https://github.com/<owner>/<repo>.git "+refs/heads/*:refs/remotes/origin/*"
   ```

   - The `gh auth git-credential` helper supplies the token. Never embed it in the
     URL — that leaks it into the reflog, config, and process list.
   - Match the active `gh` account to the repo owner first (`gh auth switch -u <account>`);
     the helper serves the active account's token, so a mismatch 404s on private repos.
4. **The fallback is temporary and per-command.** Never `git remote set-url` to HTTPS,
   never add a `url.*.insteadOf` rewrite, and never switch to `ssh.github.com:443`,
   regenerate keys, edit `~/.ssh/config`, or re-authenticate `gh`. The configured SSH
   remote stays exactly as it is; only the single command takes the detour.
5. **After an explicit-URL push, refresh the tracking refs.** Pushing to a URL does not
   update `refs/remotes/origin/*`, so the branch keeps reporting "ahead" despite being
   pushed. Run the `fetch` above to make `git status` accurate again.
6. **Commits are unaffected.** Local commits already succeeded; only the push is
   pending. Retry the push later rather than amending, resetting, or recommitting.

## Conventional Commits

1. All commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/):

   ```text
   <type>(<optional scope>): <imperative summary>
   ```

   - **Allowed types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
   - **Scopes** match the affected area: the surface (`home`), the layer (`templates`, `tokens`, `constants`), or the docs (`prd`, `docs`). Omit when global.
   - **Subject:** ≤ 72 characters, lowercase, no trailing period.
   - **Body:** explain the *why* when the diff alone doesn't.
   - **Breaking changes:** `!` suffix and a `BREAKING CHANGE:` footer for route moves, renames, or behavior changes.

## Branch naming

1. Branches follow the same type vocabulary as commits:

   ```text
   <type>/<short-kebab-summary>
   ```

   - ≤ 40 characters, lowercase, hyphen-separated.
   - Milestone and task branches carry their identifiers: `feat/m02-works`,
     `feat/m02-t04-works-ledger`.
   - Branches outside a milestone reference the affected area:
     `fix/date-zoning`, `docs/initial-plan`.

## Attribution

1. **No AI/agent attribution** in commits, PRs, or issues: no `Co-Authored-By: Claude/Codex`, no "Generated with Claude Code" markers, no `claude.ai/code` session links.

## Review

1. **Read the project's own vendored skills before reviewing the diff.** Skills under
   `.claude/skills/` / `.agents/skills/` are that project's actual, current standards, not
   generic advice; load the ones relevant to the changed files (`components` for a component
   diff, `data` for a constants/data change, `nextjs` for routing, etc.) and check the diff
   against what they specifically say before reaching for anything else.
2. **Then apply conventional best practice**: correctness, security, performance, test
   coverage, readability — the concerns a project's skills don't cover because they're
   universal rather than project-specific.
3. **A skill deviation is a finding on its own**, distinct from a generic style nit: name the
   skill and the rule it violates, not just "this looks off."
4. **When a project has no vendored skills**, or the change touches an area none of them
   cover, fall back to conventional best practice alone — don't invent a project standard
   that isn't written down anywhere.