git-workflow

Files (2)

• SKILL.md
• gpg-rewarm.sh · references/

SKILL.md (first lines)

# Git Workflow

## Branching

### Picking the source branch

The default branch depends on the repo's deployment model — identify it before branching:

- **Small project**: `main` is both default and production (deploy on push or tag).
- **Standard**: `main` deploys to staging on push, production on tag. Branch from `main`.
- **Staged**: `dev` deploys to staging on push, `main` is preprod, tags are prod. Branch from `dev`.

If unsure, check CI config or ask before branching.

### Branch naming

`<type>/<short-kebab-description>`, optionally prefixed with the issue ID.

- Types: `feature/`, `fix/`, `hotfix/`, `refactor/`, `chore/`, `release/vX.Y.Z[-target]`
- Examples: `feature/vista-123-user-authentication`, `fix/login-redirect`, `hotfix/memory-leak`
- `hotfix/*` targets the **production** branch (usually `main`), not `dev`. Everything else targets the default/staging branch.
- Optional: `fix/various` as a batch branch for rapid low-risk bug sweeps. Only use when the maintainer is comfortable with it.

For collaboration on the same feature, use sub-branches: `feature/my-feature-alice`, `feature/my-feature-bob`, reconciled into `feature/my-feature` via rebase or merge.

## Commits

### Format

Bracketed prefix matching the issue tracker's native format, then a description in English:

```
[<issueRef>] <Description of the change>
```

- GitHub/GitLab: `[#123]`
- Linear: `[VISTA-123]`
- Jira: `[PROJ-456]`
- Match whatever the repo uses — do not invent a format.

If the commit addresses PR/MR review feedback or a CI failure, prepend the MR ref:

```
[!51, #123] Fixed code after peer review
```

Unreferenced commits are fine for linters, dependency bumps, cleanups:

```
Updated Meteor packages & dependencies
```

Avoid `feat:` / `fix:` / `(fix)` Conventional Commits prefixes — not the convention here.

### Rules

- **Atomic and revertible.** One logical change per commit. A `git revert` on any commit should leave a coherent tree.
- **Dedicated refactor commits.** Never mix refactors with behavioral changes — the diff becomes unreadable.
- **Tense.** Past (what the dev did: `Fixed the delete button`) or present general truth (what the commit brings: `Fixes the delete button`). Pick one and stick with it in the branch.
- **Title-only.** If you feel the need for a multi-paragraph description, the commit probably needs to be split. Use `git add -p` / `git add -i`.
- **Clean the history before merging.** Use `git commit --amend` or `git rebase -i` to squash WIPs, fix typos, reorder.
- WIP-style commits (`[WIP] ...`) are fine during work but should be squashed or renamed before the MR is ready.

### GPG signing

When `commit.gpgsign = true`, signed git operations (commit, tag, merge, cherry-pick, revert, rebase) must reach gpg-agent's pinentry to unlock the signing key. **Pinentry cannot prompt from inside Claude Code's TTY** — curses, GUI, anything interactive — so the operation hangs indefinitely.

Two practical workarounds:

1. **Long passphrase cache + once-daily pre-unlock** (recommended). In `~/.gnupg/gpg-agent.conf`:

   ```
   default-cache-ttl 86400
   max-cache-ttl 86400
   ```

   Then once a day, in a normal terminal: `echo test | gpg --clearsign > /dev/null`. The cache stays warm for 24h and signed commits inside Claude Code "just work."

   **Warm a specific (non-default) key.** `gpg --clearsign` signs with the default key (`default-key`, or the first secret key), so it warms the *wrong* key's cache if you sign commits with a non-default key. Pin the key with `-u`: `echo test | gpg -u <KEYID> --clearsign > /dev/null`.

   **Re-warm before expiry (reset the 24h window).** Re-running the warm command while the cache is still valid does *not* extend the lifetime — `max-cache-ttl` is measured from the *first* unlock and is never bumped by use (only `default-cache-ttl` resets, and here they're equal). To force a fresh 24h window you must flush the cached passphrase first, then re-sign to trigger pinentry: flush the signing (sub)key's **keygrip** with `gpg-connect-agent "clear_passphrase --mode=normal <KEYGRIP>" /bye`, then `echo test | gpg -u <KEYID> --clearsign > /dev/null`. Find the keygrip with `gpg --list-secret-keys --with-keygrip` (use the *signing* subkey's keygrip, not the primary's). Flushing every signing-capable keygrip of the key and re-signing once is the robust way to avoid the primary-vs-subkey guess. A ready-made `gpg-rewarm [keyid]` function that does all of this is in [`references/gpg-rewarm.sh`](references/gpg-rewarm.sh) — source it from your shell rc. The argument is optional: with none, it uses `$GPG_REWARM_KEY`, else `git config --get user.signingkey`, so a bare `gpg-rewarm` warms the key your commits are actually signed with.

2. **PreToolUse hook** — see [`hooks/git-gpg-precheck.sh`](../../hooks/git-gpg-precheck.sh) in this repo. Probes the cache before any signed git operation and returns `permissionDecision: "deny"` with a clear "cold cache" message when the cache is empty, so the agent stops and asks the user to pre-unlock instead of hanging.

Last resort: pass `--no-gpg-sign` for an unsigned commit. Don't pre-emptively bypass signing — only use this when the user has explicitly authorized it for the specific operation, otherwise commits stop being verifiable.

## Pulling & rebasing

Keep history linear to avoid spurious merge commits and conflicts.

- Prefer `git pull --rebase` or `git pull --ff-only` over plain `git pull`. Configure once: `git config --global pull.ff only`.
- Rebase your feature branch on the target branch **before opening the MR** and again before merging if it has drifted.
- Push at least once a day — remote is your backup and lets others review in progress.
- To pull in a fix from a sibling branch, prefer `git cherry-pick <sha>` over merging the whole branch.

## MR/PR preparation

- Run typecheck + lint + tests before pushing. Fix warnings caused by your changes.
- MR title: include the issue ref in the same bracketed format as commits. Example: `[VISTA-1234] Implemented user authentication`.
- MR description: what changed, why, how to test.
- Target branch: default/staging branch for features and fixes, production branch for hotfixes.
- Rebase onto the target branch just before requesting review.

From Clovel/custom-ai-skills, MIT.

More from Clovel/custom-ai-skills