git-workflow

Git Workflow

Guided workflows for common git operations that benefit from structured steps.

PR Preparation

When preparing a pull request:

1. Gather context
2. git log main..HEAD --oneline — list all commits on the branch
3. git diff main...HEAD --stat — see all changed files
4. git status — check for uncommitted work

1. Draft PR content
2. Title: under 70 chars, describes the change (not the branch name)
3. Body: summarise the "why", list key changes, add test plan
4. Use the commit history to write the summary — don't rely on memory

1. Push and create

```bash git push -u origin HEAD gh pr create --title "..." --body "$(cat <<'EOF' ## Summary

• ...

## Test plan

• [ ] ...

🤖 Generated with Claude Code EOF )" ```

1. Verify — gh pr view --web to open in browser

Branch Cleanup

Clean up merged branches safely:

1. Switch to main and pull latest

``bash git checkout main && git pull ``

1. List merged branches (excludes main/master/develop)

``bash git branch --merged main | grep -vE '^\*|main|master|develop' ``

1. Delete local merged branches

``bash git branch --merged main | grep -vE '^\*|main|master|develop' | xargs -r git branch -d ``

1. Prune remote tracking refs

``bash git fetch --prune ``

1. List remote branches with no local tracking (optional)

``bash git branch -r --merged origin/main | grep -vE 'main|master|develop|HEAD' ``

Merge Conflict Resolution

When a PR has conflicts:

1. Assess the conflict scope

``bash git fetch origin git merge origin/main --no-commit --no-ff git diff --name-only --diff-filter=U # List conflicted files ``

1. For each conflicted file, read the file and resolve:
2. Keep both changes if they're in different areas
3. If architecturally incompatible, prefer the main branch's approach and re-apply the PR's intent on top

1. If rebase is cleaner (few commits, no shared history):

``bash git rebase origin/main # Resolve conflicts per commit, then: git rebase --continue ``

1. If rebase is messy (many conflicts, architectural divergence):
2. Abort: git rebase --abort or git merge --abort
3. Extract useful code: git show origin/branch:path/to/file > /tmp/extracted.txt
4. Apply changes manually to main
5. Close original PR with explanation

1. Verify — run tests, check the diff looks right

Monorepo Release Tags

In monorepos, scope tags to the package:

# ❌ Ambiguous in monorepos
git tag v2.1.0

# ✅ Scoped to package
git tag contextbricks-v2.1.0
git push origin contextbricks-v2.1.0

Pattern: {package-name}-v{semver}

.gitignore-First Init

When creating a new repo, always create .gitignore BEFORE the first git add:

cat > .gitignore << 'EOF'
node_modules/
.wrangler/
dist/
.dev.vars
*.log
.DS_Store
.env
.env.local
EOF

git init && git add . && git commit -m "Initial commit"

If node_modules is already tracked:

git rm -r --cached node_modules/
git commit -m "Remove node_modules from tracking"

Private Repo License Audit

Before publishing or sharing a private repo:

gh repo view --json visibility -q '.visibility'

If PRIVATE, ensure:

• LICENSE contains proprietary notice (not MIT/Apache)
• package.json has "license": "UNLICENSED" and "private": true
• No CONTRIBUTING.md or "contributions welcome" in README