# GitHub for Complete Beginners

A practical guide to understanding and using GitHub repositories — written for someone who has never used version control before.

---

## Table of Contents

1. [The Big Picture](#the-big-picture)
2. [Key Terms (Plain English)](#key-terms-plain-english)
3. [Setting Up](#setting-up)
4. [Your First Repository](#your-first-repository)
5. [The Daily Workflow](#the-daily-workflow)
6. [Working With Others](#working-with-others)
7. [Branches Explained Simply](#branches-explained-simply)
8. [Pull Requests (PRs)](#pull-requests-prs)
9. [Issues and Project Boards](#issues-and-project-boards)
10. [README Files](#readme-files)
11. [Common Mistakes and How to Avoid Them](#common-mistakes-and-how-to-avoid-them)
12. [When Things Go Wrong](#when-things-go-wrong)
13. [GitHub vs. Other Tools](#github-vs-other-tools)
14. [Quick Reference Cheat Sheet](#quick-reference-cheat-sheet)
15. [Glossary](#glossary)

---

## The Big Picture

### What problem does GitHub solve?

Imagine you are writing a book. You save `Chapter1.docx`, then `Chapter1_v2.docx`, then `Chapter1_FINAL.docx`, then `Chapter1_FINAL_really.docx`. Soon you cannot tell which version is current, and if you delete something by accident, it may be gone forever.

**Git** is software that tracks every change you make to files over time. **GitHub** is a website that stores those tracked projects online so you can:

- **Back up** your work in the cloud
- **See history** — every change, who made it, and when
- **Undo mistakes** by going back to an earlier version
- **Collaborate** with others without overwriting each other's work
- **Share** code, documents, or any text-based project with the world

### The filing cabinet analogy

| Real world | GitHub equivalent |
|---|---|
| A filing cabinet | A **repository** (repo) |
| A folder of documents | The files inside the repo |
| A photocopy of every page every time you edit | A **commit** (a saved snapshot) |
| A sticky note explaining what you changed | A **commit message** |
| A duplicate cabinet at a friend's office | A **remote** copy on GitHub's servers |
| Working on a draft copy before putting it in the cabinet | Your **local** copy on your computer |

---

## Key Terms (Plain English)

### Repository (repo)
A project folder that Git tracks. It contains your files plus the full history of every change. Repos can be **public** (anyone can see) or **private** (only you and people you invite).

### Clone
Downloading a copy of a repo from GitHub to your computer so you can work on it locally.

### Commit
Saving a snapshot of your changes with a short description. Think of it like clicking "Save" in a video game — you are creating a restore point you can return to.

### Push
Uploading your local commits to GitHub so the online copy is up to date.

### Pull
Downloading the latest changes from GitHub to your computer.

### Branch
A parallel version of your project. The main line of work is usually called `main` (or sometimes `master` in older repos). Branches let you experiment without breaking the main version.

### Merge
Combining changes from one branch into another.

### Fork
Your own copy of someone else's repo on GitHub. You can change your fork without affecting the original.

### Pull Request (PR)
A request to merge your changes into someone else's repo (or into the main branch). It is a place for review and discussion before changes go live.

### .gitignore
A special file that tells Git which files to *not* track — things like passwords, temporary files, or large downloads.

---

## Setting Up

### Step 1: Create a GitHub account

1. Go to [github.com](https://github.com)
2. Click **Sign up**
3. Choose a username, email, and password
4. Verify your email

Your username becomes part of every repo URL: `github.com/yourusername/project-name`

### Step 2: Install Git on your computer

Git is the engine; GitHub is where repos live online. You need Git installed locally.

**On Mac:**
```bash
# Check if Git is already installed
git --version

# If not installed, install Xcode Command Line Tools when prompted,
# or download from https://git-scm.com
```

**On Windows:**
Download and run the installer from [git-scm.com](https://git-scm.com). Accept the defaults during setup.

### Step 3: Tell Git who you are

Run these once in your terminal (Terminal on Mac, Git Bash or PowerShell on Windows):

```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

Use the same email you used for your GitHub account.

### Step 4 (optional but recommended): Install GitHub Desktop

If the command line feels intimidating, [GitHub Desktop](https://desktop.github.com) gives you buttons and menus for clone, commit, push, and pull. Many beginners start here and learn the terminal later.

---

## Your First Repository

You can create a repo two ways: on the GitHub website, or from your computer.

### Option A: Create on GitHub (easiest for beginners)

1. Log in to GitHub
2. Click the **+** icon (top right) → **New repository**
3. Fill in:
   - **Repository name** — short, no spaces (use hyphens: `my-first-project`)
   - **Description** — optional one-line summary
   - **Public or Private** — public = anyone can see; private = only you and invitees
   - Check **Add a README file** — this creates a starter file explaining your project
4. Click **Create repository**

You now have a repo at `github.com/yourusername/my-first-project`.

### Option B: Create from your computer

```bash
# Navigate to where you want the project folder
cd ~/Documents

# Create the folder and turn it into a Git repo
mkdir my-first-project
cd my-first-project
git init

# Create a file
echo "# My First Project" > README.md

# Save your first snapshot
git add .
git commit -m "Initial commit"

# Connect to GitHub (create the empty repo on GitHub first, then copy its URL)
git remote add origin https://github.com/yourusername/my-first-project.git
git push -u origin main
```

### Cloning an existing repo

If a repo already exists on GitHub and you want a copy on your machine:

```bash
git clone https://github.com/yourusername/my-first-project.git
```

This creates a folder called `my-first-project` with all the files and full history.

---

## The Daily Workflow

This is the cycle you will repeat hundreds of times:

```
Edit files → Stage changes → Commit → Push
                ↑                        ↓
           (git add)              (git push)
                                    ↓
                              GitHub is updated
```

### Step by step

**1. Make changes** — Edit files in your project folder using any text editor, VS Code, Cursor, etc.

**2. Check what changed**
```bash
git status
```
This shows which files were modified, added, or deleted.

**3. Stage the changes you want to save**
```bash
# Stage one file
git add README.md

# Stage everything that changed
git add .
```

**4. Commit with a message**
```bash
git commit -m "Add project description to README"
```

Good commit messages are short and describe *what* changed and *why*:
- ✅ `"Fix typo in installation instructions"`
- ✅ `"Add chapter 3 notes"`
- ❌ `"stuff"`
- ❌ `"asdfasdf"`

**5. Push to GitHub**
```bash
git push
```

Your changes are now backed up online and visible to collaborators.

### Before you start working (especially on a team)

Always pull first to get the latest changes:

```bash
git pull
```

---

## Working With Others

### Inviting collaborators to your repo

1. Open your repo on GitHub
2. Go to **Settings** → **Collaborators**
3. Click **Add people** and enter their GitHub username or email
4. They accept the invitation

Now you both push to the same repo. Git keeps track of who changed what.

### Cloning a teammate's repo

```bash
git clone https://github.com/teammate/project-name.git
```

### The golden rule of collaboration

**Pull before you push.** Always run `git pull` before starting work and before pushing. This prevents most conflicts.

---

## Branches Explained Simply

Branches let you work on a feature or experiment without touching the stable `main` version.

```
main:     A --- B --- C ------------------- F (merged)
                       \                   /
feature:                D --- E ----------/
```

### Creating and using a branch

```bash
# Create and switch to a new branch
git checkout -b add-new-section

# Make changes, commit as usual
git add .
git commit -m "Add new section to guide"

# Push the branch to GitHub
git push -u origin add-new-section
```

When your work is ready, you open a **Pull Request** to merge it into `main`.

### Switching branches

```bash
# See all branches
git branch

# Switch to an existing branch
git checkout main
```

---

## Pull Requests (PRs)

A Pull Request is not just "please merge my code." It is a conversation space.

### When to use a PR

- Merging a feature branch into `main`
- Contributing to someone else's open-source project
- Getting feedback before changes go live

### How to open a PR

1. Push your branch to GitHub
2. GitHub shows a banner: **Compare & pull request** — click it
3. Write a title and description explaining your changes
4. Click **Create pull request**
5. Reviewers can comment, request changes, or approve
6. When approved, click **Merge pull request**

### PR best practices

- Keep PRs focused — one feature or fix per PR
- Write a clear description of what changed and why
- Link to any related Issues

---

## Issues and Project Boards

### Issues
Issues are GitHub's built-in to-do list and bug tracker. Each Issue is a ticket you can assign, label, and discuss.

**Creating an Issue:**
1. Open your repo → **Issues** tab → **New issue**
2. Write a clear title: `"Fix broken link on page 3"`
3. Add details, labels (bug, enhancement, question), and assign someone

### Project Boards
Kanban-style boards (To Do → In Progress → Done) that organize Issues and PRs. Find them under the **Projects** tab.

---

## README Files

Every repo should have a `README.md` at the root. This is the first thing visitors see.

A good README includes:

```markdown
# Project Name

One sentence explaining what this project is.

## What is this?
Longer description for people who land here with no context.

## Getting Started
Step-by-step instructions to use or install the project.

## How to Contribute
Guidelines if you want others to help.

## License
Who can use this and how.
```

The `.md` extension means **Markdown** — a simple formatting language using `#` for headings, `-` for lists, and `**bold**` for emphasis.

---

## Common Mistakes and How to Avoid Them

| Mistake | What happens | Fix |
|---|---|---|
| Forgetting to pull before editing | Merge conflicts | Always `git pull` first |
| Committing passwords or API keys | Security risk — keys may be public forever | Use `.gitignore`; never commit secrets |
| Vague commit messages | Hard to find changes later | Write clear, specific messages |
| Committing huge files (videos, datasets) | Repo becomes slow and bloated | Add them to `.gitignore`; use cloud storage instead |
| Working directly on `main` for big changes | Risk breaking the stable version | Use branches for anything non-trivial |
| Not pushing for days | Work only exists on your machine — lost if laptop dies | Push at least daily |

### What is a .gitignore file?

Create a file named `.gitignore` in your repo root:

```
# Secrets — never commit these
.env
*.key
credentials.json

# System junk
.DS_Store
Thumbs.db

# Large or generated files
node_modules/
*.mp4
dist/
```

---

## When Things Go Wrong

### "I committed to the wrong branch"
```bash
# Save your commits to the correct branch
git checkout correct-branch
git cherry-pick <commit-hash>
```

Or ask for help — this is a common beginner situation and fixable.

### "I want to undo my last commit"
```bash
# Undo commit but keep your file changes
git reset --soft HEAD~1
```

### "I have a merge conflict"
This happens when two people edited the same lines. Git marks the conflict in the file:

```
<<<<<<< HEAD
Your version of the text
=======
Their version of the text
>>>>>>> branch-name
```

Open the file, delete the markers, keep the correct text (or combine both), then:

```bash
git add the-conflicted-file.txt
git commit -m "Resolve merge conflict"
```

### "I accidentally deleted something"
Git remembers everything:
```bash
# See history of a file
git log -- path/to/file.txt

# Restore a file from a previous commit
git checkout <commit-hash> -- path/to/file.txt
```

### When in doubt
GitHub's [docs](https://docs.github.com) and searching your exact error message usually solve 90% of problems.

---

## GitHub vs. Other Tools

| Tool | What it is | When to use it |
|---|---|---|
| **GitHub** | Online home for Git repos + collaboration features | Code, docs, open source, team projects |
| **GitLab / Bitbucket** | Alternatives to GitHub | Same core ideas, different company |
| **Google Drive / iCloud** | Cloud file storage | Documents, photos — no version history like Git |
| **Obsidian Sync / iCloud** | Note syncing | Personal notes — not for code collaboration |

GitHub shines when you need **history**, **collaboration**, and **branching**. For a single Word doc you edit alone, Google Drive is simpler. For a coding project or shared documentation, GitHub is the standard.

---

## Quick Reference Cheat Sheet

```bash
# Setup (once)
git config --global user.name "Your Name"
git config --global user.email "you@email.com"

# Starting out
git clone <url>              # Download a repo
git init                     # Start a new repo in current folder

# Daily loop
git status                   # What changed?
git pull                     # Get latest from GitHub
git add .                    # Stage all changes
git commit -m "message"        # Save a snapshot
git push                     # Upload to GitHub

# Branches
git branch                   # List branches
git checkout -b new-branch   # Create and switch to new branch
git checkout main            # Switch back to main

# History
git log                      # See commit history
git diff                     # See unstaged changes
```

---

## Glossary

| Term | Definition |
|---|---|
| **Commit** | A saved snapshot of your project at a point in time |
| **Repository (repo)** | A tracked project folder with full change history |
| **Remote** | The copy of your repo stored on GitHub's servers |
| **Local** | The copy of your repo on your computer |
| **Clone** | Download a repo from GitHub to your machine |
| **Push** | Upload local commits to GitHub |
| **Pull** | Download latest commits from GitHub |
| **Branch** | An independent line of development |
| **Merge** | Combine changes from one branch into another |
| **Fork** | Your personal copy of someone else's repo |
| **Pull Request (PR)** | A request to merge changes, with space for review |
| **Issue** | A ticket for bugs, tasks, or discussions |
| **README** | The front-page description file in a repo |
| **.gitignore** | File listing paths Git should not track |
| **Markdown (.md)** | Simple text formatting used for READMEs and docs |
| **Open source** | Public repos anyone can view, use, and contribute to |

---

*You do not need to memorize everything in this guide. Bookmark it, start with "clone → edit → commit → push," and look up the rest as you need it.*