---
name: git-operations
description: >-
  Safe git operation guidelines. Use when performing any git operations including commits, branching, merging, rebasing, pushing, pull request creation, or any other git-related tasks.
---

Before executing, read the [Claude Code / Codex runtime instructions](../../references/runtime.md).

# Git Operations Safety Guidelines

These are defaults. The project's instructions (AGENTS.md, CLAUDE.md, rule files, memory) and the session's instructions take precedence where they differ, such as the commit message language, attribution lines, or whether to commit and push without asking.

## Git Safety Protocol

- NEVER update the git config
- NEVER run destructive git commands (`push --force`, `reset --hard`, `checkout .`, `restore .`, `clean -f`, `branch -D`) unless the user explicitly requests these actions
  - Exception: the `branch-cleanup` skill's `git branch -D`, which only targets branches whose tip SHA matches a merged PR's head SHA and only runs when the user asked for cleanup. Squash merge makes `git branch -d` unable to recognize those branches, so `-D` is the only way to delete them
- NEVER skip hooks (`--no-verify`, `--no-gpg-sign`, etc.) unless the user explicitly requests it
- NEVER force push to `main`/`master`. Warn the user if they request it
- NEVER run `git rebase -i` or `git add -i` since they require interactive input which is not supported
- NEVER use `--no-edit` with `git rebase` commands, as it is not a valid option for git rebase
- When the session asks the user to approve commands one by one, run each git command as a separate invocation instead of chaining with `&&` or `;`
  - A chain can only be allowed or denied as a whole (e.g., a chain containing `git push` forces the user to deny the entire chain)
  - In auto mode, where commands are not approved one by one, chaining is fine
- When the session asks the user to approve commands one by one, don't use `git -C <path>`; `cd` to the target directory first, or use absolute paths in arguments
  - If the user approves a `git -C` command with "Yes, and don't ask again for similar commands", `Bash(git -C:*)` is added to `permissions.allow`, and that pattern matches every git command
  - In auto mode no allow rule is added, so `git -C <absolute path>` is fine. It is the more reliable way to target another repository from a subagent, whose working directory can reset between Bash calls

## Commit Rules

- Only create commits when explicitly requested by the user. If unclear, ask first
- ALWAYS create NEW commits rather than amending, unless the user explicitly requests amend
  - When a pre-commit hook fails, the commit did NOT happen. Using `--amend` would modify the PREVIOUS commit, which may destroy work. Instead, fix the issue, re-stage, and create a NEW commit
- When staging files, prefer adding specific files by name rather than using `git add -A` or `git add .`, which can accidentally include sensitive files (`.env`, credentials) or large binaries
- NEVER commit files that likely contain secrets (`.env`, `credentials.json`, etc.). Warn the user if they request it

### Commit Message Format

- Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `<type>(<scope>): <description>`
  - Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`
  - Scope is optional but recommended (e.g., `feat(auth): add login endpoint`)
  - Description should be concise and have no period at the end; in English, use the imperative mood and lowercase
- For breaking changes, add `!` after type/scope (e.g., `feat(api)!: change response format`) or add `BREAKING CHANGE:` in the body
- Pass multi-line commit messages through a quoted HEREDOC on stdin, so backticks in the message are not run as command substitution:

```bash
git commit -F - <<'EOF'
feat(auth): add OAuth2 login support

<body>
EOF
```

- Add attribution lines (`Co-Authored-By:` and the like) only as the harness and the repository instruct

## Branch Rules

- Check the current branch before making changes
- Prefer creating feature branches from the main branch for new work
- Use descriptive branch names (e.g., `feature/add-auth`, `fix/login-bug`)

## Push Rules

- Do NOT push to the remote repository unless the user explicitly asks
- Always verify the current branch and its remote tracking status before pushing
- Use `git push -u origin <branch>` for new branches

## Pull Request Rules

- Keep the PR title short (under 70 characters)
- Use the PR description/body for details, not the title
- Include a summary section with bullet points
- Include a test plan section
- Write the body to a file and pass it with `--body-file`. With `--body "$(...)"`, a failing command substitution leaves the body empty, and `gh` still succeeds:

```bash
cat > <scratchpad>/pr-body.md <<'EOF'
## Summary
<1-3 bullet points>

## Test plan
[Bulleted checklist of testing steps]
EOF
gh pr create --title "the pr title" --body-file <scratchpad>/pr-body.md
```

## Merge Conflict Resolution

- Investigate merge conflicts rather than discarding changes
- Try to identify root causes and fix underlying issues rather than bypassing safety checks
- If a lock file exists, investigate what process holds it rather than deleting it

## General Safety

- Before taking any irreversible git action, consider the blast radius and confirm with the user
- If you discover unexpected state (unfamiliar files, branches, or configuration), investigate before deleting or overwriting, as it may represent the user's in-progress work