Git Workflow

What Is Git Workflow?

The "Git Workflow" skill for Claude Code provides a structured, guided approach to performing common Git operations in software development. It streamlines tasks such as preparing pull requests (PRs), cleaning up branches, resolving merge conflicts, managing monorepo tags, and handling squash-and-merge workflows. By embedding best practices directly into the workflow, this skill helps developers minimize errors and improve team collaboration. The Git Workflow skill is particularly valuable for projects with multiple contributors, where consistent, repeatable steps are essential for maintaining code quality and repository hygiene.

Why Use Git Workflow?

Modern development teams rely heavily on Git for source code management. However, inconsistent practices when managing branches, preparing PRs, or resolving conflicts can introduce risk and slow productivity. Manual, ad hoc processes often lead to:

• Poorly described PRs that confuse reviewers
• Stale or orphaned branches cluttering the repository
• Merge conflicts that are challenging to resolve cleanly
• Inconsistent tagging and release management, especially in monorepos
• Difficulty enforcing squash-and-merge conventions

The Git Workflow skill addresses these pain points by offering a set of clearly defined, repeatable steps for each scenario. This not only improves code quality and project maintainability, but also reduces onboarding friction for new team members by making the workflow transparent and standardized.

How to Get Started

Using the Git Workflow skill within Claude Code is straightforward. When you need to prepare a PR, clean up branches, resolve a conflict, or tag a release, simply invoke the skill or request guidance from Claude Code. The skill will present you with a logical sequence of steps, including the exact commands to run and recommendations for documentation.

For example, to prepare a pull request:

1. Gather context about your changes

   bash

   git log main..HEAD --oneline    # Lists all commits on your branch not in main
   git diff main...HEAD --stat     # Shows all changed files
   git status                      # Checks for any uncommitted work

2. Draft the PR content

   • Title: concise, under 70 characters, summarizing the change
   • Body: summary explaining the "why", enumerate key changes, and provide a test plan
   • Use your actual commit history as reference, not just memory

3. Push your branch and create the PR

   bash

   git push -u origin HEAD
   gh pr create --title "Your PR Title" --body "$(cat <<'EOF'
   ## Summary
   - Key change 1
   - Key change 2
   
   ## Test plan
   - [ ] Manual test steps
   - [ ] Automated test coverage
   
   Generated with [Claude Code](https://claude.com/claude-code)
   EOF
   )"

4. Verify the PR in your browser

   bash

   gh pr view --web

For branch cleanup after merging:

1. Switch to the main branch and fetch the latest updates

   bash

   git checkout main && git pull

2. List merged branches (excluding 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 -n 1 git branch -d

Key Features

The Git Workflow skill covers several essential areas in modern development:

• Pull Request Preparation: Guides you through collecting change context, writing effective titles and summaries, and structuring PRs for clarity and reviewability.
• Branch Cleanup: Offers safe, repeatable steps to delete branches that have been merged, reducing repository clutter and confusion.
• Merge Conflict Resolution: Provides instructions for identifying, resolving, and verifying merge conflicts, helping to ensure a clean history.
• Monorepo Tag Handling: Assists in tagging releases accurately within large, multi-package repositories.
• Squash-and-Merge Patterns: Encourages consistent use of squash-and-merge, resulting in a linear, readable commit history and easier rollback if necessary.

Each feature emphasizes clarity, reproducibility, and safety, minimizing accidental data loss or repository mismanagement.

Best Practices

To maximize the benefit of the Git Workflow skill, consider the following best practices:

• Always review your commit history and diff before opening a PR. This helps catch mistakes early and prepares you to write a more informative summary.
• Write PR titles and descriptions for your reviewers. Avoid using branch names as titles; instead, describe what the change accomplishes and why it matters.
• Regularly clean up merged branches. This prevents confusion and reduces the risk of duplicate or conflicting work.
• Resolve conflicts promptly. When notified of a conflict, use the provided workflow to resolve differences and verify that the final result matches project expectations.
• Follow tagging conventions when working in monorepos to ensure releases are traceable and reliable.
• Embrace squash-and-merge for feature branches unless your team has a compelling reason not to, as it helps maintain a clean, understandable history.

Important Notes

• The Git Workflow skill is compatible with Claude Code only, and is intended for use within that environment.
• Always ensure your local environment matches the project’s Git configuration and conventions before running cleanup or branch deletion commands.
• For GitHub-specific commands (such as gh pr create), ensure the GitHub CLI (gh) is installed and authenticated.
• While the skill provides a guided process, it is essential to review each step and adapt to your team’s specific practices where necessary.
• The skill is open-source and available for review or contribution at https://github.com/jezweb/claude-skills/tree/main/plugins/dev-tools/skills/git-workflow.