Git Workflow Skill

When to Use This Skill

Use this skill when:

•Creating commits with proper messages
•Managing branches and merges
•Resolving merge conflicts
•Reviewing Git history
•Performing Git operations safely
•Following Git best practices

Commit Message Guidelines

Format

code

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

<body>

<footer>

Types

•feat: New feature for the user
•fix: Bug fix
•docs: Documentation changes
•style: Code formatting (no logic change)
•refactor: Code restructuring (no feature/fix)
•perf: Performance improvements
•test: Adding or updating tests
•chore: Maintenance tasks
•ci: CI/CD configuration changes
•build: Build system or dependencies

Rules

•Subject line: max 50 characters
•Use imperative mood: "add" not "added" or "adds"
•No period at end of subject line
•Body: wrap at 72 characters
•Explain WHAT and WHY, not HOW
•Separate subject from body with blank line

Examples

code

feat(auth): add JWT token refresh mechanism

Implement automatic token refresh to improve user experience.
Users will no longer be logged out during active sessions.

- Add refresh token endpoint
- Implement token rotation logic
- Add background refresh timer

Closes #234

code

fix(api): prevent null pointer exception in user profile

Add null check before accessing user.email property.
This was causing crashes when users had incomplete profiles.

Fixes #456

Commit Size Guidelines

Ideal Commit Sizes

•Small: 10-50 lines (bug fixes, small tweaks)
•Medium: 50-300 lines (features, refactors)
•Large: 300-500 lines (major features - consider splitting)
•Too Large: 500+ lines (definitely split into multiple commits)

Atomic Commit Principle

Each commit should:

•Build successfully
•Pass all tests
•Represent one logical change
•Be independently revertable

Staging Strategy

bash

# Stage specific files only
git add src/component.js tests/component.test.js

# Interactive staging for partial file commits
git add -p filename.js

# Review before committing
git diff --staged

# Commit with message
git commit -m "feat: add user profile component"

Branch Management

Branch Naming Conventions

code

feature/short-description    # New features
fix/bug-description         # Bug fixes
hotfix/critical-fix         # Production hotfixes
refactor/what-refactored    # Code refactoring
docs/what-documented        # Documentation
test/what-tested            # Test additions
chore/maintenance-task      # Maintenance

Branch Workflow

bash

# Create and switch to new branch
git checkout -b feature/user-notifications

# Work and commit regularly
git add src/notifications.js
git commit -m "feat: add notification service"

# Keep branch updated with main
git checkout main
git pull origin main
git checkout feature/user-notifications
git merge main

# Push to remote
git push origin feature/user-notifications

# Delete after merge
git branch -d feature/user-notifications
git push origin --delete feature/user-notifications

Merge Strategies

Fast-Forward Merge (cleanest history)

bash

git checkout main
git merge feature/simple-change

Merge Commit (preserves branch history)

bash

git checkout main
git merge --no-ff feature/important-feature

Rebase (linear history)

bash

git checkout feature/my-branch
git rebase main
# Resolve conflicts if any
git push --force-with-lease origin feature/my-branch

When to Use Each

•Fast-forward: Simple, quick changes
•Merge commit: Team features, want to preserve context
•Rebase: Personal branches, want clean linear history
•Never rebase: Public/shared branches

Conflict Resolution

Process

bash

# 1. Start merge or rebase
git merge feature/branch
# CONFLICT appears

# 2. See conflicted files
git status

# 3. Open conflicted file, look for:
incoming branch content

# 4. Resolve by:
# - Keeping one version
# - Combining both versions
# - Writing new solution

# 5. Stage resolved files
git add resolved-file.js

# 6. Complete merge
git commit  # for merge
# or
git rebase --continue  # for rebase

Conflict Prevention

•Pull/merge main frequently
•Make smaller, focused commits
•Communicate with team about file changes
•Use feature flags for large changes

History Management

Viewing History

bash

# Basic log
git log

# Compact view
git log --oneline --graph --all

# See changes in commits
git log -p

# Search commits
git log --grep="search term"
git log --author="name"

# See what changed in a file
git log --follow filename.js

Amending Commits (before push)

bash

# Fix last commit message
git commit --amend -m "Better message"

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

# Change multiple commits
git rebase -i HEAD~3

Undoing Changes

bash

# Discard working directory changes
git checkout -- filename.js

# Unstage files
git reset HEAD filename.js

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Revert a commit (create new commit)
git revert <commit-hash>

Stashing

When to Stash

•Switch branches but not ready to commit
•Pull latest changes
•Quick context switch
•Save experimental work

Stash Commands

bash

# Save current work
git stash save "WIP: working on feature X"

# List stashes
git stash list

# Apply most recent stash (keep stash)
git stash apply

# Apply and remove stash
git stash pop

# Apply specific stash
git stash apply stash@{2}

