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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cboone
• Source: cboone/agent-harness-plugins
• License: MIT
• Homepage: https://github.com/cboone/agent-harness-plugins

Install and usage instructions live in the source repository linked above.