Git & GitHub Guide for EPIC

This guide covers setting up Git, uploading to GitHub, and handling large files using Git LFS (Large File Storage).

Initial Setup
Understanding Git Basics
Uploading to GitHub
Git Large File Storage (LFS)
Daily Workflow
Common Git Operations
Handling Large Files
Troubleshooting

Initial Setup

Step 1: Install Git

Windows:

# Download from https://git-scm.com/download/win
# Run the installer and follow prompts
# Choose "Use Git Bash" when asked about the default editor

# Verify installation
git --version

macOS:

# Using Homebrew (recommended)
brew install git

# Verify installation
git --version

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install git

# Verify installation
git --version

Step 2: Configure Git Globally

# Set your name (appears in all commits)
git config --global user.name "Your Name"

# Set your email (should match GitHub email)
git config --global user.email "your.email@example.com"

# View your configuration
git config --global --list

Step 3: Generate SSH Key (Recommended for GitHub)

SSH keys allow you to push to GitHub without entering your password every time.

# Generate a new SSH key
ssh-keygen -t ed25519 -C "your.email@example.com"

# When prompted, press Enter to accept default location (~/.ssh/id_ed25519)
# When prompted for passphrase, you can:
#   - Press Enter for no passphrase (less secure)
#   - Enter a passphrase (more secure, you'll type it when needed)

# Start SSH agent
eval $(ssh-agent -s)

# Add your SSH key to the agent
ssh-add ~/.ssh/id_ed25519

# Copy the public key to clipboard
# Windows (Git Bash):
cat ~/.ssh/id_ed25519.pub | clip

# macOS:
cat ~/.ssh/id_ed25519.pub | pbcopy

# Linux:
cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard

Step 4: Add SSH Key to GitHub

Go to GitHub.com and sign in
Click your profile icon � Settings
Click SSH and GPG keys in left sidebar
Click New SSH key
Paste your public key (copied above)
Give it a name like "My Laptop"
Click Add SSH key

Step 5: Verify SSH Connection

ssh -T git@github.com

# Expected output:
# Hi yourusername! You've successfully authenticated, but GitHub does not provide shell access.

Understanding Git Basics

Git Concepts

Working Directory (Local Files)
         � (git add)
Staging Area (Index)
         � (git commit)
Repository (Local .git folder)
         � (git push)
GitHub Remote (github.com)
         � (git pull)

Key Terminology

Term	Meaning
Repository (Repo)	Your project folder with .git tracking
Commit	A snapshot of your code at a point in time
Branch	A separate line of development
Remote	A copy of the repo on GitHub
Origin	Default name for remote repository
Master/Main	Default primary branch
Staging Area	Files ready to be committed
Diff	Changes between versions

Git Status Explained

Untracked Files  � git add  � Staged Changes  � git commit  � Committed
                            (in staging area)              (in repository)

Uploading to GitHub

Method 1: Create New Repository on GitHub First

On GitHub:

