# Git Dual Remote Setup - GitHub & HuggingFace

## Current Setup
- **GitHub**: `origin` - https://github.com/DealExMachina/llm-pro-fin-api.git
- **HuggingFace Space**: Not yet configured as a remote

## Why Use Two Remotes?

### GitHub (Code Repository)
- Version control for all code, tests, documentation
- Collaboration with team members
- Issue tracking, pull requests
- CI/CD workflows
- Private repository with full project history

### HuggingFace Space (Deployment)
- Live deployment of the API
- Public-facing service
- Only needs deployment files (app.py, Dockerfile, requirements.txt)
- Automatic rebuilds on push

## Setup: Adding HuggingFace as a Remote

### Step 1: Add HuggingFace Remote

```bash
cd /Users/jeanbapt/LLM-Pro-Fin-Inference

# Add HuggingFace Space as a remote called 'hf'
git remote add hf https://huggingface.co/spaces/jeanbaptdzd/linguacustodia-financial-api.git
```

### Step 2: Configure Authentication for HuggingFace

HuggingFace uses your HF token for git authentication:

```bash
# Option 1: Configure git to use your HF token
git config credential.helper store

# When you push, use your HF username and token as password
# Username: jeanbaptdzd
# Password: your HF_TOKEN
```

**OR** use the git credential helper:

```bash
# Set up HF CLI authentication (recommended)
huggingface-cli login
# Enter your HF_TOKEN when prompted
```

### Step 3: Verify Remotes

```bash
git remote -v
```

Expected output:
```
origin  https://github.com/DealExMachina/llm-pro-fin-api.git (fetch)
origin  https://github.com/DealExMachina/llm-pro-fin-api.git (push)
hf      https://huggingface.co/spaces/jeanbaptdzd/linguacustodia-financial-api.git (fetch)
hf      https://huggingface.co/spaces/jeanbaptdzd/linguacustodia-financial-api.git (push)
```

## Workflow: Working with Both Remotes

### Development Workflow

```bash
# 1. Make changes on a feature branch
git checkout -b feature/new-feature

# 2. Make your changes
vim app.py

# 3. Commit changes
git add app.py
git commit -m "feat: add new feature"

# 4. Push to GitHub (for version control and collaboration)
git push origin feature/new-feature

# 5. Merge to main
git checkout main
git merge feature/new-feature
git push origin main

# 6. Deploy to HuggingFace Space
git push hf main
# This will trigger a rebuild and deployment on HuggingFace
```

### Quick Deployment Workflow

If you only want to deploy without creating a branch:

```bash
# Make changes
vim app.py

# Commit
git add app.py
git commit -m "fix: update model parameters"

# Push to both remotes
git push origin main  # Backup to GitHub
git push hf main      # Deploy to HuggingFace
```

### Push to Both Remotes at Once

You can configure git to push to both remotes with a single command:

```bash
# Add both URLs to origin
git remote set-url --add --push origin https://github.com/DealExMachina/llm-pro-fin-api.git
git remote set-url --add --push origin https://huggingface.co/spaces/jeanbaptdzd/linguacustodia-financial-api.git

# Now 'git push origin main' will push to both!
git push origin main
```

**OR** create a custom alias:

```bash
# Add to ~/.gitconfig or .git/config
[alias]
    pushall = "!git push origin main && git push hf main"

# Usage:
git pushall
```

## Important Differences

### GitHub vs HuggingFace Space Structure

**GitHub** (Full Project):
```
LLM-Pro-Fin-Inference/
├── app.py
├── requirements.txt
├── Dockerfile
├── test_*.py              # Test files
├── docs/                  # Documentation
├── .env.example
├── PROJECT_RULES.md
├── venv/                  # Not committed
└── .git/
```

**HuggingFace Space** (Deployment Only):
```
linguacustodia-financial-api/
├── app.py                 # Main application
├── requirements.txt       # Dependencies
├── Dockerfile            # Container config
├── README.md             # Space description
├── .gitattributes        # LFS config
└── .git/
```

### What to Push Where

**GitHub** (Push Everything):
- ✅ All source code
- ✅ Tests
- ✅ Documentation
- ✅ Configuration examples
- ✅ Development scripts
- ❌ `.env` (never commit secrets!)
- ❌ `venv/` (listed in .gitignore)

**HuggingFace** (Push Deployment Files Only):
- ✅ `app.py`
- ✅ `requirements.txt`
- ✅ `Dockerfile`
- ✅ `README.md` (for Space description)
- ❌ Test files
- ❌ Documentation (unless needed for Space)
- ❌ Development scripts

## Branch Strategy

### Recommended: Keep HF Synced with GitHub Main

```bash
# GitHub - main branch (stable)
# HuggingFace - main branch (deployed)

# Work on feature branches in GitHub
git checkout -b feature/new-endpoint
# ... make changes ...
git push origin feature/new-endpoint

# After review/testing, merge to main
git checkout main
git merge feature/new-endpoint
git push origin main

# Deploy to HuggingFace
git push hf main
```

### Alternative: Use Separate Deployment Branch

If you want more control over what gets deployed:

```bash
# Create a deployment branch
git checkout -b deploy
git push hf deploy:main

# Now HuggingFace deploys from your 'deploy' branch
# while GitHub main can be ahead with unreleased features
```

