Sanitized mirror from private repository - 2026-03-21 10:17:56 UTC

docs/admin/GIT_BRANCHES_GUIDE.md

@@ -0,0 +1,254 @@
+# 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?
+
+1. **Safety**: Your production services keep running while you test changes
+2. **Collaboration**: If someone helps you, they can work on their own branch
+3. **Easy Rollback**: If something breaks, just delete the branch or don't merge it
+4. **Code Review**: You can review changes before merging (especially useful for risky changes)
+5. **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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+git checkout -b docs/monitoring-guide
+# Write extensive docs
+# Merge when complete
+```
+
+### 5. Major Refactors
+Restructure code over time.
+
+```bash
+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/functionality
+- `fix/*` - Bug fixes
+- `docs/*` - Documentation only
+- `experiment/*` - Testing ideas (might not merge)
+- `upgrade/*` - Service upgrades
+- `config/*` - Configuration changes
+- `security/*` - Security updates
+
+## Standard Workflow
+
+### Starting New Work
+
+```bash
+# 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
+
+```bash
+# 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 service
+- `fix/plex-permissions` - Fixing Plex container permissions
+- `docs/ansible-playbook-guide` - Documentation work
+- `upgrade/ollama-version` - Upgrading a service
+- `experiment/kubernetes-migration` - Testing big changes
+- `security/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
+
+```bash
+# 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.
+```bash
+git merge feature-branch
+```
+
+### No Fast-Forward Merge (recommended)
+Creates merge commit showing branch integration point. Better for tracking features.
+```bash
+git merge feature-branch --no-ff
+```
+
+### Squash Merge
+Combines all branch commits into one commit on main. Cleaner but loses individual commit history.
+```bash
+git merge feature-branch --squash
+```
+
+## Conflict Resolution
+
+If merge conflicts occur:
+
+```bash
+# 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
+
+1. **Keep branches short-lived**: Merge within days/weeks, not months
+2. **Update from main regularly**: Prevent large divergence
+3. **One feature per branch**: Don't mix unrelated changes
+4. **Descriptive names**: Use naming convention for clarity
+5. **Test before merging**: Verify changes work
+6. **Delete after merging**: Keep repository clean
+7. **Create backups**: Before risky merges, create backup branch
+
+## Recovery Commands
+
+```bash
+# 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:
+- `main` branch is always deployable
+- Feature branches are merged with `--no-ff` for 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
+
+## See Also
+
+- [Git Documentation](https://git-scm.com/doc)
+- [GitHub Flow Guide](https://guides.github.com/introduction/flow/)
+- Repository: https://git.vish.gg/Vish/homelab