bram-git-gh.md

bram-git-gh.md

Bram git / gh workflow patterns

Tabulated from three weeks of Claude Code session logs (2026-05-12 to 2026-06-02), Bram-driven.

Git: surgical operations Bram does on the user's behalf

bucket	what it covers
Hunk-level staging / unstaging	-p / --patch work: add -p, checkout -p, restore -p, reset -p, stash push -p. Plus diff --cached / --staged to review the staging area hunk by hunk.
Staging surgery (non-hunk)	restore --staged <path> to unstage a single file, rm --cached, add --intent-to-add, any --index / --cached flag work.
History rewriting	commit --amend (with and without --no-edit), commit --fixup <sha>, rebase --autosquash --autostash, rebase --onto, --continue / --abort / --skip.
Merge / cherry-pick / revert / apply	Picking commits across branches, applying patches, conflict resolution: cherry-pick <sha>, revert <sha>, merge --no-ff / --squash, apply --cached, am.
Reset surgery	reset --soft HEAD~N, reset --mixed, reset --hard <sha>, the soft-reset-to-squash pattern, reset --keep.
Stashes	stash push/pop/apply/drop, with --keep-index, --include-untracked, --patch; checkout stash@{N} -- <path> to restore a single file from a stash.
Refs / branches advanced	push --force-with-lease, push --delete, branch -d/-D, branch -m, fetch --prune, remote set-url.
Inspection magic	The read-before-write loop: log --graph --all, log -G '<regex>' (pickaxe by content change), log -S '<string>', log --grep, log --author, blame, show <sha>:<path> to read a file at a revision, diff <a>...<b> (three-dot), merge-base, rev-list.

Top 3 git patterns: effective, but deterred by mechanical complexity

1. Hunk-level staging (git add -p and friends). Composing a focused commit out of a messy working tree by accepting / rejecting individual hunks. The mechanical cost is real — you sit through every hunk, type y/n/s/e, and if you split wrong you start over. Most developers default to git add . and live with sprawling commits. Bram does the patience work on your behalf and lands clean, atomic commits.

2. Squash-by-soft-reset (git reset --soft HEAD~N && git commit). Turning two consecutive WIP commits into one clean commit without touching the working tree. The flag combinations are intimidating (--soft vs --mixed vs --hard), and getting it wrong loses work. Most developers reach for git rebase -i, which requires an interactive editor and breaks in non-interactive contexts. Bram applies the soft-reset pattern as documented in the project conventions — no editor, no panic.

3. History archaeology (git log -G '<regex>', git show <sha>:<path>). Finding when a string first appeared or disappeared from the codebase, or reading a deleted file at the revision before it was removed. The flags (-G, -S, :<path> ref-spec) are obscure enough that most developers never learn them and instead grep the working tree and miss the history. Bram uses them as the default first move when investigating a regression — "when did this break" becomes a one-liner instead of a half-hour bisect.

---

gh (GitHub CLI): surgical operations Bram does on the user's behalf

bucket	what it covers
Issue lifecycle (mutation)	issue create / edit / comment / close / reopen. The mutation surface, not the read surface.
JSON / jq scripting	--json <fields> + --jq '<expr>' to pipe gh output through structured filters; --template for shaping.
Raw API calls	gh api <endpoint> with --paginate, -X POST/PATCH/DELETE, --field, -F, --input. Hand-rolled REST when no higher-level subcommand exists.
Filtered listing / search	issue list --search '<query>', --state, --label, --assignee, --author, --milestone; gh search code/issues/prs/repos/commits for cross-repo discovery.
Cross-repo with -R	-R <owner/repo> or --repo <owner/repo> to operate on a repo you're not cwd-in — no clone required.
Multi-line body composition	--body-file <path> to author rich markdown content offline (heredoc, editor, generated) and post it without shell-escaping hell.
Releases	release view / create / edit / list, with --draft, --prerelease, --generate-notes, asset upload patterns.
Repo lifecycle	repo view / edit / clone / create / fork / archive.
Actions / workflow runs	run list / view / watch / cancel / rerun, workflow run for dispatching.
PR operations	pr create / view / diff / checkout / merge / review. Light in this window because Bram's worklist drives in-repo PRs.
Labels / milestones	label list / create / edit / delete.

Top 3 gh patterns: effective, but deterred by mechanical complexity

1. gh api with --paginate and --jq. Hand-rolled REST queries against the GitHub API with pagination handled and JSON filtered down to exactly the fields you want — e.g. "all open issues across these five repos with label X, formatted as TSV." Doing this without gh means curl + Bearer-token auth + manual Link: header parsing for pagination + a separate jq invocation, and any one of those steps deters most developers from starting. With gh api --paginate ... --jq ... it's a single shell line; Bram composes them routinely for cross-issue analytics that would be impractical to do by hand.

2. Filtered listing and search (gh issue list --search '...', gh search code). GitHub's search syntax (is:open label:bug -author:dependabot updated:>2026-05-01) is powerful but finicky enough that hand-typing it is error-prone. The web UI search box is fine for one-offs but doesn't compose into a script. Bram drops the right --search string in once, pipes through --json / --jq, and the result feeds the next decision — the kind of "show me everything that matches X, then triage" loop that's tedious to do by clicking.

3. Multi-line body composition with --body-file. Authoring a rich issue or PR body (tables, fenced code blocks, embedded diffs) in markdown, then posting it without losing structure to shell-escape hell. The alternative is the web UI's textarea, which means leaving your terminal, switching to a browser, retyping context, and losing the ability to compose the body programmatically. Bram writes the body to /tmp/foo.md, then gh issue create --body-file /tmp/foo.md — bodies stay byte-perfect, and the same pattern composes with templates and generated content.