use-git

Use Git

Conventions for running git and GitHub CLI (gh) commands in Claude Code. These rules keep Bash commands short, avoid unnecessary permission prompts, and prevent destructive operations.

Core Principles

1. Tmpfiles for long content: Write long strings (PR bodies, issue bodies, review replies) to a tmpfile via the Write tool, then pass --body-file. Keeps Bash commands short and avoids permission prompts.
2. HEREDOCs for short content: Commit messages use $(cat << 'EOF' ... EOF). Single-quoted 'EOF' prevents variable expansion.
3. GPG sign every commit: Always git commit -S. The sandbox cannot access GPG keys, so resort immediately to the unsandboxed command.
4. Never amend: Always create new commits. Pre-commit hook failures mean the commit did not happen, so --amend would modify the wrong commit.
5. Never use force or override flags: Never use git push --force, git push -f, --no-verify, or similar override flags without explicit user instruction. If the user explicitly requests a force push, use git push --force-with-lease (add --force-if-includes when the installed Git version supports it, v2.30+). Investigate root causes rather than forcing through.
6. Parallel tool calls over chained commands: Use separate Bash tool calls for independent commands instead of chaining with ; or &&, which trigger permission prompts.
7. Exclude secret files from staging: Never stage .env, credentials.json, *.pem, *.key, or similar secret files.
8. Use clean diff output: Always pass --no-ext-diff --no-color (and --no-pager before the subcommand) on diff-producing commands (git diff, git log -p, git show). User configs may route diffs through external tools like difftastic, producing output that is harder to parse. These flags ensure standard unified diff format.

Quick Decision Table