Your First Repository

Your GitHub account is all set up, so let's make your very first project. On GitHub a project is called a "repository" (or "repo" for short). Let's build one!

What is a Repository?#

A repository is just a folder that Git keeps track of. Inside you'll find a few things.

• All your project files
• The complete history of every change
• Settings for how the project works

Think of it as a regular folder on your computer... with superpowers. Git watches everything that happens in that folder and keeps a record of every single change.

Creating a Repository on GitHub#

We'll make your first repo right on GitHub, then pull it down to your computer.

Step 1. Go to GitHub#

Open github.com and make sure you're signed in.

Step 2. Create New Repository#

Click the green "New" button near "Repositories" on the left, or click the "+" in the top-right corner and pick "New repository."

Step 3. Name Your Repository#

Give your repository a name. For this exercise, let's call it my-first-repo.

Naming tips

• Use lowercase letters
• Use hyphens instead of spaces
• Keep it short but descriptive

Step 4. Add a Description#

Write a quick description of what this project is, something like "My first GitHub repository for learning Git."

Step 5. Choose Visibility#

Pick who gets to see your repo.

• Public - Anyone can see it
• Private - Only you can see it

For learning, either one is totally fine!

Step 6. Initialize the Repository#

Turn on the option to add a README file (depending on how GitHub has the page laid out that week, it's a checkbox or a toggle). That creates a starting file for your project.

Step 7. Create Repository#

Click the green "Create repository" button.

Cloning: Download Your Repository#

Your repository lives on GitHub now, but you need a copy on your computer to actually work on it. Grabbing that copy is called "cloning."

Get the Clone URL#

Step 1. Find the Code Button#

On your repository page, click the green "Code" button.

Step 2. Copy the SSH URL#

Make sure "SSH" is selected (NOT HTTPS), then click the clipboard icon to copy the URL.

It should look something like [email protected]:yourusername/my-first-repo.git

Clone to Your Computer#

Step 3. Open Your Terminal#

Open up your terminal app.

Step 4. Navigate to Where You Want the Project#

Pick where you want your project to live. For example, this.

cd ~/Projects

No Projects folder yet? Make one.

mkdir ~/Projects && cd ~/Projects

Step 5. Clone the Repository#

Run the clone command with your URL.

git clone [email protected]:yourusername/my-first-repo.git

Swap "yourusername" for your actual GitHub username (copy-pasting it as-is is a classic first-timer move, no shame).

Step 6. Enter the Project Folder#

cd my-first-repo

And now you've got a complete copy of your repository on your computer!

What Just Happened?#

When you cloned the repository, Git did a handful of things for you.

1. Git created a new folder called my-first-repo
2. It downloaded all the files from GitHub (just the README for now)
3. It set up a connection between your local folder and GitHub
4. It downloaded the complete history of the project

Explore Your Repository#

Let's peek at what's inside your new repository.

ls -la

You should see two things.

• README.md - The file GitHub made for you
• .git - A hidden folder where Git keeps all its tracking data

Never hand-edit the .git folder! Git manages it on its own, and poking at it is a fast way to ruin your afternoon.

The README File#

Open the README.md file and see what's in there.

cat README.md

You'll see your repository name as a heading. This file uses Markdown, which is a simple way to format text. We'll get into Markdown more later.

Common Issues#

"Permission denied (publickey)" error

• Your SSH key isn't set up quite right
• Head back to the previous lesson and double-check your SSH setup

"Repository not found" error

• Make sure the URL is correct
• Make sure you're signed in to the right GitHub account

Cloned but can't find the folder

• Think back to which directory you were in when you cloned
• Use ls to list folders and cd to move around

TL;DR#

• A repository is a folder that Git keeps track of
• You can create repositories on GitHub through the website
• Cloning downloads a repository from GitHub to your computer
• Your local copy stays connected to the remote copy on GitHub
• The README.md file describes your project

What's Next?#

You've got a repository on GitHub AND on your computer. Now it's time to learn how to make changes and save them. Next lesson covers the basic Git workflow of add, commit and push...