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

Scenario	Pattern	Reason
Commit messages	HEREDOC	Short, predictable length
PR bodies (gh pr create)	Tmpfile + --body-file	Can be long; HEREDOC triggers prompts
Issue bodies (gh issue create)	Tmpfile + --body-file	Can be long
Review replies	Tmpfile + --body-file	Variable length
Worktree prompts	Write tool to /tmp/	Avoids shell escaping
Tag messages	Inline -m	Typically one line

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
• references/diff-output.md - Clean diff output flags for bypassing external diff tools, colors, and pagers