name: git-workflows description: | Generates PR descriptions, commit messages, release notes, and manages branch strategies, changelog automation, and git hooks. Use when creating pull requests, writing commits, preparing releases, managing branches, or automating changelogs. Triggers: "git", "PR", "push", "pull", "git workflows", "git automation", "commit messages", "PR description", "changelog", "branch strategy", "release automation".

Git Workflows

Automated git documentation, branch management, and release automation.

Quick Start

Generate PR description:

Create a PR description for the current branch compared to main

Write commit message:

Generate a commit message for my staged changes

Update changelog:

Update the changelog based on commits since the last release

Capabilities

1. PR Description Generation

Create comprehensive pull request descriptions from branch diffs.

Analysis Process

# 1. Get branch info
git branch --show-current
git log main..HEAD --oneline

# 2. Get full diff
git diff main...HEAD

# 3. Get changed files
git diff main...HEAD --name-status

# 4. Get commit messages
git log main..HEAD --pretty=format:"%s%n%b"

PR Description Template

## Summary

{1-3 sentences describing what this PR does and why}

## Changes

### Added
- {New features or files}

### Changed
- {Modifications to existing functionality}

### Fixed
- {Bug fixes}

## Testing

- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] {Specific test scenarios}

## Related Issues

- Closes #{issue_number}
- Related to #{issue_number}

## Checklist

- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Tests added/updated
- [ ] Documentation updated

See templates/pr-description.md for more templates.

2. Commit Message Generation

Create meaningful commit messages from staged changes.

Conventional Commits Format

<type>(<scope>): <subject>

<body>

<footer>

Types:

Type	When to Use
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation only
`style`	Formatting, no code change
`refactor`	Code restructuring
`perf`	Performance improvement
`test`	Adding/updating tests
`chore`	Maintenance tasks
`ci`	CI/CD changes
`build`	Build system changes

Example Messages

feat(auth): add OAuth2 authentication support

- Add Google OAuth provider integration
- Create session management middleware
- Add user profile endpoint

Closes #123

fix(api): correct pagination offset calculation

The offset was being calculated as page * limit instead of
(page - 1) * limit, causing the first item to be skipped.

Fixes #456

3. Branch Naming Conventions

Enforce consistent branch naming patterns.

Naming Patterns

Pattern	Example	Use Case
`feature/<ticket>-<description>`	`feature/PROJ-123-user-auth`	New features
`fix/<ticket>-<description>`	`fix/PROJ-456-login-error`	Bug fixes
`hotfix/<ticket>-<description>`	`hotfix/PROJ-789-security-patch`	Production fixes
`release/<version>`	`release/1.2.0`	Release branches
`chore/<description>`	`chore/update-dependencies`	Maintenance

Validation Script

#!/bin/bash
# .git/hooks/pre-push

branch=$(git rev-parse --abbrev-ref HEAD)
pattern="^(feature|fix|hotfix|release|chore)/[a-z0-9-]+$"

if [[ ! $branch =~ $pattern ]]; then
  echo "Branch name '$branch' doesn't match pattern: $pattern"
  echo "Examples: feature/PROJ-123-add-login, fix/PROJ-456-null-check"
  exit 1
fi

See references/branch-strategies.md for strategy comparison.

4. Changelog Automation

Automatically update CHANGELOG.md from commits.

Generation Process

# Get commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"%s|%h|%an" > commits.txt

# Parse conventional commits
# feat: -> Added
# fix: -> Fixed
# docs: -> Documentation
# BREAKING CHANGE: -> Breaking Changes

Keep a Changelog Format

# Changelog

## [Unreleased]

