K
K12worX Education501(c)(3) Public Charity
Jamboree

Cloning the Repository

Cloning means downloading a copy of the code from GitHub to your computer. Once cloned, you can view, edit, and run the code locally.

Before You Start

Make sure you have:

  • ✅ Git installed (Installing Git)
  • ✅ GitHub account (if you don't have one, create it at github.com)
  • ✅ Terminal/Command Prompt open

What is GitHub?

GitHub is like Google Drive for code. It stores the K12worX codebase and tracks all changes made by contributors.

Cloning creates a local copy on your computer that stays connected to GitHub.

Step 1: Choose a Location

First, decide where to keep the code on your computer.

Recommended: Create a projects folder

# Go to home directory
cd ~

# Go to Documents
cd Documents

# Create projects folder
mkdir projects

# Go into projects folder
cd projects

# Verify you're in the right place
pwd
# Should show: /Users/yourname/Documents/projects (Mac)
# Or: C:\Users\YourName\Documents\projects (Windows)

Step 2: Clone the Repository

Note: Replace <repository-url> with the actual GitHub URL provided by your coordinator.

git clone <repository-url>

Example (your URL will be different):

git clone https://github.com/k12worx/k12worx-jamboree.git

What happens:

  1. Git contacts GitHub
  2. Downloads all code files
  3. Creates a new folder called k12worx-jamboree
  4. Sets up git tracking

This might take 30-60 seconds depending on internet speed.

Step 3: Navigate into the Project

# Go into the project folder
cd k12worx-jamboree

# Go into the website folder
cd website

# Confirm you're in the right place
pwd
# Should show: .../k12worx-jamboree/website

Step 4: Explore the Structure

Let's see what's in the folder:

# List all files and folders
ls

# Or on Windows Command Prompt
dir

You should see:

app/
components/
public/
package.json
README.md
tsconfig.json
tailwind.config.ts
next.config.ts
... and more

Understanding What You Cloned

Project Structure

k12worx-jamboree/          ← Repository root
├── website/               ← Next.js website (where you'll work)
│   ├── app/              ← Pages and routes
│   ├── components/       ← Reusable components
│   ├── public/           ← Static assets (images, icons)
│   ├── package.json      ← Dependencies list
│   └── ...
├── docs/                 ← Project documentation
├── planning/             ← Planning documents
└── README.md             ← Project overview

Key Files

package.json

  • Lists all dependencies (React, Next.js, Tailwind, etc.)
  • Defines scripts (npm run dev, npm run build)

README.md

  • Project overview and instructions
  • Read this file to understand the project!

tsconfig.json

  • TypeScript configuration
  • You don't need to modify this

Opening in VS Code

Now let's open the project in VS Code:

Option 1: Command Line

# Make sure you're in the website folder
cd ~/Documents/projects/k12worx-jamboree/website

# Open in VS Code
code .

The . means "current directory".

Option 2: VS Code GUI

  1. Open VS Code
  2. File → Open Folder
  3. Navigate to k12worx-jamboree/website
  4. Click "Open"

Verify in VS Code

You should see:

  • Left sidebar: File explorer showing all folders
  • Terminal at bottom (if not, press Cmd/Ctrl + `)

Troubleshooting

"git: command not found"

Problem: Git not installed or not in PATH

Solution:

  1. Review Installing Git
  2. Restart terminal after installation
  3. Try git --version to verify

"Permission denied (publickey)"

Problem: GitHub can't verify your identity

Solutions:

Option 1: Use HTTPS instead of SSH

# Use the https:// URL, not git@github.com
git clone https://github.com/...

Option 2: Set up SSH keys (advanced)

"Repository not found"

Problem: Incorrect URL or no access

Solutions:

  1. Double-check the URL
  2. Make sure you have access to the repository
  3. Contact your coordinator

"Directory not empty"

Problem: Folder already exists

Solution:

# Remove old folder first
rm -rf k12worx-jamboree

# Or choose a different name
git clone <url> k12worx-jamboree-2

Clone is very slow

Problem: Large repository or slow internet

Solution:

  • Be patient! First clone can take a few minutes
  • Make sure you have stable internet connection
  • Try shallow clone (downloads less history): 
    git clone --depth 1 <repository-url>

Verifying the Clone

Let's make sure everything downloaded correctly:

# Check that website folder exists
cd ~/Documents/projects/k12worx-jamboree/website

# Check that package.json exists
ls package.json
# Should show: package.json

# Check git is working
git status
# Should show: "On branch main" or similar

If all these work, you're ready!

What's Next?

You have the code! Now let's install dependencies and run it:

Running the Dev Server →

Quick Reference

Clone repository:

git clone <repository-url>

Navigate to website:

cd k12worx-jamboree/website

Open in VS Code:

code .

Check git status:

git status

External Resources

Git Clone Documentation: https://git-scm.com/docs/git-clone

  • When to use: Understanding clone options

GitHub's Clone Guide: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository

  • When to use: Visual guide with screenshots