jramos/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(repo): reorganize repository structure for improved navigation and maintainability

Browse Source 
Implement comprehensive directory reorganization to improve discoverability,
logical grouping, and separation of concerns across documentation, scripts,
and infrastructure snapshots.

Major Changes:

1. Documentation Reorganization:
   - Created start-here-docs/ for onboarding documentation
     * Moved QUICK-START.md, START-HERE.md, GIT-SETUP-GUIDE.md
     * Moved GIT-QUICK-REFERENCE.md, SCRIPT-USAGE.md, SETUP-COMPLETE.md
   - Created troubleshooting/ directory
     * Moved BUGFIX-SUMMARY.md for centralized issue resolution
   - Created mcp/ directory for Model Context Protocol configurations
     * Moved OBSIDIAN-MCP-SETUP.md to mcp/obsidian/

2. Scripts Reorganization:
   - Created scripts/crawlers-exporters/ for infrastructure collection
     * Moved collect*.sh scripts and collection documentation
     * Consolidates Proxmox homelab export tooling
   - Created scripts/fixers/ for operational repair scripts
     * Moved fix_n8n_db_*.sh scripts
     * Isolated scripts with embedded credentials (templates tracked)
   - Created scripts/qol/ for quality-of-life utilities
     * Moved git-aliases.sh and git-first-commit.sh

3. Infrastructure Snapshots:
   - Created disaster-recovery/ for active infrastructure state
     * Moved latest homelab-export-20251202-204939/ snapshot
     * Contains current VM/CT configurations and system state
   - Created archive-homelab/ for historical snapshots
     * Moved homelab-export-*.tar.gz archives
     * Preserves point-in-time backups for reference

4. Agent Definitions:
   - Created sub-agents/ directory
     * Added backend-builder.md (development agent)
     * Added lab-operator.md (infrastructure operations agent)
     * Added librarian.md (git/version control agent)
     * Added scribe.md (documentation agent)

5. Updated INDEX.md:
   - Reflects new directory structure throughout
   - Updated all file path references
   - Enhanced navigation with new sections
   - Added agent roles documentation
   - Updated quick reference commands

6. Security Improvements:
   - Updated .gitignore to match reorganized file locations
   - Corrected path for scripts/fixers/fix_n8n_db_c_locale.sh exclusion
   - Maintained template-based credential management pattern

Infrastructure State Update:
   - Latest snapshot: 2025-12-02 20:49:54
   - Removed: VM 101 (gitlab), CT 112 (Anytype)
   - Added: CT 113 (n8n)
   - Total: 9 VMs, 3 Containers

Impact:
   - Improved repository navigation and discoverability
   - Logical separation of documentation, scripts, and snapshots
   - Clearer onboarding path for new users
   - Enhanced maintainability through organized structure
   - Foundation for multi-agent workflow support

Files changed: 90 files (+935/-349)
   - 3 modified, 14 new files, 73 renames/moves

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Jordan Ramos
2025-12-02 21:39:33 -07:00
parent eec4c4b298
commit 4f69420aaa
90 changed files with 935 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
start-here-docs/GIT-QUICK-REFERENCE.md Normal file
View File

@@ -0,0 +1,189 @@
# 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`