Git Instructions

🚨 GIT POLICY - ABSOLUTELY CRITICAL

NEVER EVER make git commands without explicit user approval!

Forbidden Commands - DO NOT RUN:

❌ git add - User runs this themselves (including git add ., git add -A, git add )
❌ git commit - User runs this themselves
❌ git push - User runs this themselves
❌ git push --force - User runs this themselves
❌ git reset - User runs this themselves
❌ 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:

Run git diff --staged or git diff — read what actually changed
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.
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:

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:

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:

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

6.0 KiB Raw Blame History