git-workflow v2.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/9a304b70d2b6a721.

---
name: git-workflow
description: Non-interactive git usage and commit conventions for AI coding agents. Use when staging changes, committing, writing commit messages, naming branches, splitting work into pull requests, rebasing, or checking out a pull request in a worktree for review.
license: MIT
metadata:
  author: pablodiazjorge
  url: https://github.com/pablodiazjorge/prompt-forge
  version: "2.0.0"
  tokens: "0.9k"
  sources: "https://www.conventionalcommits.org/en/v1.0.0/, https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional, https://git-scm.com/docs"
---

# Git Workflow

## The team's rules win

Before applying the defaults below, look for the team's own conventions and
follow them instead: a commitlint config (`commitlint.config.*`,
`.commitlintrc*`), `CONTRIBUTING.md`, a pull request template, and the commit
history (`git log --oneline -20`).

## Never block on an editor or a prompt

An agent shell has no usable stdin, so interactive commands hang until they time
out.

| Instead of | Use |
|---|---|
| `git add -p`, `git add -i` | `git add <path>...` with explicit paths |
| `git commit` with no message | `git commit -m "<subject>" -m "<body>"`, or `-F <file>` for long messages |
| `git rebase -i` to squash fixes | `git commit --fixup <sha>`, then `git -c sequence.editor=true rebase -i --autosquash <base>`; for any other history edit, ask the user |
| `git rebase --continue` | `git -c core.editor=true rebase --continue` |
| `git merge` that opens an editor | `git merge --no-edit <branch>` |
| Paged output (`log`, `diff`, `show`) | `git --no-pager log -n 20 --oneline` |

## Safety

- Never pass `--no-verify`. A failing hook is a failing check: fix the cause.
- Never force-push a shared branch. When you must rewrite your own branch, use
  `git push --force-with-lease`.
- Read `git diff --cached` before every commit. Unstage anything that looks like
  a secret, a local config file, or an unrelated change.
- Do not commit to the default branch directly when the team works through pull
  requests. Create a branch first.

## Commits

One logical change per commit, staged by path.

The [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
format:

```
<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]
```

The specification itself defines only `feat` (a minor release) and `fix` (a
patch release), plus breaking changes, marked with `!` before the colon or a
`BREAKING CHANGE:` footer (a major release). Every other type is a team
convention. The common set, from `@commitlint/config-conventional`, is
`build`, `chore`, `ci`, `docs`, `perf`, `refactor`, `revert`, `style`, and
`test`. Release tools differ on whether these bump a version (semantic-release's
defaults, for example, release a patch for `perf` and for reverts), so check the
project's release configuration rather than assuming.

## Branches

`<type>/<short-name>`, for example `feature/export-csv`, `fix/login-timeout`,
`docs/install-guide`, `chore/bump-deps`, `refactor/split-parser`, unless the team
uses another scheme.

## Pull requests

- Every pull request builds and passes its tests on its own. Tests ship with the
  code they cover, not in a later pull request.
- Split a large change along layers (types and schema, then logic, then the
  delivery surface) only when each step is reviewable and working by itself.
- When a base pull request in a stack is squash-merged, move the next branch
  onto the default branch with `git rebase --onto <default> <old-base> <branch>`.

## Reviewing a pull request in a worktree

```bash
git fetch origin pull/<n>/head:pr-<n>      # GitHub; GitLab uses merge-requests/<n>/head
git worktree add ../pr-<n> pr-<n>
# review, build, test in ../pr-<n>
git worktree remove ../pr-<n>
git branch -D pr-<n>
```

If your sandbox blocks writes outside the repository, put the worktree in a
git-ignored directory inside it instead.

## Before you commit

If the repository has a `knowledge/lessons/` directory and this task hit a
non-obvious failure that a teammate's agent would likely repeat, run the
`record-lesson` skill first, so the lesson ships in the same pull request.