Go to github.com and sign in
Click + (top right) � New repository
Repository name: epic (or your project name)
Description: "EPIC: Novel writing and world-building application"
Choose Private or Public
DO NOT initialize with README/gitignore/license (we'll do that locally)
Click Create repository

On Your Computer:

# Navigate to your project root
cd c:\Users\arman\Desktop\Yo\Computer_Science\epic

# Initialize local git repository
git init

# Add all files to staging area
git add .

# Create initial commit
git commit -m "Initial commit: EPIC application setup"

# Add GitHub as remote repository
git remote add origin git@github.com:YOUR_USERNAME/epic.git

# Rename branch to main (if needed)
git branch -M main

# Push local commits to GitHub
git push -u origin main

Method 2: Clone Existing Repository

If the repository already exists on GitHub:

# Clone the repository to your computer
git clone git@github.com:YOUR_USERNAME/epic.git

# This creates a folder called "epic" with the repository inside
cd epic

Verify Remote Setup

# List configured remotes
git remote -v

# Expected output:
# origin  git@github.com:YOUR_USERNAME/epic.git (fetch)
# origin  git@github.com:YOUR_USERNAME/epic.git (push)

Git Large File Storage (LFS)

Git LFS solves the problem of tracking large files (videos, images, models, databases) without bloating the repository.

Why Git LFS?

Without LFS:

Cloning takes hours
Repository becomes gigabytes
Every small change commits the entire large file again
GitHub has a 100MB file size limit per file

With LFS:

Only pointers (tiny text files) stored in Git
Large files stored separately on GitHub's servers
Fast clones and pushes
Bandwidth efficient

Step 1: Install Git LFS

Windows (Git Bash):

# Download from https://git-lfs.com or use Homebrew
brew install git-lfs

# Or download the .exe from https://git-lfs.com
# Then run: git-lfs-windows-<version>.exe

# Initialize Git LFS
git lfs install

macOS:

brew install git-lfs

# Initialize Git LFS
git lfs install

Linux (Ubuntu/Debian):

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs

# Initialize Git LFS
git lfs install

Step 2: Check Git LFS Installation

git lfs version

# Expected output:
# git-lfs/3.4.0 (GitHub; windows amd64; go 1.20.1)

Step 3: Configure LFS for Your Repository

# Navigate to your project
cd c:\Users\arman\Desktop\Yo\Computer_Science\epic

# Track specific file types with LFS
git lfs track "*.mp4"
git lfs track "*.mkv"
git lfs track "*.mov"
git lfs track "*.avi"
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.7z"
git lfs track "*.rar"
git lfs track "*.iso"
git lfs track "*.db"
git lfs track "*.sqlite"
git lfs track "*.png"
git lfs track "*.jpg"
git lfs track "*.jpeg"
git lfs track "*.gif"
git lfs track "*.exe"
git lfs track "*.dll"

# View what's being tracked
cat .gitattributes

# Expected output:
# *.mp4 filter=lfs diff=lfs merge=lfs -text
# *.mkv filter=lfs diff=lfs merge=lfs -text
# ... etc

Step 4: Add .gitattributes to Git

# Add the .gitattributes file to staging
git add .gitattributes

# Commit it
git commit -m "Configure Git LFS for large files"

Step 5: Move Existing Large Files to LFS

If you already committed large files:

# To migrate files already in the repository (advanced):
# 1. Install git-lfs-migrate
brew install git-lfs

# 2. Migrate files
git lfs migrate import --include="*.mp4,*.psd,*.zip,*.db"

# 3. Force push (be careful with shared repos!)
git push --force-with-lease origin main

List All LFS-Tracked Files

git lfs ls-files

# Shows all files managed by Git LFS

Daily Workflow

Standard Commit Workflow

# 1. Check what changed
git status

# Output shows:
# - Untracked files (new files)
# - Modified files (changed files)
# - Deleted files

# 2. View specific changes (optional)
git diff filename.ts

# 3. Stage all changes
git add .

# Or stage specific files:
git add backend/routes/wikiRoutes.ts
git add frontend/components/SolarSystem.tsx

# 4. Review what will be committed
git status

# 5. Commit with descriptive message
git commit -m "Add wiki category filtering and search functionality

- Implement search filter in SearchFilterEntity component
- Add category filtering in useWikiCategory hook
- Update API routes to support filter parameters
- Add tests for search and filter functionality"

# 6. Push to GitHub
git push origin main

# Or if you get behind:
git pull origin main    # Get latest changes
git push origin main    # Push your changes

Commit Message Best Practices

Good commit message structure:

Short summary (50 chars max)

Detailed explanation of:
- What changed
- Why it changed
- How it works

Related issues: #123, #456

Examples:

#  Good
git commit -m "Fix solar system filtering not working on first load

The useWikiCategory hook wasn't fetching items on initial mount when
wikiNovelId was provided as a prop. Added useEffect to call loadItems
when wikiNovelId changes.

Fixes #42"

# L Bad
git commit -m "Fixed stuff"
git commit -m "updates"
git commit -m "asdfghjkl"

Common Git Operations

Branching

# Create and switch to new branch
git checkout -b feature/wiki-search

# Or using newer syntax
git switch -c feature/wiki-search

# List all branches
git branch -a

# Switch to existing branch
git checkout main
git switch main

# Delete local branch
git branch -d feature/wiki-search

# Delete remote branch
git push origin --delete feature/wiki-search

# Rename branch
git branch -m old-name new-name

Merging

# Switch to main branch
git switch main

# Update main with latest remote changes
git pull origin main

# Merge feature branch into main
git merge feature/wiki-search

# Push merged changes to GitHub
git push origin main

Undoing Changes

# Discard changes in working directory (CAREFUL!)
git checkout -- filename.ts

# Unstage files (doesn't delete them)
git reset filename.ts

# View last 5 commits
git log --oneline -5

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes) (VERY CAREFUL!)
git reset --hard HEAD~1

# Revert a specific commit (creates new commit undoing changes)
git revert commit-hash

# Stash changes temporarily
git stash

# Restore stashed changes
git stash pop

Checking History

# View commit history
git log

# View concise history
git log --oneline

# View history with graph
git log --graph --oneline --all

# View history for specific file
git log --oneline -- backend/routes/wikiRoutes.ts

