tomevault-io 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
<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
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
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
# 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
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
# 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)
git checkout main
git merge feature/simple-change
Merge Commit (preserves branch history)
git checkout main
git merge --no-ff feature/important-feature
Rebase (linear history)
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
# 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
# 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)
# 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
# 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
# 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
# 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
- All CI checks pass
- Code reviewed and approved
- Branch is up to date with target
- No merge conflicts
- Tests cover new code
Common Workflows
Daily Development Flow
# 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
# 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
# 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"
# Create branch from current state
git checkout -b recovery-branch
# Or go back to branch
git checkout main
"Your branch has diverged"
# 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)"
# 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
# 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
# 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:
#!/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:
#!/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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.