### Added
- New user authentication flow (#123) - @developer

### Changed
- Updated dependencies to latest versions

### Fixed
- Fixed race condition in queue processing (#124)

### Security
- Updated vulnerable dependency xyz to 2.0.0

## [1.2.0] - 2024-01-15

### Added
- Initial release features...

[Unreleased]: https://github.com/owner/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/owner/repo/releases/tag/v1.2.0

Automation Tools

# conventional-changelog
npx conventional-changelog-cli -p angular -i CHANGELOG.md -s

# standard-version
npx standard-version

# semantic-release (fully automated)
npx semantic-release

5. Version Bumping from Commits

Determine semantic version from commit history.

Semver Detection

Commit Type	Version Bump
`BREAKING CHANGE:`	Major (1.0.0 -> 2.0.0)
`feat:`	Minor (1.0.0 -> 1.1.0)
`fix:`, `perf:`	Patch (1.0.0 -> 1.0.1)

Detection Script

#!/bin/bash
# determine-version.sh

last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
current=${last_tag#v}

# Check for breaking changes
if git log $last_tag..HEAD --pretty=format:"%s%b" | grep -q "BREAKING CHANGE"; then
  echo "major"
elif git log $last_tag..HEAD --pretty=format:"%s" | grep -qE "^feat(\(.+\))?:"; then
  echo "minor"
else
  echo "patch"
fi

npm version Integration

# Automatic version bump based on commits
bump=$(./determine-version.sh)
npm version $bump -m "chore(release): %s"
git push --follow-tags

6. Git Hooks

Pre-commit and commit-msg validation.

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Run linting
npm run lint --silent || {
  echo "Linting failed. Fix errors before committing."
  exit 1
}

# Run type checking
npm run type-check --silent || {
  echo "Type checking failed. Fix errors before committing."
  exit 1
}

# Check for debug statements
if git diff --cached | grep -E "console\.(log|debug)|debugger"; then
  echo "Remove debug statements before committing."
  exit 1
fi

# Check for secrets
if git diff --cached | grep -E "(password|api_key|secret)\s*=\s*['\"][^'\"]+['\"]"; then
  echo "Potential secrets detected. Review before committing."
  exit 1
fi

Commit-msg Hook

#!/bin/bash
# .git/hooks/commit-msg

commit_msg=$(cat "$1")
pattern="^(feat|fix|docs|style|refactor|perf|test|chore|ci|build)(\(.+\))?: .{1,72}"

if [[ ! $commit_msg =~ $pattern ]]; then
  echo "Invalid commit message format!"
  echo "Expected: <type>(<scope>): <subject>"
  echo "Example: feat(auth): add login endpoint"
  echo ""
  echo "Types: feat, fix, docs, style, refactor, perf, test, chore, ci, build"
  exit 1
fi

See references/git-hooks.md for more hook examples.

7. Merge Conflict Resolution

Guide for resolving merge conflicts.

Common Conflict Patterns

Same line edited:

<<<<<<< HEAD
const config = { timeout: 5000 };
=======
const config = { timeout: 10000 };
>>>>>>> feature/new-timeout

Resolution options:

Keep ours: git checkout --ours <file>
Keep theirs: git checkout --theirs <file>
Manual merge: Edit file and remove markers

Resolution Workflow

# 1. Start merge
git merge feature-branch

# 2. See conflicted files
git status

# 3. Open in merge tool
git mergetool

# 4. After resolving
git add <resolved-files>
git commit

Prevention Strategies

Rebase frequently: git pull --rebase
Small, focused branches
Clear code ownership
Modular file structure

8. Rebase and Squash Guidance

Clean up commit history before merging.

Interactive Rebase

# Squash last 5 commits
git rebase -i HEAD~5

# In editor:
pick abc1234 First commit
squash def5678 Second commit
squash ghi9012 Third commit
fixup jkl3456 WIP commit (discard message)
reword mno7890 Final commit (edit message)

Rebase onto Main

# Update feature branch with main
git checkout feature-branch
git fetch origin
git rebase origin/main

# If conflicts, resolve then:
git rebase --continue
# Or abort:
git rebase --abort

Squash Merge

# Merge with squash (combines all commits)
git checkout main
git merge --squash feature-branch
git commit -m "feat: add user authentication (#123)"

9. Git Bisect Assistance

Find the commit that introduced a bug.

Bisect Workflow

# Start bisect
git bisect start

# Mark current as bad
git bisect bad

# Mark known good commit
git bisect good v1.0.0

# Git checks out middle commit
# Test and mark:
git bisect good  # if works
git bisect bad   # if broken

# Repeat until found
# Git will output: "abc1234 is the first bad commit"

# End bisect
git bisect reset

Automated Bisect

# Run test script automatically
git bisect start HEAD v1.0.0
git bisect run npm test

# Or custom script
git bisect run ./check-bug.sh

10. Stale Branch Cleanup

Identify and remove stale branches.

List Stale Branches

# Branches merged into main
git branch --merged main

# Remote branches not updated in 30 days
git for-each-ref --sort=committerdate refs/remotes/ \
  --format='%(committerdate:relative) %(refname:short)' |
  grep -E "months? ago"

# Branches with no remote
git branch -vv | grep ': gone]'

Cleanup Script

#!/bin/bash
# cleanup-branches.sh

# Delete merged local branches (except main/develop)
git branch --merged main |
  grep -vE "^\*|main|develop" |
  xargs -r git branch -d

# Prune remote tracking branches
git fetch --prune

# Delete local branches without remote
git branch -vv |
  grep ': gone]' |
  awk '{print $1}' |
  xargs -r git branch -D

11. Branch Strategies

Choose the right branching strategy.

GitFlow

main ─────────────────────────────────────────
       \                    /
        develop ───────────────────────
         \         /    \         /
          feature/a    feature/b

Best for: Large teams, scheduled releases

Trunk-Based Development

main ──●──●──●──●──●──●──●──●──●──
       │  │     │     │
      short-lived branches (< 1 day)

Best for: Small teams, continuous deployment

GitHub Flow

main ─────────────────────────────
       \         /    \       /
        feature/a     feature/b

Best for: Web applications, simple workflow

See references/branch-strategies.md for detailed comparison.

Release Workflow

Release Checklist

## Release v{version}

### Pre-Release
- [ ] All PRs for release merged
- [ ] CI green on main
- [ ] Version bumped
- [ ] CHANGELOG.md updated
- [ ] Documentation updated

### Release
- [ ] Tag created: git tag -a v{version} -m "Release v{version}"
- [ ] Tag pushed: git push --tags
- [ ] GitHub release created
- [ ] Package published

### Post-Release
- [ ] Announcement posted
- [ ] Documentation site updated
- [ ] Stakeholders notified

GitHub Release Command

# Create release with notes
gh release create v1.3.0 \
  --title "v1.3.0" \
  --notes-file RELEASE_NOTES.md \
  --target main

# Auto-generate notes from PRs
gh release create v1.3.0 --generate-notes

Hook Integration

PreToolUse Hook - Commit Message Validation

Before commits, validate message format:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "command": "validate-commit.sh",
      "condition": "contains(input, 'git commit')"
    }]
  }
}

