# Git Instructions

## 🚨 GIT POLICY - ABSOLUTELY CRITICAL

**NEVER EVER make git commands without explicit user approval!**

### Forbidden Commands - DO NOT RUN:
1. ❌ **git add** - User runs this themselves (including git add ., git add -A, git add <file>)
2. ❌ **git commit** - User runs this themselves  
3. ❌ **git push** - User runs this themselves
4. ❌ **git push --force** - User runs this themselves
5. ❌ **git reset** - User runs this themselves
6. ❌ **ANY command that modifies git repository or server state**

### What You CAN Do:
- ✅ `git status` - Show current state
- ✅ `git diff` - Show changes
- ✅ `git log` - Show history
- ✅ Show the command user should run
- ✅ Explain what the command will do

### Exception:
Only if user explicitly says:
- "commit this now"
- "push this now"
- "go ahead and commit"

Otherwise: **SHOW the command, WAIT for user to run it**

---

## Best Practices

- Always show `git diff` before suggesting commits
- Show `git status` to verify what will be committed
- Explain impact of each git operation
- User controls git commands, you analyze and advise
- Never assume user wants to commit
- Reliability over speed

---

## Commit Message Workflow

When the user asks for a commit message:

1. **Run `git diff --staged` or `git diff`** — read what actually changed
2. **Documentation check** — scan the changed files and ask: does any `docs/` or `README.md` need updating based on these changes? If yes, flag it clearly before writing the message. Do not block the commit — just surface it.
3. **Write the commit message only** — one short subject line, optionally a blank line and brief body if the change needs context. Output must be only the message text inside one fenced code block. Do NOT wrap it in a `git commit` command.

**Output format is mandatory for copy/paste:**
- Always use one fenced code block (prefer `text` language tag)
- Put only commit message content inside the block
- Do not add prose before or after the block
- Do not add labels like "Suggested message:" outside the block

Correct:
```text
fix(scope): concise subject

optional body line
```

Wrong:
- `Suggested commit message: fix(scope): concise subject`
- Plain text without a fenced block

Format:
```
<type>: <what changed>

<optional: why, or what is not obvious from the diff>
```

Types: `feat`, `fix`, `docs`, `refactor`, `chore`

### Commit message rules

**Only include what actually changed in this commit.**

- Run `git diff --staged` (or `git diff` if nothing staged) and read it fully before writing
- List only files and lines that appear in the diff
- If a file appears in the diff but only has whitespace or comment changes, omit it from the body
- Never mention changes that are not in the diff — even if you remember discussing them earlier in the session
- If unsure whether something changed, check the diff — do not guess

**Format rules:**
- Subject line: max ~72 chars, imperative mood ("Fix", "Add", "Remove" — not "Fixed", "Added")
- Body: optional, only when the *why* is not obvious from the diff
- No bullet-pointed list of every file changed unless the diff spans many unrelated files
- No "CHANGES:" headers, no file-by-file breakdowns for single-topic commits
- No "Expected:", "Result:", "Impact:" or any speculative outcome sections — commit messages describe what changed, not what is predicted to happen
- Bullet points state *what* changed, not *why it was wrong* or *how it works* — keep each line short and factual
  - ✅ `use MC_HOST_minio for S3 auth`
  - ❌ `Use MC_HOST_minio env var for direct S3 auth (no mc alias set)`
- Do not describe runtime behavior, incident narrative, or manual operations in the commit message body
  - ❌ `gitea failed on startup`
  - ❌ `Redis services cleaned up manually`
  - ❌ `Certificate renewed successfully`
  - ✅ `disable redis sub-chart`
  - ✅ `set queue type to level`

**All projects:**
- Treat commit messages as change logs of repository state, not behavior reports
- Never include runtime status, deployment outcomes, test run narratives, or manual operation confirmations unless the user explicitly asks for a release note or status report instead of a commit message