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, release notes, review replies) to a tmpfile via the Write tool, then pass the path to the command's file flag, such as --body-file or --notes-file. Keeps Bash commands short and avoids permission prompts. Generate the path with mktemp -u so the file does not already exist, and never batch the Write call together with the gh call that reads it. Both rules are scoped to this pattern, which carries non-secret content; references/tmpfile-pattern.md explains why -u is the wrong choice for security-sensitive temp files.
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. This applies only to commands with no dependencies between them. A Write that produces a tmpfile and the gh call that consumes it through a file flag (--body-file, --notes-file, and the like) are dependent: issue them in separate, sequential messages, never in one parallel batch. See references/tmpfile-pattern.md.
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

Workflow

1. Quick reference: Check the decision table above
2. Tmpfile details: Read references/tmpfile-pattern.md
3. HEREDOC details: Read references/heredoc-pattern.md
4. Safety rules: Read references/safety-rules.md
5. Common operations: Read references/common-operations.md
6. Diff output: Read references/diff-output.md

Reference Navigation

Quick reviews (default):

• The decision table above and the core principles cover most situations

Deep dives by topic:

• references/tmpfile-pattern.md - When and how to use tmpfiles for long content
• references/heredoc-pattern.md - When and how to use HEREDOCs for commit messages
• references/safety-rules.md - GPG signing, never amend, never force, secret exclusion, parallel calls
• references/common-operations.md - Base branch detection, push with upstream fallback, conventional commits, branch naming, paginated gh api reads
• references/diff-output.md - Clean diff output flags for bypassing external diff tools, colors, and pagers