| name | version-control-helper |
| description | Guide users through git workflows, best practices, commit messages, branching strategies, and resolving common version control issues. Use this when users need help with git operations or workflow decisions. |
| domain | project |
| type | helper |
| version | 1.0.0 |
| allowed-tools | ["Bash","Read"] |
Version Control Helper Skill
This skill provides guidance on git workflows, commit strategies, branch management, and resolving common version control issues for game development projects.
When to Use This Skill
Invoke this skill when the user:
- Asks "how do I use git for game dev?"
- Says "help me with git" or "explain git workflow"
- Needs commit message suggestions
- Asks about branching strategies
- Has merge conflicts and needs help
- Wants to organize git history
- Asks "should I commit this?"
- Says "what's a good git workflow for solo/team dev?"
Core Principle
Git enables safe iteration and collaboration:
- ✅ Commit often, push less often
- ✅ Write meaningful commit messages
- ✅ Branch for features, merge when stable
- ✅ Keep history clean and readable
- ✅ Never lose work
- ✅ Enable collaboration and code review
Commit Message Guidelines
Format: Conventional Commits
<type>(<scope>): <subject>
<body>
<footer>
Types
- feat: New feature
- fix: Bug fix
- refactor: Code refactoring (no behavior change)
- perf: Performance improvement
- docs: Documentation changes
- style: Code formatting (no logic change)
- test: Adding or updating tests
- chore: Build process, dependencies, tooling
- art: Art asset additions/changes
- audio: Audio asset additions/changes
- balance: Game balance tweaks
Examples
Good commit messages:
feat(weapons): add railgun with pierce mechanic
- Damage: 100
- Fire rate: 0.5/s
- Range: 600px
- Pierces up to 3 enemies
Closes #42
fix(player): prevent movement while paused
Player could move during pause menu if input buffered.
Now movement input is ignored when game_paused == true.
Fixes #38
refactor(enemies): extract hardcoded stats to resources
Converted all 5 enemy types to use EnemyData resources:
- Scout, Tank, Drone, Artillery, Elite
- Enables easy balancing without code changes
Related to #25
Bad commit messages:
❌ "fixed stuff"
❌ "wip"
❌ "update"
❌ "asdf"
❌ "final final FINAL version"
Subject Line Rules
- Use imperative mood ("add feature" not "added feature")
- Don't capitalize first letter (unless proper noun)
- No period at end
- Max 50 characters for subject
- Wrap body at 72 characters
Branching Strategies
Solo Developer (Simple Flow)
main
└─ feature/weapon-system
└─ fix/enemy-spawning
Strategy:
main = stable, working game- Feature branches for new systems
- Merge to main when feature works
- Tag releases on main
Commands:
git checkout -b feature/weapon-rules
git add .
git commit -m "feat(weapons): add target priority system"
git checkout main
git merge feature/weapon-rules
git branch -d feature/weapon-rules
Small Team (Git Flow Lite)
main (production)
└─ develop (integration)
└─ feature/player-movement
└─ feature/enemy-ai
└─ fix/collision-bug
Strategy:
main = releases only (tagged)develop = active development- Feature branches off
develop
- Merge to
develop, then main for releases
Commands:
git checkout develop
git checkout -b feature/wave-spawning
git commit -m "feat(waves): implement time-based spawning"
git checkout develop
git merge feature/wave-spawning
git checkout main
git merge develop
git tag -a v1.0.0 -m "Release 1.0.0"
Release Branches (Larger Projects)
main
└─ develop
├─ release/1.0
├─ feature/new-weapon
└─ hotfix/crash-fix
Strategy:
release/X.Y branches for stabilization- Hotfixes branch from
main for urgent production fixes
- Features continue on
develop during release stabilization
When to Commit
Commit Frequency
Good times to commit:
- ✅ Feature complete and working
- ✅ Bug fixed and tested
- ✅ End of work session (even if incomplete)
- ✅ Before risky refactoring
- ✅ After code review changes
When NOT to commit:
- ❌ Code doesn't compile
- ❌ Game crashes on start
- ❌ In middle of refactoring (use WIP commit, amend later)
Atomic Commits
One commit = one logical change
✅ Good:
feat(player): add dash ability
fix(enemies): correct pathfinding edge case
refactor(weapons): extract data to resources
❌ Bad:
"updated player, fixed enemies, changed weapons, added UI"
.gitignore for Godot Projects
Essential .gitignore:
# Godot-specific ignores
.import/
export.cfg
export_presets.cfg
# Godot 4+ specific
.godot/
# Builds
builds/
exports/
# Logs
*.log
# OS
.DS_Store
Thumbs.db
# IDE
.vscode/
.idea/
# Addons (if external)
addons/
# Sensitive data
*.secret
credentials.json
.env
Common Scenarios & Solutions
Scenario 1: "I made a mistake in last commit"
If not pushed yet:
git add .
git commit --amend --no-edit
git commit --amend -m "fix(player): correct movement speed"
If already pushed:
git add .
git commit -m "fix(player): correct movement speed regression from previous commit"
Scenario 2: "I need to undo last commit"
Keep changes, undo commit:
git reset --soft HEAD~1
Discard changes and commit:
git reset --hard HEAD~1
Scenario 3: "I have merge conflicts"
Resolve conflicts:
git status
git add <resolved-files>
git commit -m "merge: resolve conflicts in enemy system"
Abort merge:
git merge --abort
Scenario 4: "I want to save work but not commit"
Use git stash:
git stash save "WIP: weapon rule system half done"
git stash pop
Scenario 5: "I committed to wrong branch"
If not pushed:
git log
git reset --hard HEAD~1
git checkout correct-branch
git cherry-pick <commit-hash>
Scenario 6: "I need to work on old version"
Create branch from old commit/tag:
git log --oneline
git checkout <commit-hash>
git checkout -b hotfix/old-version-bug
Git Workflow Recommendations by Team Size
Solo Developer
- Use
main + feature branches
- Commit frequently to feature branches
- Merge to
main when stable
- Tag releases on
main
2-3 Developers
- Use
main + develop + feature branches
- Pull requests for code review (GitHub/GitLab)
- Merge to
develop, periodically merge to main for releases
4+ Developers
- Use Git Flow (main, develop, feature, release, hotfix)
- Enforce PR reviews before merging
- CI/CD pipeline for automated testing
- Protected
main branch (no direct commits)
Game Dev Specific Tips
Binary Assets
Problem: Large binary files (sprites, audio) bloat git history
Solution: Git LFS (Large File Storage)
git lfs install
git lfs track "*.png"
git lfs track "*.wav"
git lfs track "*.ogg"
git add .gitattributes
git commit -m "chore: configure git lfs for binary assets"
Godot-Specific Considerations
Commit .import folder?
- ❌ Don't commit
.import/ (regenerated by Godot)
- ✅ Do commit source assets (images, audio)
- ✅ Godot will regenerate imports on other machines
Scene conflicts:
.tscn files are text-based, merge carefully- Use "Tools → Reload from Disk" in Godot after git operations
Export presets:
- ❌ Don't commit
export_presets.cfg (contains local paths)
- ✅ Document export settings in README
Tagging Releases
Create annotated tag:
git tag -a v1.0.0 -m "Release 1.0.0 - Initial release"
Push tags:
git push origin v1.0.0
git push --tags
Tag naming:
- Use semantic versioning:
v1.0.0, v1.1.0, v2.0.0
- Pre-releases:
v1.0.0-alpha.1, v1.0.0-beta.2, v1.0.0-rc.1
Suggested Git Aliases
Add to ~/.gitconfig:
[alias]
s = status -s
lg = log --oneline --graph --decorate --all
last = log -1 HEAD --stat
undo = reset --soft HEAD~1
amend = commit --amend --no-edit
d = diff
ds = diff --staged
Pre-Commit Hooks (Advanced)
Prevent commits that:
- Have syntax errors (GDScript linting)
- Have merge conflict markers
- Are too large
- Have debug code (e.g.,
print("DEBUG:"))
Example hook: .git/hooks/pre-commit
#!/bin/bash
if git diff --cached | grep -i "print.*debug"; then
echo "Error: Debug print statements found"
exit 1
fi
GitHub/GitLab Integration
Pull Request Template
Create .github/pull_request_template.md:
## What does this PR do?
[Brief description]
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactor
- [ ] Documentation
## Testing
- [ ] Tested in-game
- [ ] No console errors
- [ ] Doesn't break existing features
## Screenshots
[If UI/visual changes]
Issue Templates
Create .github/ISSUE_TEMPLATE/bug_report.md
Troubleshooting Common Issues
"I have uncommitted changes and can't switch branches"
git stash
git checkout other-branch
git checkout original-branch
git stash pop
"My repo is huge from binary assets"
"I accidentally committed secrets"
git reset HEAD~1
git filter-branch --force --index-filter \
"git rm --cached --ignore-unmatch path/to/secret" \
--prune-empty --tag-name-filter cat -- --all
Example Invocations
User: "How do I use git for my game?"
User: "What's a good commit message for adding a weapon?"
User: "I have merge conflicts, help!"
User: "Should I commit .import folder?"
User: "What branching strategy for solo dev?"
User: "How do I undo last commit?"
Workflow Summary
- User asks git-related question
- Assess user's situation (solo/team, experience level, specific issue)
- Provide tailored guidance with commands
- Explain rationale (why this approach is recommended)
- Show examples specific to game dev / Godot
- Suggest preventive measures (hooks, aliases, workflows)
This skill helps users maintain clean git history, collaborate effectively, and never lose work during game development.