# Delete stash
git stash drop stash@{0}

# Clear all stashes
git stash clear

Remote Operations

Safe Push/Pull

bash

# Always pull before push
git pull origin main

# Push with lease (safer than force)
git push --force-with-lease origin feature/branch

# Fetch without merging
git fetch origin

# See remote branches
git branch -r

# Track remote branch
git checkout --track origin/feature/branch

Git Best Practices Checklist

Before Committing

• Code builds successfully
• Tests pass locally
• Linting passes
• Only related changes staged
• Reviewed diff with git diff --staged
• Commit message is clear and descriptive

Before Pushing

• Pulled latest changes
• Resolved any conflicts
• Tests still pass after merge
• Commit history is clean

Before Merging PR

Common Workflows

Daily Development Flow

bash

# Morning: Get latest
git checkout main
git pull origin main

# Start work
git checkout -b feature/new-thing

# Work for 30-60 mins, then commit
git add src/
git commit -m "feat: add initial structure"

# Continue working, commit regularly
# ...commits...

# End of day: Push
git push origin feature/new-thing

Hotfix Flow

bash

# Create hotfix from main
git checkout main
git pull origin main
git checkout -b hotfix/critical-bug

# Fix and test
git add fixed-file.js
git commit -m "fix: resolve critical production bug"

# Push and merge ASAP
git push origin hotfix/critical-bug
# Create PR, get quick review, merge

Feature Branch Flow

bash

# Create feature branch
git checkout -b feature/user-dashboard

# Commit regularly (atomic commits)
# Every 30-90 minutes of work

# Stay updated with main
git fetch origin
git merge origin/main

# When complete, push and create PR
git push origin feature/user-dashboard

Troubleshooting

"Detached HEAD state"

bash

# Create branch from current state
git checkout -b recovery-branch

# Or go back to branch
git checkout main

"Your branch has diverged"

bash

# If you want remote version
git reset --hard origin/main

# If you want local version
git push --force-with-lease origin main

# If you want to merge both
git pull --rebase origin main

"Permission denied (publickey)"

bash

# Check SSH key
ssh -T git@github.com

# Add SSH key if needed
ssh-keygen -t ed25519 -C "your_email@example.com"
# Add to GitHub settings

Accidentally committed secrets

bash

# Remove from last commit
git reset HEAD~1
# Edit .gitignore, recommit

# Remove from history (if pushed)
# Use git-filter-repo or BFG Repo-Cleaner
# Then rotate the compromised secrets!

Quick Reference Commands

bash

# Status & Info
git status                    # Current state
git log --oneline            # Commit history
git diff                     # Unstaged changes
git diff --staged            # Staged changes

# Basic Operations
git add <file>               # Stage changes
git commit -m "message"      # Commit
git push origin <branch>     # Push to remote
git pull origin <branch>     # Pull from remote

# Branching
git branch                   # List branches
git branch <name>            # Create branch
git checkout <branch>        # Switch branch
git checkout -b <branch>     # Create and switch
git branch -d <branch>       # Delete branch

# Merging
git merge <branch>           # Merge branch
git merge --abort            # Cancel merge
git rebase <branch>          # Rebase onto branch
git rebase --abort           # Cancel rebase

# Undoing
git checkout -- <file>       # Discard changes
git reset HEAD <file>        # Unstage file
git reset --soft HEAD~1      # Undo commit, keep changes
git reset --hard HEAD~1      # Undo commit, discard changes
git revert <commit>          # Create reverting commit

# Stashing
git stash                    # Save work
git stash pop                # Restore work
git stash list               # List stashes

# Remote
git remote -v                # Show remotes
git fetch origin             # Get remote changes
git pull origin main         # Fetch and merge
git push origin main         # Push to remote

Integration with CI/CD

Pre-commit Hooks

Create .git/hooks/pre-commit:

bash

#!/bin/sh
# Run tests before commit
npm test
if [ $? -ne 0 ]; then
  echo "Tests failed. Commit aborted."
  exit 1
fi

Commit Message Validation

Create .git/hooks/commit-msg:

bash

#!/bin/sh
# Validate commit message format
commit_msg=$(cat "$1")
if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .+"; then
  echo "Invalid commit message format"
  echo "Use: <type>(<scope>): <subject>"
  exit 1
fi

Tips for AI Collaboration

When working with AI agents like Copilot:

•Commit frequently: AI can track changes better
•Clear messages: Help AI understand intent
•Branch per feature: Keep AI context focused
•Review AI commits: Always check git diff --staged
•Use conventional commits: AI can generate better messages

Additional Resources

•Git documentation: https://git-scm.com/doc
•Conventional Commits: https://www.conventionalcommits.org/
•GitHub Flow: https://guides.github.com/introduction/flow/
•Git Flight Rules: https://github.com/k88hudson/git-flight-rules