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** - `git log main..HEAD --oneline` — list all commits on the branch - `git diff main...HEAD --stat` — see all changed files - `git status` — check for uncommitted work 2. **Draft PR content** - Title: under 70 chars, describes the change (not the branch name) - Body: summarise the "why", list key changes, add test plan - Use the commit history to write the summary — don't rely on memory 3. **Push and create** ```bash git push -u origin HEAD gh pr create --title "..." --body "$(cat <<'EOF' ## Summary - ... ## Test plan - [ ] ... 🤖 Generated with [Claude Code](https://claude.com/claude-code) EOF )" ``` 4. **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 ``` 2. **List merged branches** (excludes main/master/develop) ```bash git branch --merged main | grep -vE '^\*|main|master|develop' ``` 3. **Delete local merged branches** ```bash git branch --merged main | grep -vE '^\*|main|master|develop' | xargs -r git branch -d ``` 4. **Prune remote tracking refs** ```bash git fetch --prune ``` 5. **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 ``` 2. **For each conflicted file**, read the file and resolve: - Keep both changes if they're in different areas - If architecturally incompatible, prefer the main branch's approach and re-apply the PR's intent on top 3. **If rebase is cleaner** (few commits, no shared history): ```bash git rebase origin/main # Resolve conflicts per commit, then: git rebase --continue ``` 4. **If rebase is messy** (many conflicts, architectural divergence): - Abort: `git rebase --abort` or `git merge --abort` - Extract useful code: `git show origin/branch:path/to/file > /tmp/extracted.txt` - Apply changes manually to main - Close original PR with explanation 5. **Verify** — run tests, check the diff looks right ## Monorepo Release Tags In monorepos, scope tags to the package: ```bash # ❌ 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`: ```bash 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:** ```bash 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: ```bash 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