# View changes in last commit
git show HEAD

# View changes between branches
git diff main feature/wiki-search

# View who changed each line
git blame backend/routes/wikiRoutes.ts

Handling Large Files

Best Practices

Don't commit:
- node_modules/ (use .gitignore)
- .env files with secrets
- Build outputs (dist/, build/)
- Database files in version control
Use Git LFS for:
- Video files (*.mp4, *.mov, *.mkv)
- Image files (*.psd, *.ai, large *.png)
- Archives (*.zip, *.7z, *.rar)
- Databases (*.db, *.sqlite)
- Executables (*.exe, *.dll)
- Large data files (> 10MB)
Use .gitignore for:
- Temporary files
- IDE settings
- OS files
- Dependencies
- Logs

Create .gitignore

Create c:\Users\arman\Desktop\Yo\Computer_Science\epic\.gitignore:

# Dependencies
node_modules/
.pnp
.pnp.js

# Build outputs
dist/
build/
.next/
out/

# Environment variables
.env
.env.local
.env.*.local

# IDE and editor files
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store

# OS files
Thumbs.db
.DS_Store

# Logs
logs/
*.log
npm-debug.log*
yarn-debug.log*

# Temporary files
*.tmp
*.temp
tmp/

# Testing
coverage/
.nyc_output/

# Database files (unless using LFS)
*.sqlite
*.db

# Large media (use Git LFS instead)
# These should be tracked by LFS, not .gitignore
# But list them here for reference:
# *.mp4
# *.psd
# *.zip

Check File Sizes

# Find largest files in repository
du -sh * | sort -h

# Or more detailed:
find . -type f -exec du -h {} + | sort -rh | head -20

# Check if file will exceed GitHub limits
ls -lh filename.zip

Handle Large Files Accidentally Committed

# If you accidentally committed a large file:

# 1. Remove from Git history (nuclear option)
git rm --cached large-file.zip
git commit -m "Remove large file from tracking"

# 2. Or, convert to LFS after the fact
git lfs migrate import --include="*.zip"
git push --force-with-lease origin main

# 3. Delete the file locally if not needed
rm large-file.zip

Troubleshooting

Issue: "fatal: remote origin already exists"

# Solution: Remove existing remote and add new one
git remote remove origin
git remote add origin git@github.com:YOUR_USERNAME/epic.git

Issue: "permission denied (publickey)"

# SSH key not working. Try HTTPS instead:
git remote set-url origin https://github.com/YOUR_USERNAME/epic.git

# Or add SSH key to agent:
ssh-add ~/.ssh/id_ed25519

# Or generate new key:
ssh-keygen -t ed25519 -C "your.email@example.com"

Issue: Large file rejected by GitHub

# File is > 100MB. Use Git LFS:

# 1. Remove the file from Git
git rm --cached large-file.zip

# 2. Track with LFS
git lfs track "*.zip"

# 3. Re-add the file
git add large-file.zip
git add .gitattributes

# 4. Commit and push
git commit -m "Track large file with Git LFS"
git push origin main

Issue: Can't push due to conflicts

# Pull latest changes first
git pull origin main

# Resolve any conflicts in your editor
# Then stage, commit, and push
git add .
git commit -m "Resolve merge conflicts"
git push origin main

Issue: Git LFS quota exceeded

GitHub has quota limits for Git LFS. Check your usage:

Go to GitHub.com � Settings � Billing and Plans
Click Git LFS Data in the left sidebar
View your usage and purchase more if needed

Alternatives:

Remove old LFS files: git lfs prune
Use separate storage service for very large files
Archive old data separately

Issue: Can't clone repository

# If you get permission errors:
# 1. Check SSH setup
ssh -T git@github.com

# 2. Try HTTPS instead
git clone https://github.com/YOUR_USERNAME/epic.git

# 3. When prompted, use Personal Access Token instead of password
# Create at: GitHub.com � Settings � Developer settings � Personal access tokens

Common Workflows

Feature Development

# 1. Create feature branch
git switch -c feature/solar-system-search

# 2. Make changes and commit regularly
git add .
git commit -m "Add search functionality to solar systems"

# 3. Push to GitHub
git push origin feature/solar-system-search

# 4. Create Pull Request on GitHub
# (Will see button to create PR after push)

# 5. After PR is merged, delete branch
git switch main
git pull origin main
git branch -d feature/solar-system-search

Emergency: Revert Bad Commit

# Option 1: Undo last commit, keep changes
git reset --soft HEAD~1

# Option 2: Create a new commit that undoes changes
git revert HEAD

