git-workflow

Git Workflow Skill

Overview

This skill defines the git workflow patterns for the project, including branching strategies, commit conventions, and pull request guidelines.

Branching Strategy

Branch Types

Branch	Purpose	Naming
main	Production-ready code	Protected
develop	Integration branch	Protected
feature/*	New features	feature/description
bugfix/*	Bug fixes	bugfix/issue-description
hotfix/*	Production fixes	hotfix/critical-fix
release/*	Release preparation	release/v1.2.0

Branch Naming Convention

type/short-description

Examples:
feature/user-authentication
bugfix/login-validation
hotfix/security-patch
release/v2.0.0

Commit Conventions

Commit Message Format

type(scope): subject

body (optional)

footer (optional)

Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation
style	Formatting (no code change)
refactor	Code refactoring
test	Adding tests
chore	Maintenance
perf	Performance improvement
ci	CI/CD changes

Examples

# Feature
feat(auth): add JWT token validation

# Bug fix
fix(api): resolve null pointer in user lookup

# Documentation
docs(readme): update installation instructions

# Refactor
refactor(utils): simplify date formatting logic

Commit Guidelines

1. Keep commits atomic: One logical change per commit
2. Use present tense: "add feature" not "added feature"
3. Keep subject under 50 characters
4. Wrap body at 72 characters
5. Reference issues: Closes #123 or Fixes #456

Workflow Steps

Starting New Work

# 1. Start from develop
git checkout develop
git pull origin develop

# 2. Create feature branch
git checkout -b feature/my-feature

# 3. Make changes and commit
git add .
git commit -m "feat(scope): description"

# 4. Push branch
git push -u origin feature/my-feature

Creating Pull Request

# 1. Ensure up to date with develop
git checkout develop
git pull origin develop
git checkout feature/my-feature
git rebase develop

# 2. Push final changes
git push origin feature/my-feature

# 3. Create PR via GitHub/CLI
gh pr create --base develop --title "feat: description" --body "..."

PR Description Template

## Summary
[Brief description of changes]

## Changes Made
- [Change 1]
- [Change 2]

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

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

## Related Issues
Closes #XXX

Merging

# Squash merge for features
git checkout develop
git merge --squash feature/my-feature
git commit -m "feat(scope): complete feature description"
git push origin develop

# Delete feature branch
git branch -d feature/my-feature
git push origin --delete feature/my-feature

Common Tasks

Sync with Upstream

git fetch origin
git checkout develop
git pull origin develop
git checkout feature/my-feature
git rebase develop

Fix Merge Conflicts

# During rebase
git status  # See conflicted files
# Edit files to resolve conflicts
git add <resolved-files>
git rebase --continue

Amend Last Commit

# Change message
git commit --amend -m "new message"

# Add forgotten files
git add forgotten-file.js
git commit --amend --no-edit

Interactive Rebase (Clean History)

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

# In editor, change 'pick' to 'squash' for commits to combine

Protected Branch Rules

main Branch

• Requires PR with 1+ approval
• Requires passing CI
• No direct pushes
• Linear history (squash merge)

develop Branch

• Requires PR
• Requires passing CI
• No force push

Release Process

# 1. Create release branch
git checkout develop
git checkout -b release/v1.2.0

# 2. Update version numbers, changelog
# ... make release preparations ...

# 3. Merge to main
git checkout main
git merge release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

# 4. Merge back to develop
git checkout develop
git merge release/v1.2.0
git push origin develop

# 5. Clean up
git branch -d release/v1.2.0

Troubleshooting

Undo Last Commit (Keep Changes)

git reset --soft HEAD~1

Undo Last Commit (Discard Changes)

git reset --hard HEAD~1

Recover Deleted Branch

git reflog  # Find commit hash
git checkout -b recovered-branch <hash>

Clean Untracked Files

git clean -fd  # Remove untracked files and directories