Script example:

#!/bin/bash
# validate-commit.sh

# Extract commit message from command
message=$(echo "$INPUT" | grep -oP '(?<=-m ")[^"]+')

pattern="^(feat|fix|docs|style|refactor|perf|test|chore|ci|build)(\(.+\))?: .{1,72}"

if [[ ! $message =~ $pattern ]]; then
  echo "BLOCK: Invalid commit message format"
  echo "Expected: <type>(<scope>): <subject>"
  echo "Got: $message"
  exit 1
fi

echo "Commit message format valid"

Hook response pattern:

interface CommitValidationResponse {
  valid: boolean;
  message?: string;
  suggestions?: string[];
}

PostToolUse Hook - Auto-Changelog

After commits, suggest changelog updates:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "command": "suggest-changelog.sh",
      "condition": "contains(output, 'create mode') || contains(output, 'insertions')"
    }]
  }
}

CI/CD Integration

GitHub Actions

name: Release
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate changelog
        run: |
          npx conventional-changelog-cli -p angular -r 2 > RELEASE_NOTES.md

      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          body_path: RELEASE_NOTES.md
          draft: false
          prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Automated Version Bump

name: Version Bump
on:
  push:
    branches: [main]

jobs:
  version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Bump version
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          npx standard-version
          git push --follow-tags

Pre-commit with Husky

# Install husky
npm install --save-dev husky
npx husky init

# Add pre-commit hook
echo "npm run lint && npm test" > .husky/pre-commit

# Add commit-msg hook
echo 'npx commitlint --edit "$1"' > .husky/commit-msg

Templates

templates/pr-description.md - PR description templates
templates/release-notes.md - Release notes templates
templates/commit-message.md - Commit message examples

Reference Files

references/conventional-commits.md - Commit message conventions
references/branch-strategies.md - Branch strategy comparison
references/git-hooks.md - Git hook examples and patterns

Sign in to Comment

git-workflows