From 9d9bb52f93795be2a3ab2c07282325e168d55fe3 Mon Sep 17 00:00:00 2001 From: bob walker Date: Fri, 6 Feb 2026 16:49:54 +0000 Subject: [PATCH] docs: update git guidelines in GEMINI.md Add comprehensive rules for Git usage, including branching protocols, worktree suggestions, safety checks (git diff), and history management. Establish discovery steps for repo-specific branching and worktree suitability. Ensure commits are atomic and separate functional logic from linting/whitespace changes. --- GEMINI.md | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/GEMINI.md b/GEMINI.md index 01532c9..ea2643a 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,9 +1,9 @@ ## Core Guidelines - **Persona:** Assume the user is a 30-year veteran system administrator. Skip explanations of basic concepts. Be direct, technical, and concise. -- **Direct Action:** Edit files directly to fulfill requests. Do not offer to commit, create pull requests, or discuss branching unless explicitly asked. +- **Direct Action:** Edit files directly. Do not commit or branch autonomously; always ask for permission first. Proactively suggest logical points for atomic commits and suggest new branches if the work deviates from the current scope or a significant task shift occurs. - **Code Comments:** Use them sparingly. Only explain complex "why" logic. Never explain "what" the code is doing. -- **Project Discovery:** +- **Project Discovery:** - Always check for a `Makefile` or `scripts/` directory first for build/test/lint commands. - Identify language stacks via manifests (`package.json`, `go.mod`, `Cargo.toml`, `requirements.txt`). - **Language Defaults:** @@ -15,4 +15,26 @@ - Mimic local indentation (tabs vs spaces) and naming conventions exactly. - Always write a test if a framework exists. Match the existing style (e.g., table-driven tests in Go). - Respect `.gitignore` and `.editorconfig`. -- **Shell Usage:** Prefer non-interactive commands with silent/quiet flags (e.g., `apt-get -y`, `npm install --quiet`). \ No newline at end of file +- **Shell Usage:** Prefer non-interactive commands with silent/quiet flags (e.g., `apt-get -y`, `npm install --quiet`). +- **Git Branching:** + - **Discovery:** On new repo entry, ask "Does this repo require feature branches?". Record answer in the repo's `GEMINI.md`. + - Use a new branch for each feature or bug fix. + - include ticket/issue number in branch name if available (e.g., `123-add-login`). + - Naming convention: `description` (e.g., `add-login`, `memory-leak`). + - Branch from the default branch (`main` or `master`) and keep branches short-lived. + - Rebase from the default branch frequently to avoid conflicts. +- **Git Worktrees:** + - Suggest `git worktree` for parallel tasks or frequent context switching. + - **Discovery:** On new repo entry, ask "Is this repo suitable for worktrees?". Record answer in the repo's `GEMINI.md`. +- **Git Safety & History:** + - **Pre-commit:** Always run `git diff` (or `git diff --staged`) to verify changes before asking to commit. + - **Force Push:** Permitted *only* on private feature branches (`--force-with-lease`). Never on shared/main branches. + - **Conflicts:** If a rebase/merge encounters complex conflicts, abort and ask for guidance. + - **Cleanup:** Squash "wip" or "fix typo" commits into the main feature commit before final merge instructions. +- **Git Commits:** + - Use present tense, imperative mood (e.g., `resolve memory leak`). + - Keep summary <= 50 chars; wrap body at 72 chars. + - Explain _why_ in the body, not _what_. + - Reference issue/ticket numbers if available (e.g., `Fixes #456`). + - Keep commits atomic; one logical change per commit. + - Separate whitespace and linting changes into their own commits, distinct from functional logic changes.