Git Workflow

Purpose

Handle git operations with best practices for commit messages, pull/merge requests, and branch management. Ensures clean, professional git history without author attribution in descriptions.

Critical Rule: No Author Attribution

NEVER include author names in commit message bodies, PR descriptions, or MR descriptions.

• •Forbidden patterns: "Co-Authored-By:", "Authored by:", "Written by:", "Created by:"
• •Rationale: Git already tracks authors via metadata. Adding names to descriptions creates noise and maintenance burden.
• •Correct approach: Let git's authorship metadata handle attribution. Focus descriptions on WHAT and WHY, not WHO.

Examples

❌ WRONG - Author in description:

feat: add new feature

Co-Authored-By: Claude <noreply@anthropic.com>

✅ CORRECT - Clean description:

feat: add new feature

Add authentication middleware with JWT token validation.
Includes login endpoint and refresh token rotation.

When to Use

• •Creating git commits
• •Creating pull requests or merge requests
• •Managing git branches
• •Resolving merge conflicts
• •Reviewing git history
• •Amending commits (following safety rules)

Process

Creating Commits

1. •

   Stage relevant files

   bash

   git add [files]
   

2. •

   Write commit message

   • •Use Conventional Commits format (commitlint spec)
   • •Format: type(scope): description
   • •Keep subject line under 72 characters
   • •Wrap body at 72 characters
   • •Focus on WHAT and WHY, not HOW
   • •NEVER add Co-Authored-By or author attribution
3. •

   Create commit

   bash

   git commit -m "$(cat <<'EOF'
   type(scope): brief description
   
   Detailed explanation of changes and reasoning.
   EOF
   )"
   

Commit Message Types

Creating Pull/Merge Requests

1. •

   Ensure clean branch name

   bash

   git checkout -b feature/short-description
   

2. •

   Push to remote

   bash

   git push -u origin feature/short-description
   

3. •

   Create PR/MR with gh CLI

   bash

   gh pr create --title "type(scope): description" --body "$(cat <<'EOF'
   ## Summary
   - Bullet point 1
   - Bullet point 2
   
   ## Changes
   - Detailed change 1
   - Detailed change 2
   
   ## Testing
   - Test case 1
   - Test case 2
   EOF
   )"
   

PR/MR Description Template:

## Summary
[Brief overview - 2-3 bullet points]

## Changes
- [Specific change 1]
- [Specific change 2]
- [Specific change 3]

## Testing
- [Test case 1]
- [Test case 2]

## Checklist
- [ ] Tests pass
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

Handling Merge Conflicts

1. •

   Ensure main branch is up to date

   bash

   git checkout main
   git pull
   

2. •

   Rebase feature branch

   bash

   git checkout feature/branch
   git rebase main
   

3. •

   Resolve conflicts

   • •Open conflicted files
   • •Look for <<<<<, ====, >>>>> markers
   • •Choose correct content
   • •Remove conflict markers
   • •Save files
4. •

   Continue rebase

   bash

   git add [resolved-files]
   git rebase --continue
   

5. •

   Force push if needed

   bash

   git push --force-with-lease
   

Git Safety Rules

NEVER do these without explicit user permission:

• •git push --force (use --force-with-lease instead)
• •git reset --hard (warn user they'll lose work)
• •git clean -fd (warn about untracked files)
• •git commit --amend after push (requires force push)

Always warn user before:

• •Force pushing
• •Hard resetting
• •Cleaning untracked files
• •Rewriting public history

Branch Naming Conventions

feature/feature-name
bugfix/bug-description
hotfix/critical-fix
refactor/code-improvement
docs/documentation-update
test/test-coverage
release/version-number

Common Commands Reference

# Status
git status

# Branch operations
git branch                    # List branches
git checkout -b new-branch    # Create and switch
git branch -d old-branch      # Delete local
git push origin --delete branch-name  # Delete remote

# Staging
git add .                     # Stage all
git add file.txt              # Stage specific
git restore --staged file.txt # Unstage

# Commits
git commit -m "message"       # Commit staged
git log --oneline -5          # Recent commits
git show HEAD                 # Show last commit

# Remote sync
git fetch                     # Get remote changes
git pull                      # Fetch + merge
git push                      # Send to remote

Troubleshooting

"Commit message is empty"

• •Ensure message is in quotes
• •Check for unclosed heredoc (EOF)
• •Verify no trailing backslashes

"Nothing to commit"

• •Check git status to see if files are staged
• •Use git add to stage changes first

"Failed to push some refs"

• •Remote has new commits: git pull first
• •Diverged branches: git pull --rebase then resolve conflicts

Merge conflict markers not found

• •Run git status to see conflicted files
• •Open each file and search for <<<<<

Quality Checklist

Before completing git operations:

• • Commit message follows conventional format
• • No author attribution in description
• • Subject line under 72 characters
• • Body wrapped at 72 characters
• • Branch name follows conventions
• • PR/MR description includes summary and testing
• • No sensitive data in commits
• • Conflicts resolved (if applicable)

Integration with Other Skills

• •file-todos - Track TODO items in commits
• •workflows:compound - Document solved problems