## Selective File Sync

If you want different files in each remote, use `.gitignore` or create a deployment script:

### Option 1: Sparse Checkout (Advanced)

```bash
# Clone HF Space with sparse checkout
git clone --no-checkout https://huggingface.co/spaces/jeanbaptdzd/linguacustodia-financial-api.git hf-space
cd hf-space
git sparse-checkout init --cone
git sparse-checkout set app.py requirements.txt Dockerfile README.md
git checkout main
```

### Option 2: Deployment Script (Recommended)

```bash
#!/bin/bash
# deploy-to-hf.sh

# Create a temporary branch with only deployment files
git checkout -b temp-deploy main

# Remove non-deployment files
git rm -r tests/ docs/ *.md --ignore-unmatch
# ... remove other files ...

# Commit
git commit -m "Deployment build"

# Force push to HF
git push -f hf temp-deploy:main

# Clean up
git checkout main
git branch -D temp-deploy
```

## Troubleshooting

### Issue 1: Push Conflicts

If HuggingFace has changes you don't have locally:

```bash
# Fetch from HF
git fetch hf

# Check what's different
git diff main hf/main

# If you want to keep HF changes
git pull hf main

# If you want to overwrite HF with your changes
git push -f hf main  # Use force push carefully!
```

### Issue 2: Authentication Errors

```bash
# Test authentication
git ls-remote hf

# If it fails, reconfigure credentials
huggingface-cli login
# or
git config credential.helper store
```

### Issue 3: Large Files

HuggingFace Spaces uses Git LFS for large files:

```bash
# Install git-lfs
git lfs install

# Track large files (if any)
git lfs track "*.bin"
git lfs track "*.safetensors"

# Commit .gitattributes
git add .gitattributes
git commit -m "Configure Git LFS"
```

## Best Practices

### ✅ DO

1. **Push to GitHub First** - Always backup to GitHub before deploying to HF
2. **Use Meaningful Commits** - Both repos benefit from good commit messages
3. **Test Before Deploying** - Test locally before pushing to HF
4. **Use Branches** - Work on features in branches, merge to main
5. **Keep Secrets in Space Variables** - Never commit tokens to either repo
6. **Document Deployments** - Tag releases: `git tag v20.0.0`

### ❌ DON'T

1. **Don't Commit Secrets** - Never push `.env` or tokens to either repo
2. **Don't Force Push to Main** - Unless you're absolutely sure
3. **Don't Mix Development and Deployment** - Keep HF clean with only deployment files
4. **Don't Forget to Pull** - Always pull before pushing to avoid conflicts
5. **Don't Push Large Files** - Use Git LFS or exclude them

## Quick Reference Commands

```bash
# Setup
git remote add hf https://huggingface.co/spaces/jeanbaptdzd/linguacustodia-financial-api.git
huggingface-cli login

# Daily workflow
git add .
git commit -m "your message"
git push origin main          # Backup to GitHub
git push hf main              # Deploy to HuggingFace

# Check status
git remote -v                 # List remotes
git fetch hf                  # Fetch HF changes
git log hf/main              # View HF commit history

# Emergency rollback
git push -f hf HEAD~1:main   # Revert HF to previous commit
```

## Using HuggingFace API Instead of Git

For individual file updates (like we've been doing), the HF API is often easier:

```python
from huggingface_hub import HfApi

api = HfApi(token=hf_token)

# Upload single file
api.upload_file(
    path_or_fileobj='app.py',
    path_in_repo='app.py',
    repo_id='jeanbaptdzd/linguacustodia-financial-api',
    repo_type='space'
)

# Upload folder
api.upload_folder(
    folder_path='./deploy',
    repo_id='jeanbaptdzd/linguacustodia-financial-api',
    repo_type='space'
)
```

This is what we've been using - it's simpler for quick deployments!

## Recommended Setup

For your use case, I recommend:

1. **GitHub** (`origin`) - Main development repository
   - All code, tests, docs
   - Feature branches
   - Pull requests and reviews

2. **HuggingFace API** (not git remote) - For deployments
   - Use `huggingface_hub` API to upload `app.py`
   - Faster and simpler than git
   - No merge conflicts
   - Perfect for quick iterations

3. **Optional: HF Git Remote** - For full deployments
   - Add as `hf` remote
   - Use when doing major version releases
   - Push entire deployment package

## Example: Combined Workflow

```bash
# 1. Develop on GitHub
git checkout -b feature/storage-cleanup
vim app.py
git add app.py
git commit -m "feat: add storage cleanup endpoint"
git push origin feature/storage-cleanup

# 2. Merge to main after review
git checkout main
git merge feature/storage-cleanup
git push origin main

# 3. Deploy to HuggingFace (choose one):

# Option A: Using HF API (Recommended)
python -c "
from huggingface_hub import HfApi
from dotenv import load_dotenv
import os

load_dotenv()
api = HfApi(token=os.getenv('HF_TOKEN'))
api.upload_file('app.py', 'app.py', 'jeanbaptdzd/linguacustodia-financial-api', repo_type='space')
"

# Option B: Using git remote
git push hf main

# 4. Tag the release
git tag v20.0.0
git push origin v20.0.0
```

This gives you the best of both worlds!