homelab-optimized/docs/admin/GIT_BRANCHES_GUIDE.md

# 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