# Option 3: Hard reset (loses all changes!)
git reset --hard HEAD~1

Sync Fork with Upstream

# If you forked someone's repo:

# Add upstream remote
git remote add upstream git@github.com:ORIGINAL_OWNER/epic.git

# Fetch latest changes
git fetch upstream

# Merge upstream main into your main
git checkout main
git merge upstream/main

# Push to your fork
git push origin main

GitHub Features

Issues

Create and track bugs, features, and tasks:

# Reference issue in commit
git commit -m "Fix solar system search bug

Fixes #123"

# When you push, GitHub auto-closes issue #123

Pull Requests (PR)

Propose changes for review:

# After pushing to feature branch:
# 1. Go to github.com/YOUR_USERNAME/epic
# 2. Click "Compare & pull request"
# 3. Add description and submit
# 4. Team members review and approve
# 5. Merge to main

Project Boards

Organize tasks visually (Kanban board):

Go to GitHub repo � Projects
Create new project
Add issues and PRs to project
Move cards through workflow

Actions (CI/CD)

Automate tests and deployments:

Go to Actions
Choose template (e.g., Node.js)
Edit workflow file
Commit and push
Workflow runs automatically

Best Practices Summary

Practice	Reason
Commit frequently	Easier to track changes and revert if needed
Descriptive messages	Makes history readable for future developers
Use branches	Keep main branch clean and stable
Push regularly	Backup your work to GitHub
Pull before push	Avoid merge conflicts
Use .gitignore	Prevents accidentally committing sensitive files
Use Git LFS	Keeps repository lean with large files
Code reviews	Catch bugs before merging to main
Automated testing	Ensure code quality before merge

Quick Reference Card

# Setup
git config --global user.name "Your Name"
git config --global user.email "email@example.com"
ssh-keygen -t ed25519 -C "email@example.com"

# Clone or Initialize
git clone git@github.com:user/repo.git
git init
git remote add origin git@github.com:user/repo.git

# Daily Work
git status
git add .
git commit -m "message"
git push origin main
git pull origin main

# Branches
git branch -a
git switch -c feature/name
git merge feature/name
git branch -d feature/name

# Undo
git reset --soft HEAD~1  # Undo commit, keep changes
git revert HEAD          # Create new commit undoing changes
git checkout -- file     # Discard changes to file

# LFS
git lfs track "*.mp4"
git lfs ls-files
git lfs migrate import --include="*.zip"

# History
git log --oneline
git show commit-hash
git diff main feature/name

Additional Resources

Official Git Documentation: https://git-scm.com/doc
GitHub Guides: https://guides.github.com
Git Cheat Sheet: https://github.github.com/training-kit/
Branching Model: https://nvie.com/posts/a-successful-git-branching-model/
Git LFS Documentation: https://git-lfs.com

Summary

You now have everything you need to:

Set up Git and GitHub
Upload your project to GitHub
Handle large files with Git LFS
Use Git effectively for version control
Collaborate with others
Manage your project on GitHub

Happy coding! =�

Git & GitHub Guide for EPIC

Git & GitHub Guide for EPIC

Table of Contents

Initial Setup

Step 1: Install Git

Step 2: Configure Git Globally

Step 3: Generate SSH Key (Recommended for GitHub)

Step 4: Add SSH Key to GitHub

Step 5: Verify SSH Connection

Understanding Git Basics

Git Concepts

Key Terminology

Git Status Explained

Uploading to GitHub

Method 1: Create New Repository on GitHub First

Method 2: Clone Existing Repository

Verify Remote Setup

Git Large File Storage (LFS)

Why Git LFS?

Step 1: Install Git LFS

Step 2: Check Git LFS Installation

Step 3: Configure LFS for Your Repository

Step 4: Add .gitattributes to Git

Step 5: Move Existing Large Files to LFS

List All LFS-Tracked Files

Daily Workflow

Standard Commit Workflow

Commit Message Best Practices

Common Git Operations

Branching

Merging

Undoing Changes

Checking History

Handling Large Files

Best Practices

Create .gitignore

Check File Sizes

Handle Large Files Accidentally Committed

Troubleshooting

Issue: "fatal: remote origin already exists"

Issue: "permission denied (publickey)"

Issue: Large file rejected by GitHub

Issue: Can't push due to conflicts

Issue: Git LFS quota exceeded

Issue: Can't clone repository

Common Workflows

Feature Development

Emergency: Revert Bad Commit

Sync Fork with Upstream

GitHub Features

Issues

Pull Requests (PR)

Project Boards

Actions (CI/CD)

Best Practices Summary

Quick Reference Card

Additional Resources

Summary