01-working-with-github.md

Working with GitHub

Learning Goals

• Create a new repository on GitHub
• Understand the difference between public and private repositories
• Clone a GitHub repository to your local machine
• Understand the relationship between local and remote repositories
• Push local commits to GitHub
• Pull changes from GitHub to your local machine
• Know the difference between fetch and pull

Introduction

In the previous exercise, you worked with Git entirely on your local machine. Now it's time to move to GitHub — a platform for hosting Git repositories online.

A GitHub repository gives your code:

• A remote backup — your code lives safely in the cloud
• A URL — you can share your project with anyone
• Collaboration tools — Pull Requests, Issues, Actions, and more

Key concepts

• Remote — A version of your repository hosted somewhere else (e.g., GitHub). By convention, the default remote is called origin
• Origin — The default name for the remote you cloned from
• Clone — Create a local copy of a remote repository
• Push — Upload your local commits to the remote
• Pull — Download remote changes and merge them into your local branch
• Fetch — Download remote changes without merging (just look, don't touch)

GitHub (origin)          Your Machine (local)
┌──────────────┐         ┌──────────────┐
│  Repository  │ ◀─push──│  Repository  │
│  (remote)    │ ──pull─▶│  (local)     │
└──────────────┘         └──────────────┘

💡 If you don't have a GitHub account yet, go to github.com and sign up — it's free.

Exercise

Overview

• Create a new repository on GitHub named github-katas-playground
• Clone the repository to your local machine
• Explore the remote connection with git remote
• Edit files, commit, and push changes to GitHub
• Verify the changes on GitHub's web interface
• Understand git fetch vs git pull

Step by step instructions

Step by step

Part 1: Create a GitHub repository

Task 1: Navigate to the "New repository" page

• Log in to github.com
• Click the + icon in the top-right corner of the page
• Select New repository

💡 You can also go directly to github.com/new.

Task 2: Fill in the repository details

Fill in the form with the following:

Field	Value
Repository name	github-katas-playground
Description	My playground repo for the GitHub Katas exercises
Visibility	Private
Initialize this repository with	✅ Add a README file

💡 Public/Private/Internal?

• Public — Anyone can see the repo. Great for open source and learning.
• Private — Only you and people you invite can see it. Good for personal or company projects.
• Internal — Only people in your organization can see it. For company use.

For this exercise, we recommend Private. You can always change it later in Settings.

Leave the .gitignore template and license as None for now.

Click the green Create repository button.

You should be taken to your new repository page at https://github.com/<your-username>/github-katas-playground.

---

Part 2: Clone the repository

Task 3: Get the clone URL

On your repository page, click the green Code button. You'll see options for HTTPS, SSH, and GitHub CLI.

Copy the HTTPS URL (it looks like https://github.com/<your-username>/github-katas-playground.git).

💡 HTTPS vs SSH — which should I use?

Both work for cloning and pushing code:

Method	URL format	Authentication
HTTPS	https://github.com/user/repo.git	Username + Personal Access Token (PAT)
SSH	git@github.com:user/repo.git	SSH key pair

For beginners, HTTPS is simpler — it works immediately. You'll be prompted for credentials when you push.

SSH is more convenient long-term — once set up, you never need to enter credentials. See GitHub's SSH guide to set it up.

For this exercise, use whichever you prefer. If unsure, go with HTTPS.

Task 4: Clone the repository

Open your terminal and navigate to where you want to keep your projects:

cd ~

Clone the repository:

git clone https://github.com/<your-username>/github-katas-playground.git

💡 Replace <your-username> with your actual GitHub username!

Expected output:

Cloning into 'github-katas-playground'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.

Then open the cloned folder:

cd github-katas-playground

💻 VS Code alternative

1. Open VS Code
2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
3. Type "Git: Clone" and select it
4. Paste the repository URL and press Enter
5. Choose a folder to clone into
6. When prompted, click Open to open the cloned repository

Task 5: Explore the cloned repository

List the files:

ls -la

You should see .git/ and README.md. The .git/ folder is the Git database — just like when you used git init, but this time it was created by git clone and contains the history from GitHub.

Check the status:

git status

Expected output:

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

💡 Notice it says "up to date with 'origin/main'" — your local repo knows about the remote! This connection was set up automatically by git clone.

Task 6: Inspect the remote connection

See which remotes are configured:

git remote -v

Expected output:

origin  https://github.com/<your-username>/github-katas-playground.git (fetch)
origin  https://github.com/<your-username>/github-katas-playground.git (push)

💡 origin is just a name — a shortcut for the full GitHub URL. When you run git push origin main, you're telling Git "push to the remote called origin, branch main."

---

Part 3: Make changes and push

Task 7: Edit the README and commit

Open README.md in your editor and replace its contents with:

# GitHub Katas Playground

This is my playground repository for the GitHub Katas exercises.

## What I'm Learning

- Git basics (init, add, commit, log)
- Creating repos on GitHub
- Cloning and pushing
- Branches and Pull Requests

Stage and commit:

git add README.md
git commit -m "Update README with learning goals"

💻 VS Code alternative

1. Open README.md from the Explorer panel and edit it
2. Open the Source Control panel (Ctrl+Shift+G / Cmd+Shift+G)
3. Click the + icon next to README.md to stage it
4. Type the commit message: Update README with learning goals
5. Click ✓ Commit

Task 8: Create a new file and commit

Create a file called notes.md with the following content:

# My Git Notes

## Useful Commands

| Command | What it does |
|---------|-------------|
| `git status` | Show the state of working directory and staging area |
| `git add <file>` | Stage changes for the next commit |
| `git commit -m "msg"` | Create a commit with a message |
| `git log` | Show commit history |
| `git push` | Upload local commits to the remote |

Stage and commit:

git add notes.md
git commit -m "Add personal notes on useful Git commands"

💻 VS Code alternative

1. Create the file: right-click in the Explorer panel → New File → name it notes.md
2. Paste the content above and save
3. In Source Control, stage with +, enter the commit message, and click ✓ Commit

Task 9: Check what's ahead

git status

Expected output:

On branch main
Your branch is ahead of 'origin/main' by 2 commits.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

💡 "Your branch is ahead of 'origin/main' by 2 commits" — Git tells you that you have local work that hasn't been pushed yet.

Task 10: Push to GitHub

git push

💡 This is shorthand for git push origin main. Since main is set up to track origin/main (done automatically by git clone), Git knows where to push.

💻 VS Code alternative

In the Source Control panel, click the ⋯ menu (three dots) and select Push. Or click the sync icon (↻) in the bottom-left status bar.

💡 If VS Code shows a "Sync Changes" button click it - this does both pull and push in one step.

If you're using HTTPS and haven't authenticated before, you may be prompted for your username and a Personal Access Token (not your password).

💡 How to create a Personal Access Token (PAT)

GitHub no longer accepts passwords for Git operations. You need a Personal Access Token:

1. Go to github.com/settings/tokens
2. Click Generate new token → Generate new token (classic)
3. Give it a name (e.g., "git-cli")
4. Select the repo scope
5. Click Generate token
6. Copy the token and use it as your password when prompted

💡 You can configure Git to cache your credentials so you don't have to enter them every time: git config --global credential.helper cache

Task 11: Verify on GitHub

Open your repository in the browser at https://github.com/<your-username>/github-katas-playground.

You should see:

• The updated README.md rendered on the page
• The notes.md file in the file listing
• Your commit messages in the commit history (click "commits")

---

Part 4: Fetch and Pull

Now let's understand how to get changes from GitHub to your local machine.

Task 12: Make a change on GitHub

Let's simulate a teammate (or yourself on another computer) making a change:

1. Go to your repo on GitHub
2. Click on README.md
3. Click the pencil icon (✏️) to edit the file
4. Add a new line at the bottom: - Fetch and pull
5. Click Commit changes, add the message Add fetch and pull to learning list, and confirm

You now have a commit on GitHub that doesn't exist locally.

Task 13: Fetch — look without touching

Back in your terminal:

git fetch

💻 VS Code alternative

In the Source Control panel, click the ⋯ menu and select Fetch.

Expected output:

remote: Enumerating objects: 5, done.
...
   bbb2222..ccc3333  main       -> origin/main

Now check the status:

git status

Expected output:

On branch main
Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
  (use "git pull" to update your local branch)

💡 git fetch downloaded the new commit from GitHub, but your local files haven't changed yet. The new commit is stored in origin/main — you can inspect it before merging.

You can see the incoming changes without applying them:

git log --oneline origin/main

Compare your local main with the remote:

git log --oneline main..origin/main

This shows commits that exist on origin/main but not on your local main.

Task 14: Pull — fetch and merge

Now apply the changes:

git pull

💻 VS Code alternative

In the Source Control panel, click the ⋯ menu and select Pull. Or click the sync icon (↻) in the bottom-left status bar — this does both fetch and pull.

💡 The sync icon in VS Code's status bar shows a number like ↓1 ↑1 — the first number is how many commits to pull, the second is how many to push.

Expected output:

Updating bbb2222..ccc3333
Fast-forward
 README.md | 1 +
 1 file changed, 1 insertion(+)

Your local README.md now includes the line you added on GitHub.

cat README.md

💡 git pull is essentially git fetch + git merge in one step. Use fetch when you want to see what changed before merging; use pull when you just want to get up to date.

Summary of fetch vs pull

Command	What it does
git fetch	Downloads new commits from the remote, but doesn't change your local files
git pull	Downloads new commits AND merges them into your current branch

Think of fetch as "check for mail" and pull as "check for mail and open it."

Summary

You've learned the complete local-to-remote workflow:

• Create a repository on GitHub
• Clone it to your local machine
• Push local commits to GitHub
• Fetch to see what's new on the remote
• Pull to download and merge remote changes

This is the daily cycle of working with GitHub. In the next exercise, you'll learn about branches and Pull Requests — the standard way teams collaborate without stepping on each other's toes.

Head over to Branches and Pull Requests to continue.