Git Workflow

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

   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

   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

   git checkout -b feature/short-description
   

2. Push to remote

   git push -u origin feature/short-description
   

3. Create PR/MR with gh CLI

   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

   git checkout main
   git pull
   

2. Rebase feature branch

   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

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

5. Force push if needed

   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