Lesson 13: Git & PR Workflows

Claude Code lives in your terminal alongside git. It can stage files, write commit messages, create branches, open pull requests, and help with code review. This lesson covers the git workflows that work best with Claude Code and how to build good version control habits with AI assistance.

Commits with Claude

After making changes with Claude Code, you can have it handle the commit:

> Stage and commit the changes with a descriptive message.

Claude will look at the diff, understand what changed, and write a commit message. But you should guide the format:

> Stage and commit using conventional commit format.
  Prefix with feat, fix, refactor, test, docs, or chore.

This produces messages like:

feat(auth): add rate limiting to login endpoint
fix(cart): handle negative quantities in order total
refactor(api): extract validation middleware from route handlers
test(utils): add edge case tests for date parsing

Writing Good Commit Messages

Claude writes better commit messages when it understands the why, not just the what:

# Weak — Claude only knows what changed
> Commit these changes

# Strong — Claude understands the purpose
> Commit these changes. The motivation is that users were seeing
  stale data because the cache TTL was too long. We reduced it
  from 1 hour to 5 minutes.

The resulting message will explain the reasoning, not just list modified files.

Branch Management

Keep feature branches focused. One branch per feature, one purpose per branch.

> Create a new branch called "feature/add-search" from main
  and switch to it.

Claude will run:

git checkout -b feature/add-search main

When a branch grows too large, break it up:

> This branch has grown to include both the search feature and
  a refactor of the API routes. Help me split it: create a
  separate branch for just the API route refactor, with its
  own commits.

Tip: Start each Claude Code session by telling it which branch you are on and what the branch's goal is. This helps Claude make changes that stay on-topic.

Creating Pull Requests

If you have the GitHub CLI (gh) installed, Claude Code can create pull requests directly:

> Create a pull request for this branch. The target is main.
  Write a clear description that explains:
  - What this PR does
  - How to test it
  - Any migration steps needed

Claude will run something like:

gh pr create --title "Add full-text search to products API" \
  --body "## Summary
  Adds a /api/products/search endpoint with full-text search
  powered by PostgreSQL tsvector.

  ## How to test
  1. Run migrations: npm run db:migrate
  2. Seed test data: npm run db:seed
  3. Hit GET /api/products/search?q=widget

  ## Notes
  - Requires PostgreSQL 14+
  - Search index is created in migration 20240115_add_search_index"

PR Description Patterns

For consistent PR quality, give Claude a template:

> Create a PR with this format:
  - Title: short, imperative mood, under 70 characters
  - Summary: 2-3 bullet points of what changed
  - Testing: how reviewers can verify the changes
  - Breaking changes: any, or "None"

Code Review with Claude

Claude Code can review diffs — both your own and others':

Reviewing Your Own Changes

Before submitting a PR:

> Review the diff between this branch and main. Look for:
  - Bugs or logic errors
  - Missing error handling
  - Security concerns
  - Code style inconsistencies
  - Missing tests

Reviewing Someone Else's PR

# Fetch the PR diff
gh pr diff 142

> Review this PR diff. Summarize what it does, flag any concerns,
  and suggest improvements.

Claude can catch things humans skim past: unchecked error returns, SQL injection vulnerabilities, missing null checks, inconsistent naming.

Resolving Merge Conflicts

Merge conflicts are a pain point for every developer. Claude Code can help:

git merge main
# CONFLICT in src/services/user.js

> There's a merge conflict in src/services/user.js. Read both
  versions and resolve the conflict. Our branch added rate limiting;
  main added logging. We need both changes.

Claude will:

Read the file with conflict markers
Understand what each side intended
Produce a merged version that preserves both changes
Remove the conflict markers

For complex conflicts across multiple files:

> Run "git diff --name-only --diff-filter=U" to list all conflicted
  files, then resolve each one. Explain your resolution for each file.

Important: Always review the resolution. Claude usually gets merges right, but domain-specific conflicts (like database migrations with ordering dependencies) may need human judgment.

Example Workflow: Feature to PR

Here is a complete workflow for a typical feature:

# 1. Start on main, create a feature branch
claude
> Create a branch called "feature/user-avatars" from the latest main.

# 2. Plan the feature
> Plan the implementation of user avatar upload. We need:
  - A POST /api/users/:id/avatar endpoint
  - File validation (images only, max 2MB)
  - Storage to the local uploads/ directory
  - Update the user record with the avatar path
  What files need to change?

# 3. Implement with tests
> Implement the avatar upload feature based on the plan.
  Write tests alongside the implementation.

# 4. Run tests
> Run the full test suite. Fix any failures.

# 5. Review before committing
> Show me git diff. Walk me through each changed file.

# 6. Commit in logical chunks
> Stage and commit in two commits:
  1. The avatar upload endpoint and its tests
  2. The user model changes and migration
  Use conventional commit format.

# 7. Create the PR
> Push this branch and create a PR targeting main.
  Write a description covering what changed and how to test it.

This entire workflow — branch, plan, implement, test, review, commit, PR — happens in one Claude Code session without leaving your terminal.

Commit Message Patterns That Work

Pattern	Example	When to use
Conventional	`feat(api): add avatar upload endpoint`	Team uses conventional commits
Imperative	`Add avatar upload endpoint`	Simple, clean history
Why-focused	`Support user avatars to improve profile pages`	When the reason matters more than the what
Ticket-linked	`[PROJ-123] Add avatar upload endpoint`	Jira/Linear integration

Pick one style and tell Claude to use it consistently:

> Always use conventional commit format with a scope.
  Keep the subject line under 72 characters.

Key Takeaways

Claude Code writes better commit messages when you explain the why behind changes
Use conventional commits or another consistent format — tell Claude which one
Keep branches focused on a single feature or fix
Use gh pr create through Claude for PR creation with good descriptions
Have Claude review diffs before submitting PRs to catch bugs and style issues
Claude can resolve merge conflicts, but always review the result yourself
The full workflow (branch, plan, implement, test, commit, PR) can happen in one session