The "Holy Bible" for embedded engineers
Version control workflows are essential for managing source code changes in embedded system development. This guide covers Git-based workflows, branching strategies, code review processes, and continuous integration practices that enable teams to collaborate effectively while maintaining code quality and project stability.
Version control systems enable developers to:
Workflow Benefits:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Code │───▶│ Team │───▶│ Quality │───▶│ Release │
│ History │ │ Collaboration│ │ Assurance │ │ Management │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Audit │ │ Parallel │ │ Automated │ │ Stable │
│ Trail │ │ Development│ │ Testing │ │ Releases │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
# Repository initialization and setup
git init # Initialize new repository
git clone <url> # Clone existing repository
git remote add origin <url> # Add remote origin
# Basic workflow commands
git add <file> # Stage files for commit
git commit -m "message" # Commit staged changes
git push origin <branch> # Push commits to remote
git pull origin <branch> # Pull latest changes
# Status and information
git status # Show working directory status
git log # Show commit history
git diff # Show unstaged changes
git branch # List local branches
git checkout <branch> # Switch to branch
# Global configuration
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global core.editor "vim"
git config --global init.defaultBranch main
# Repository-specific configuration
git config user.name "Project Specific Name"
git config user.email "project@example.com"
# Useful aliases
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
# Credential management
git config --global credential.helper store
git config --global credential.helper cache --timeout=3600
# .gitignore for embedded projects
# Build artifacts
build/
*.o
*.elf
*.bin
*.hex
*.map
*.lst
# Object files
*.obj
*.exe
*.dll
*.so
*.dylib
# Debug files
*.dSYM/
*.su
*.idb
*.pdb
# IDE files
.vscode/
.idea/
*.swp
*.swo
*~
# OS files
.DS_Store
Thumbs.db
# Dependencies
vendor/
node_modules/
# Logs
*.log
logs/
# Temporary files
*.tmp
*.temp
# Git Flow branching model
# Main branches
main # Production-ready code
develop # Integration branch for features
# Supporting branches
feature/feature-name # New features
release/version # Release preparation
hotfix/issue-description # Critical bug fixes
# Branch creation commands
git checkout -b feature/new-feature develop
git checkout -b release/v1.2.0 develop
git checkout -b hotfix/critical-bug main
# Feature branch workflow
git checkout develop
git pull origin develop
git checkout -b feature/user-authentication
# ... make changes ...
git add .
git commit -m "Add user authentication feature"
git push origin feature/user-authentication
# Create pull request to merge into develop
# Trunk-based development (simplified workflow)
# Main branch only
main # Single main branch
# Short-lived feature branches
feature/quick-feature # Short-lived feature branches
# ... make changes ...
git add .
git commit -m "Add quick feature"
git push origin feature/quick-feature
# Merge directly to main after review
# Release tags
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0
# Branch naming patterns
feature/user-auth # New features
bugfix/login-error # Bug fixes
hotfix/security-patch # Critical fixes
release/v1.2.0 # Release preparation
chore/update-dependencies # Maintenance tasks
docs/api-documentation # Documentation updates
test/unit-test-coverage # Testing improvements
# Ticket-based naming
feature/PROJ-123-user-auth # Feature with ticket number
bugfix/PROJ-456-login-bug # Bug fix with ticket number
hotfix/PROJ-789-crash-fix # Hotfix with ticket number
# Pull request workflow
# 1. Create feature branch
git checkout -b feature/new-feature main
# 2. Make changes and commit
git add .
git commit -m "Implement new feature"
# 3. Push branch to remote
git push origin feature/new-feature
# 4. Create pull request on GitHub/GitLab
# - Set target branch (main or develop)
# - Add description and reviewers
# - Link related issues
# 5. Address review feedback
git add .
git commit -m "Address review feedback"
git push origin feature/new-feature
# 6. Merge after approval
# - Squash commits if needed
# - Delete feature branch
# Code review checklist
# Pre-review
- [ ] Code compiles without errors
- [ ] All tests pass
- [ ] Code follows style guidelines
- [ ] Documentation is updated
- [ ] No debug code or comments
# Review criteria
- [ ] Code functionality is correct
- [ ] Code is readable and maintainable
- [ ] Error handling is appropriate
- [ ] Performance considerations
- [ ] Security implications
- [ ] Test coverage is adequate
# Post-review
- [ ] Address all review comments
- [ ] Update documentation if needed
- [ ] Re-run tests after changes
- [ ] Get final approval
# Resolving merge conflicts
# 1. Check conflict status
git status
# 2. Open conflicted files and resolve
# Look for conflict markers:
# <<<<<<< HEAD
# Your changes
# =======
# Their changes
# >>>>>>> branch-name
# 3. Resolve conflicts manually
# Remove conflict markers
# Keep appropriate code
# 4. Stage resolved files
git add <resolved-file>
# 5. Complete merge
git commit -m "Resolve merge conflicts"
# Alternative: Use merge tool
git mergetool
git add .
git commit -m "Resolve conflicts using mergetool"
# Release branch workflow
# 1. Create release branch from develop
git checkout develop
git pull origin develop
git checkout -b release/v1.2.0
# 2. Version bump and final fixes
# Update version numbers
# Fix any last-minute issues
# Update release notes
# 3. Commit release changes
git add .
git commit -m "Prepare release v1.2.0"
# 4. Merge to main and tag
git checkout main
git merge release/v1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"
# 5. Merge back to develop
git checkout develop
git merge release/v1.2.0
# 6. Push changes and tags
git push origin main
git push origin develop
git push origin v1.2.0
# 7. Delete release branch
git branch -d release/v1.2.0
git push origin --delete release/v1.2.0
# Semantic versioning (SemVer)
# Format: MAJOR.MINOR.PATCH
# MAJOR: Incompatible API changes
# MINOR: New functionality (backward compatible)
# PATCH: Bug fixes (backward compatible)
# Version bump examples
1.0.0 -> 1.1.0 # New feature added
1.1.0 -> 1.1.1 # Bug fix
1.1.1 -> 2.0.0 # Breaking change
# Pre-release versions
1.0.0-alpha.1 # Alpha release
1.0.0-beta.1 # Beta release
1.0.0-rc.1 # Release candidate
# Build metadata
1.0.0+build.123 # Build number
1.0.0+20130313144700 # Timestamp
Version Control Workflow Models ┌─────────────────────────────────────────────────────────────┐ │ Centralized Workflow │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Main Branch Only │ │ │ │ ├── All developers work directly on main │ │ │ │ ├── Simple but limited collaboration │ │ │ │ └── Suitable for small teams │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Feature Branch Workflow │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Main + Feature Branches │ │ │ │ ├── Features developed in separate branches │ │ │ │ ├── Pull requests for code review │ │ │ │ └── Good for medium-sized teams │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ GitFlow Workflow │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Main + Develop + Feature + Release + Hotfix │ │ │ │ ├── Structured release management │ │ │ │ ├── Clear separation of concerns │ │ │ │ └── Suitable for large teams and projects │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘
### Branching Strategy
Git Branching Strategy ┌─────────────────────────────────────────────────────────────┐ │ Main Branch (Production) │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Stable, tested code │ │ │ │ Tagged releases (v1.0.0, v1.1.0, etc.) │ │ │ │ Hotfix branches for critical issues │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Develop Branch (Integration) │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Feature integration │ │ │ │ Pre-release testing │ │ │ │ Release branch creation │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Feature Branches (Development) │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Individual features │ │ │ │ Bug fixes │ │ │ │ Experimental work │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘
### Code Review Process
Code Review Workflow ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Developer │───▶│ Create │───▶│ Code │ │ Creates │ │ Pull │ │ Review │ │ Feature │ │ Request │ │ Process │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Feature │ │ Automated │ │ Reviewer │ │ Branch │ │ Checks │ │ Feedback │ └─────────────┘ └─────────────┘ └─────────────┘ │ ▼ ┌─────────────┐ │ Address │ │ Feedback │ └─────────────┘ │ ▼ ┌─────────────┐ │ Merge │ │ Approved │ └─────────────┘
### Continuous Integration Pipeline
CI/CD Pipeline ┌─────────────────────────────────────────────────────────────┐ │ Code Commit │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Push to feature branch │ │ │ │ Create pull request │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Automated Testing │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Code quality checks │ │ │ │ Unit tests │ │ │ │ Integration tests │ │ │ │ Build verification │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Code Review │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Manual review │ │ │ │ Automated checks pass │ │ │ │ Approval from reviewers │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Merge and Deploy │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Merge to develop/main │ │ │ │ Automated deployment │ │ │ │ Post-deployment tests │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ```
Version control workflows are essential for successful embedded software development. A well-designed workflow provides:
The key to successful version control implementation lies in:
By following these principles and implementing the techniques discussed in this guide, development teams can create robust, efficient, and maintainable version control workflows for their embedded projects.