6.4 KiB
6.4 KiB
Git Branches Guide for Homelab Repository
Last updated: 2026-02-17
What Are Git Branches?
Branches are like parallel timelines for your code. They let you make changes without affecting the main codebase. Your main branch is the "production" version - stable and working. Other branches let you experiment safely.
Why Use Branches?
- Safety: Your production services keep running while you test changes
- Collaboration: If someone helps you, they can work on their own branch
- Easy Rollback: If something breaks, just delete the branch or don't merge it
- Code Review: You can review changes before merging (especially useful for risky changes)
- Parallel Work: Work on multiple things at once without conflicts
Common Use Cases for This Homelab
1. Feature Development
Adding new services or functionality without disrupting main branch.
git checkout -b feature/add-jellyfin
# Make changes, test, commit
git push origin feature/add-jellyfin
# When ready, merge to main
Example: Adding a new service like Jellyfin - you can configure it, test it, document it all in isolation.
2. Bug Fixes
Isolating fixes for specific issues.
git checkout -b fix/perplexica-timeout
# Fix the issue, test
# Merge when confirmed working
Example: Like the fix/admin-acl-routing branch - fixing specific issues without touching main.
3. Experiments/Testing
Try new approaches without risk.
git checkout -b experiment/traefik-instead-of-nginx
# Try completely different approach
# If it doesn't work, just delete the branch
Example: Testing if Traefik works better than Nginx Proxy Manager without risking your working setup.
4. Documentation Updates
Large documentation efforts.
git checkout -b docs/monitoring-guide
# Write extensive docs
# Merge when complete
5. Major Refactors
Restructure code over time.
git checkout -b refactor/reorganize-compose-files
# Restructure files over several days
# Main stays working while you experiment
Branch Naming Convention
Recommended naming scheme:
feature/*- New services/functionalityfix/*- Bug fixesdocs/*- Documentation onlyexperiment/*- Testing ideas (might not merge)upgrade/*- Service upgradesconfig/*- Configuration changessecurity/*- Security updates
Standard Workflow
Starting New Work
# Always start from updated main
git checkout main
git pull origin main
# Create your branch
git checkout -b feature/new-service-name
# Work, commit, push
git add .
git commit -m "Add new service config"
git push origin feature/new-service-name
When Ready to Merge
# Update main first
git checkout main
git pull origin main
# Merge your branch (--no-ff creates merge commit for history)
git merge feature/new-service-name --no-ff -m "Merge feature/new-service-name"
# Push and cleanup
git push origin main
git push origin --delete feature/new-service-name
# Delete local branch
git branch -d feature/new-service-name
Real Examples for This Homelab
Good branch names:
feature/add-immich- Adding new photo servicefix/plex-permissions- Fixing Plex container permissionsdocs/ansible-playbook-guide- Documentation workupgrade/ollama-version- Upgrading a serviceexperiment/kubernetes-migration- Testing big changessecurity/update-vaultwarden- Security updates
When to Use Branches
✅ Use a branch when:
- Adding a new service
- Making breaking changes
- Experimenting with new tools
- Major configuration changes
- Working on something over multiple days
- Multiple files will be affected
- Changes need testing before production
❌ Direct to main is fine for:
- Quick documentation fixes
- Typo corrections
- Emergency hotfixes (but still be careful!)
- Single-line configuration tweaks
Quick Command Reference
# List all branches (local and remote)
git branch -a
# Create and switch to new branch
git checkout -b branch-name
# Switch to existing branch
git checkout branch-name
# See current branch
git branch
# Push branch to remote
git push origin branch-name
# Delete local branch
git branch -d branch-name
# Delete remote branch
git push origin --delete branch-name
# Update local list of remote branches
git fetch --prune
# See branch history
git log --oneline --graph --all --decorate
# Create backup branch before risky operations
git checkout -b backup-main-$(date +%Y-%m-%d)
Merge Strategies
Fast-Forward Merge (default)
Branch commits are simply added to main. Clean linear history.
git merge feature-branch
No Fast-Forward Merge (recommended)
Creates merge commit showing branch integration point. Better for tracking features.
git merge feature-branch --no-ff
Squash Merge
Combines all branch commits into one commit on main. Cleaner but loses individual commit history.
git merge feature-branch --squash
Conflict Resolution
If merge conflicts occur:
# Git will tell you which files have conflicts
# Edit the files to resolve conflicts (look for <<<<<<< markers)
# After resolving, stage the files
git add resolved-file.yml
# Complete the merge
git commit
Best Practices
- Keep branches short-lived: Merge within days/weeks, not months
- Update from main regularly: Prevent large divergence
- One feature per branch: Don't mix unrelated changes
- Descriptive names: Use naming convention for clarity
- Test before merging: Verify changes work
- Delete after merging: Keep repository clean
- Create backups: Before risky merges, create backup branch
Recovery Commands
# Undo last commit (keep changes)
git reset --soft HEAD~1
# Abandon all local changes
git reset --hard HEAD
# Restore from backup branch
git checkout main
git reset --hard backup-main-2026-02-17
# See what changed in merge
git diff main feature-branch
Integration with This Repository
This repository follows these practices:
mainbranch is always deployable- Feature branches are merged with
--no-fffor clear history - Backup branches created before major merges (e.g.,
backup-main-2026-02-17) - Remote branches deleted after successful merge
- Documentation changes may go direct to main if minor