136 lines
6.0 KiB
Markdown
136 lines
6.0 KiB
Markdown
# 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
|
|
- 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 *intent* or *why* is not obvious from the diff
|
|
- **NEVER list filenames in the commit message.** The git UI already shows which files changed. Your job is to describe *topics*, not files. No file-by-file breakdowns, and no "CHANGES:" headers.
|
|
- **Translate technical changes into a high-level topic summarization.** A human reading the message should immediately understand *what the goal was* without having to interpret individual code or file edits. Describe the business/functional accomplishment, not the technical steps taken.
|
|
- ❌ `docs/ai-context.md: add homelab k3s target, domain pattern`
|
|
- ✅ `document development environment and deployment context`
|
|
- No "Expected:", "Result:", "Impact:" or any speculative outcome sections — commit messages describe the accomplished goal, not what is predicted to happen
|
|
- Bullet points state *the high-level topics*, not *technical line edits* or *how it works* — keep each line short and factual
|
|
- ✅ `configure direct S3 authentication for MinIO`
|
|
- ❌ `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 external redis dependency`
|
|
- ✅ `configure queue type to persistent level`
|
|
- Do not summarize or quote the exact content of text/description changes — the diff shows the content, the message states the topic of the change
|
|
- ❌ `Remove "harmless" framing, add operational guidance: daily return to 0 expected`
|
|
- ✅ `update operational expectations for Ghost Blocks panel`
|
|
- Body format: use prose (one sentence) for a single goal; use bullets ONLY when multiple completely distinct goals or topics were accomplished in the same commit.
|
|
|
|
**Body length example — what "too much explanation" looks like vs. the correct abstract version:**
|
|
|
|
❌ Too detailed — describes files, code references, and technical mechanics:
|
|
```text
|
|
chore(minio): pin image to RELEASE.2025-10-15T17-29-55Z
|
|
|
|
Chart 5.4.0 bundles RELEASE.2024-12-18 which does not return Last-Modified
|
|
metadata on objects. Thanos compactor falls back to ULID creation time and
|
|
deletes valid blocks as stale partial uploads (>48h old).
|
|
|
|
Also add comment on thanos-sidecar image noting all Thanos containers
|
|
(compactor, blocks-exporter, init container, ghost cleanup job) share
|
|
this single image reference.
|
|
```
|
|
|
|
✅ Correct — states the high-level intent and reasoning clearly without itemizing files or specific code additions:
|
|
```text
|
|
chore(minio): downgrade minio version to fix object metadata loss
|
|
|
|
The newer chart release causes valid block deletion by the compactor due
|
|
to missing Last-Modified metadata on objects. Version is pinned to an
|
|
older stable release to prevent data loss.
|
|
|
|
Also clarified shared image dependencies for Thanos services in documentation.
|
|
```
|
|
|
|
**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
|