Git Workflow

Overview

This skill provides comprehensive git workflow best practices, branching strategies, and collaboration patterns. Use it to ensure consistent, professional git usage across your projects.

When to Use This Skill

Creating commits with proper messages
Establishing branching strategies (Git Flow, GitHub Flow, Trunk-Based)
Handling pull requests and code reviews
Managing releases and hotfixes
Resolving merge conflicts
Setting up git hooks and automation

Core Workflows

Commit Message Guidelines

Follow the Conventional Commits specification for clear, semantic commit messages:

Format:

<body>

Types:

feat : New feature
fix : Bug fix
docs : Documentation changes
style : Formatting, missing semicolons, etc.
refactor : Code restructuring without behavior changes
perf : Performance improvements
test : Adding or updating tests
chore : Build process, dependencies, tooling
ci : CI/CD pipeline changes

Examples:

feat(auth): add JWT token refresh mechanism

Implement automatic token refresh before expiration. Tokens are refreshed 5 minutes before expiry.

Closes #123

fix(api): handle null responses in user service

Add defensive null checks to prevent NPE when external API returns unexpected null values.

Fixes #456

Branching Strategies

Git Flow (Traditional)

Best for: Scheduled releases, multiple version support

Branches:

main : Production-ready code
develop : Integration branch for features
feature/* : New features
release/* : Release preparation
hotfix/* : Emergency production fixes

Workflow:

Start new feature

git checkout develop git checkout -b feature/user-authentication

Finish feature

git checkout develop git merge feature/user-authentication git branch -d feature/user-authentication

Create release

git checkout -b release/1.2.0

Bump version, final testing

git checkout main git merge release/1.2.0 git tag -a v1.2.0 -m "Release 1.2.0" git checkout develop git merge release/1.2.0

GitHub Flow (Simplified)

Best for: Continuous deployment, web applications

Branches:

main : Always deployable
feature/* : All changes

Workflow:

Start work

git checkout -b feature/add-dark-mode

Make changes, commit often

git commit -m "feat(ui): add dark mode toggle"

Push and create PR

git push origin feature/add-dark-mode

Create pull request on GitHub

After review and CI passes, merge to main

Deploy from main

Trunk-Based Development

Best for: High-frequency releases, mature CI/CD

Key principles:

All work on main or very short-lived feature branches (<1 day)
Feature flags for incomplete features
Rigorous automated testing

Pull Request Best Practices

PR Description Template:

Summary

Brief description of changes

Type of Change

Bug fix
New feature
Breaking change
Documentation update

Testing Done

Unit tests added/updated
Integration tests pass
Manual testing completed

Screenshots (if applicable)

Related Issues

Closes #123

Review Checklist:

Code follows project conventions
Tests cover new functionality
Documentation is updated
No sensitive data committed
CI/CD pipeline passes
Performance impact considered

Handling Merge Conflicts

Process:

Update your branch with latest main

git checkout feature/my-feature git fetch origin git merge origin/main

If conflicts occur

1. Open conflicted files

2. Look for conflict markers: <<<<<<< ======= >>>>>>>

3. Resolve manually, keeping appropriate changes

4. Remove conflict markers

5. Test the resolved code

git add <resolved-files> git commit -m "chore: resolve merge conflicts with main"

Conflict Resolution Tips:

Communicate with the other developer if unsure
Prefer rebasing for cleaner history (if branch not shared)
Use git mergetool for complex conflicts
Always test after resolution

Git Hooks and Automation

Common hooks to consider:

pre-commit:

Run linters, formatters

npm run lint npm run format

Run fast tests

npm run test:unit

commit-msg:

Validate commit message format

Ensure conventional commits compliance

pre-push:

Run full test suite

npm run test

Run build

npm run build

Advanced Patterns

Rebasing vs Merging

Use Rebase When:

Working on personal feature branch
Want linear history
Need to incorporate upstream changes

git fetch origin git rebase origin/main

Use Merge When:

Working on shared branches
Want to preserve complete history
Merging pull requests

git merge origin/main

Cherry-Picking

Use to apply specific commits to another branch:

Find commit hash

git log

Apply to current branch

git cherry-pick <commit-hash>

Interactive Rebase

Clean up commit history before pushing:

Rebase last 3 commits

git rebase -i HEAD~3

Options: pick, reword, squash, fixup, drop

Common Scenarios

Undo Last Commit (Not Pushed)

git reset --soft HEAD~~1 # Keep changes staged git reset HEAD~~1 # Keep changes unstaged git reset --hard HEAD~1 # Discard changes

Undo Pushed Commit

Create new commit that reverses changes

git revert <commit-hash> git push origin main

Stash Changes

Save work in progress

git stash save "WIP: feature description"

List stashes

git stash list

Apply stash

git stash apply stash@{0}

Apply and remove

git stash pop

Update Commit Message

Last commit (not pushed)

git commit --amend -m "new message"

Older commit

git rebase -i HEAD~n # Use 'reword'

Resources

references/

This skill includes reference documentation for deeper dives:

git-best-practices.md: Comprehensive git guidelines
branching-models.md: Detailed branching strategy comparisons
conflict-resolution.md: Advanced merge conflict patterns

Quick Reference

Daily Commands:

git status # Check status git add <file> # Stage file git commit -m "message" # Commit with message git push origin <branch> # Push to remote git pull origin <branch> # Pull from remote git checkout -b <branch> # Create and switch branch git merge <branch> # Merge branch

Inspection:

git log --oneline --graph # Visual commit history git diff # See unstaged changes git diff --staged # See staged changes git show <commit> # Show commit details git blame <file> # See who changed each line

Cleanup:

git branch -d <branch> # Delete local branch git push origin :<branch> # Delete remote branch git clean -fd # Remove untracked files git gc # Garbage collection