homelab/start-here-docs/GIT-QUICK-REFERENCE.md

# Git Quick Reference Card

## Essential Locations

| What | Path |
|------|------|
| **WSL2 Terminal** | `cd /home/jramos/homelab` |
| **Windows Explorer** | `\\wsl$\Ubuntu\home\jramos\homelab` |
| **Git Repository** | `/home/jramos/homelab/.git/` |

## Daily Commands

### Check What's Changed
```bash
cd /home/jramos/homelab
git status              # Show changed files
git diff                # Show exact changes
```

### Commit Your Changes
```bash
git add .                           # Stage all changes
git commit -m "Description here"    # Commit with message
```

### View History
```bash
git log                 # Detailed history
git log --oneline       # Compact history
git log -5              # Last 5 commits
```

## Emergency Commands

### Undo Changes (Not Yet Committed)
```bash
git checkout -- filename.sh    # Undo changes to one file
git checkout -- .              # Undo all changes (CAREFUL!)
```

### Undo Last Commit (Keep Changes)
```bash
git reset --soft HEAD~1        # Undo commit, keep changes staged
git reset HEAD~1               # Undo commit, keep changes unstaged
```

### See What a Commit Changed
```bash
git show <commit-hash>         # Show changes in specific commit
git show HEAD                  # Show changes in last commit
```

## First-Time Setup

### Configure Git Identity
```bash
git config --global user.name "Your Name"
git config --global user.email "your@email.com"
```

### Make First Commit
```bash
cd /home/jramos/homelab
./git-first-commit.sh          # Use helper script
```

## File Status Guide

| Status | Meaning | What To Do |
|--------|---------|------------|
| **Untracked** | New file, not in git | `git add filename` |
| **Modified** | Changed since last commit | `git add filename` |
| **Staged** | Ready to commit | `git commit -m "message"` |
| **Committed** | Saved in history | Nothing (it's saved!) |

## Common Workflows

### After Editing Files
```bash
1. git status              # See what changed
2. git diff                # Review changes
3. git add .               # Stage everything
4. git commit -m "msg"     # Save changes
5. git log --oneline -3    # Verify commit
```

### Before Major Changes
```bash
1. git status              # Check for uncommitted changes
2. git add .               # Stage current work
3. git commit -m "Checkpoint before changes"
4. # Now make risky changes
5. # If it breaks: git checkout -- .
```

### Review File History
```bash
git log --oneline filename.sh          # See commits for file
git log --follow filename.sh           # Include renames
git show <hash>:filename.sh            # Show old version
```

## Common Mistakes & Fixes

### "I Committed the Wrong Thing"
```bash
git reset --soft HEAD~1    # Undo commit, keep changes
# Fix what you need to fix
git add .
git commit -m "Correct message"
```

### "I Deleted a File by Accident"
```bash
git checkout -- filename.sh        # Restore from last commit
```

### "I Want to See Old Version of File"
```bash
git log --oneline filename.sh      # Find commit hash
git show <hash>:filename.sh        # View old version
git checkout <hash> -- filename.sh # Restore old version
```

### "Git is Asking for Username/Password"
You're trying to push/pull from a remote that doesn't exist yet.
If you just want local version control, ignore this.

## What NOT to Commit

Already configured in `.gitignore`:
- `.env` (contains secrets)
- `*.iso`, `*.qcow2` (too large)
- `*.tar.gz` (compressed archives)
- `*.log` (log files)
- `secrets/` (sensitive data)
- `homelab-export-*/` (exports)

## Helpful Aliases (Optional)

Add to `~/.bashrc` or `~/.zshrc`:
```bash
alias gs='git status'
alias ga='git add'
alias gc='git commit -m'
alias gl='git log --oneline'
alias gd='git diff'
alias ghome='cd /home/jramos/homelab'
```

Then reload: `source ~/.bashrc`

## Quick Troubleshooting

| Problem | Solution |
|---------|----------|
| "not a git repository" | `cd /home/jramos/homelab` |
| "chmod failed" | You're in `/mnt/c/...` instead of `/home/...` |
| "nothing to commit" | No changes made since last commit |
| "Please tell me who you are" | Set `user.name` and `user.email` |

## Help Commands

```bash
git help                # General help
git help commit         # Help for specific command
git status              # Usually suggests what to do next
```

## Remember

1. **Commit early, commit often**
2. **Write meaningful commit messages**
3. **Review with `git status` and `git diff` before committing**
4. **Never commit `.env` or secrets**
5. **Git is forgiving—you can almost always undo mistakes**

## Quick Workflow Reminder

```
Edit files → git status → git diff → git add . → git commit -m "message"
```

That's 95% of what you'll use daily.

---

**For detailed explanations**: See `GIT-SETUP-GUIDE.md`
**For your first commit**: Run `./git-first-commit.sh`