---
title: 1-starting-from-github-why-and-how
---

# Starting from GitHub vs. Moving Local Code to GitHub

## Why we're walking through this topic

Many people first encounter Git *after* they have already started writing code locally in an IDE. That situation is common—and recoverable—but it also motivates an important lesson:

> **Starting from a GitHub repository is usually easier than retrofitting Git later.**

This walkthrough explains:
1. Why moving local work to GitHub is a valuable skill
2. Why you can often avoid that complexity by starting from GitHub
3. How to access (clone) an existing GitHub repository
4. How to create a GitHub repository when you don’t have one yet

The goal is not to shame local-first workflows, but to help collaborators choose the *least painful* starting point.

---

## 1. Moving local work to GitHub: a useful but nontrivial skill

Knowing how to take an existing local codebase and publish it to GitHub is important because:

- You may inherit code that was never version-controlled
- You may prototype before knowing a project will become collaborative
- You may work offline or outside institutional GitHub access

That said, moving from local-only work to GitHub requires extra steps:

- Initializing Git manually
- Creating a remote repository
- Connecting local history to GitHub
- Resolving mismatches between local and remote state

This is all doable—but it adds friction.

---

## 2. Why starting from GitHub is usually easier

When you start with a GitHub repository:

- Git is already initialized
- A remote (`origin`) is already defined
- Collaboration defaults (visibility, permissions) are set early
- Version history begins at the start of the project

In practice, this means:

> You clone once, then work locally *inside* a Git-managed project from day one.

For most collaborative or instructional projects, this is the recommended path.

---

## 3. How to access (clone) an existing GitHub repository

If a GitHub repository already exists, you do **not** need to create one locally. Instead, you *clone* it.

### Step 3.1: Copy the repository URL

On GitHub:
- Open the repository
- Click the **Code** button
- Copy the HTTPS URL (recommended for most users)

---

### Step 3.2: Clone the repository locally

In the terminal:

cd /path/where/you/keep/projects
git clone https://github.com/username/repo-name.git

This creates a local folder containing:
- the full codebase
- the complete Git history
- a remote connection to GitHub (`origin`)

Move into the project:

cd repo-name
git status

At this point, you can open the folder in your IDE and begin working normally.

---

## 4. How to create a GitHub repository (recommended starting point)

If no repository exists yet, create one **on GitHub first**, then clone it.

### Step 4.1: Create the repository on GitHub

On GitHub:

1. Click **New repository**
2. Choose a name
3. Set visibility (public or private)
4. Check **Add a README** (recommended)
5. Click **Create repository**

Adding a README ensures the repo is not empty, which simplifies cloning.

---

### Step 4.2: Clone your new repository

cd /path/where/you/keep/projects
git clone https://github.com/username/new-repo-name.git
cd new-repo-name

Now your project exists both:
- locally (for editing)
- remotely (for collaboration and backup)

---

## A quick mental-model check: how Git and GitHub differ from other tools

If you are new to GitHub, it’s very common to bring assumptions from tools like Google Docs, Dropbox, or shared drives. Those assumptions are reasonable—but Git works differently in a few important ways.

### Common assumptions (and what’s actually happening)

**“If I save a file, GitHub sees it.”**
Saving a file only writes it to your computer. GitHub does not update until you:
1. commit the change locally, and then
2. push that commit to GitHub.

**“The project lives on GitHub; my computer just accesses it.”**
When you clone a repository, you get a *full copy* of the project and its history. While you’re working, the project lives on your machine. GitHub is a shared, remote copy—not the place where editing happens.

**“One wrong move could break the repo for everyone.”**
Git is designed to make experimentation safe. Changes don’t affect anyone else until you push them, and using branches lets you work without touching shared code.

These differences explain why Git uses explicit steps (add → commit → push): they give you control over *when* and *what* you share.

---

## Local work still happens locally

Starting from GitHub does **not** mean:

- editing code in a browser
- giving up your IDE
- being online all the time

It simply means:

> Your local work lives inside a project that already knows how to sync with GitHub.

### An important clarification: saving vs. GitHub

When you work in an IDE after cloning a repository:

- **Saving a file** (Cmd/Ctrl+S) only saves it on *your computer*
- GitHub does **not** see your changes automatically
- Nothing is shared until you explicitly tell Git to do so

Think of Git as a three-step publishing process:

1. **Edit & save** files locally (IDE / text editor)
2. **Commit** changes locally (Git records a snapshot)
3. **Push** commits to GitHub (GitHub receives the update)

Until you run `git push`, GitHub remains unchanged.

GitHub is therefore best thought of as:
> a shared archive you *publish to*, not a live mirror of your editor.

All editing still happens locally; GitHub just provides structure, history, and collaboration.

---

## When local-first still makes sense

Starting locally is reasonable when:

- You are experimenting and may discard the code
- You are learning a language or tool solo
- You don’t yet know whether the project will persist

The key is recognizing when a project *graduates* into something collaborative—and moving it to GitHub at that point.

---

## 5. Pushing updates back to GitHub: main vs branches

Once you are working inside a cloned repository, the basic update cycle looks like this:

git add .
git commit -m "Describe your changes"
git push

A key decision is **where** those changes should go.

### Option A: Push directly to `main`

This is appropriate when:
- You are working solo
- The change is small, safe, or clearly correct
- `main` represents the active working version

Typical flow:

git switch main
git add .
git commit -m "Update X"
git push

### Option B: Create a new branch (recommended for collaboration)

Creating a branch is safer when:
- Others are working in the same repo
- You are experimenting or refactoring
- You want review or discussion before merging

Typical flow:

git switch -c new-branch-name
git add .
git commit -m "Work in progress"
git push -u origin new-branch-name

This publishes your work **without changing `main`**, allowing collaborators to review or merge later.

---

## Summary: choosing the path of least friction

- ✔ **Start from GitHub** when collaboration, longevity, or teaching is expected
- ✔ **Know how saving, committing, and pushing differ**
- ✔ **Push to `main` only when appropriate**; use branches when in doubt
- ✔ Prefer cloning over initializing Git by hand

> Git works best when it is present from the beginning—but it is forgiving when it isn’t.

- ✔ **Start from GitHub** when collaboration, longevity, or teaching is expected
- ✔ **Know how to move local code to GitHub** for recovery and flexibility
- ✔ Prefer cloning over initializing Git by hand

> Git works best when it is present from the beginning—but it is forgiving when it isn’t.