GitHub Repositories

Create a repository on GitHub, write a helpful README, choose public or private, and add a .gitignore and licence.

Lesson 2 of 30Beginner18 min read

A repository on GitHub is the online home of a project. It holds all of the project's files and their complete Git history, plus a front page that describes the project, a list of issues, pull requests and settings.

Creating a repository takes about a minute, but a few choices on that first screen matter: its name, whether it's public or private, and whether to start it with a README, a .gitignore and a licence. A clear README in particular is what makes people understand, trust and use your project.

In this lesson you'll create a repository, write a README in Markdown, and learn what the other options do.

Creating a repository

  1. Click the + menu at the top right of GitHub and choose New repository.
  2. Enter a name: short, lowercase and hyphenated, such as recipe-website or weather-app.
  3. Add a one-line description.
  4. Choose Public (anyone can see it) or Private (only you and people you invite).
  5. Optionally tick Add a README file, choose a .gitignore template and a licence.
  6. Click Create repository.

If you already have a project on your computer, leave all three options unticked. GitHub then shows the exact commands to connect your existing folder, which you'll use in the next lesson.

README files

README.md is the first thing visitors see. It's written in Markdown, a simple way to format text:

MarkdownResult
# TitleLarge heading
## SectionSmaller heading
**bold** and *italic*bold and italic
- itemBulleted list
[text](https://...)Link
![alt](screenshot.png)Image

A good README answers four questions: what is this, what does it look like, how do I run it, and who made it.

.gitignore and licences

  • A .gitignore template gives you a ready-made list of files to ignore for a language, such as Python or Node. You can edit it later. See the Git history lesson for how it works.
  • A licence tells others what they may do with your code. Without one, nobody is legally allowed to reuse it. The MIT License is short and permissive and is a common choice for personal and open-source projects. GitHub explains each option when you choose it.

Working on GitHub directly

You can do a lot without leaving the browser:

  • Add file creates or uploads files.
  • The pencil icon edits a file. When you save, GitHub makes a commit and asks for a message.
  • Press . on any repository page to open a full code editor in your browser.
  • Settings lets you rename the repository, change its visibility, manage collaborators or delete it.

Renaming, archiving and deleting a repository

Repository names aren't permanent. If you rename weather-app to weather-dashboard in the repository's Settings, GitHub redirects the old web address and the old clone URL to the new name, so existing links and local copies keep working. It's still worth updating your local remote so you aren't relying on the redirect:

Terminal
git remote set-url origin https://github.com/samlee/weather-dashboard.git

The redirect stops working if you later create a new repository with the old name, because that name then belongs to the new project.

When a project is finished but worth keeping, archive it rather than deleting it. An archived repository becomes read-only: people can still view, clone and fork it, but nobody can push, open issues or comment. A banner tells visitors it's no longer maintained, which sets expectations for anyone who finds it, and you can unarchive it if you pick the project up again.

Deleting a repository removes its issues, pull requests and settings along with the code, and GitHub asks you to type the repository's name to confirm. Your local clone isn't affected, so the files and their history are still on your computer.

GitHub Repositories Syntax

README.md structure

# Project name

One sentence about what it does.

![Screenshot](screenshot.png)

## How to run it
1. Step one
2. Step two

## Built with
- HTML, CSS and JavaScript

GitHub Repositories Summary

  • Create repositories from the + menu; use short, hyphenated names.
  • Public repositories are visible to everyone; private ones only to people you invite.
  • README.md is the project's front page, written in Markdown.
  • Start with a .gitignore template for your language and add a licence such as MIT.
  • Leave the starter files unticked if you'll push an existing local project.

GitHub Repositories Examples

Each example shows the code, the output it produces and what each part does.

Example 1

A clear README

Markdown
# Recipe Website

A small website with my favourite family recipes, built while learning HTML and CSS.

![Home page screenshot](images/screenshot.png)

## Features
- Responsive layout that works on phones
- Recipes grouped by meal
- Printable recipe pages

## Run it
Open `index.html` in your browser. No installation needed.
Output
Recipe Website
A small website with my favourite family recipes, built while learning HTML and CSS.
[screenshot of the home page]

Features
• Responsive layout that works on phones
• Recipes grouped by meal
• Printable recipe pages

Run it
Open index.html in your browser. No installation needed.
Line-by-line explanation
  1. Line 1One # makes the main title.
  2. Line 5The screenshot shows the project at a glance.
  3. Lines 7 to 10A short, scannable list of features.
  4. Lines 12 to 13Tell people exactly how to run the project.
Example 2

A Python .gitignore (part of the template)

Text
# Byte-compiled files
__pycache__/
*.pyc

# Virtual environments
venv/
.venv/

# Secrets
.env
Output
Git will ignore these files and folders in every commit.
Line-by-line explanation
  1. Lines 2 to 3Files Python creates automatically.
  2. Lines 6 to 7Installed packages, which can be recreated and shouldn't be committed.
  3. Line 10Local secrets such as API keys.
Example 3

Creating a repository with GitHub CLI

Terminal
gh repo create weather-app --public --description "A simple weather app" --add-readme --clone
Output
✓ Created repository samlee/weather-app on GitHub
  https://github.com/samlee/weather-app
Cloning into 'weather-app'...
Line-by-line explanation
  1. Line 1The same choices as the website form, in one command. --clone downloads it to your computer straight away.

Common GitHub Repositories Mistakes

Committing a project with no README

Don't
my-project/
  index.html
  style.css
Do
my-project/
  README.md
  index.html
  style.css

Without a README, visitors have no idea what the project is or how to use it.

Ticking README on GitHub, then pushing an existing project

Don't
# created the repo WITH a README, then:
git push -u origin main   # rejected: fetch first
Do
# create the repo with NO starter files, then:
git push -u origin main

GitHub's README is a commit your local project doesn't have, so the histories don't match.

GitHub Repositories in Real Projects

Repositories that people love

Popular open-source repositories have READMEs with a short pitch, a screenshot or animated demo, installation steps, usage examples and a link to contributing guidelines. Even small personal projects look professional with the same structure, and it's the best way to show employers what you've built.

GitHub Repositories FAQ

How do I change a repository from private to public?

Open the repository's Settings and use the option to change its visibility, near the bottom of the page. Before making it public, check the whole history for passwords, keys and personal data, because every old commit becomes visible too, not just the current files.

What is the maximum file size on GitHub?

GitHub warns you when you push a file larger than 50 MB and blocks files larger than 100 MB. For large files such as videos, datasets or design assets, use Git Large File Storage (Git LFS) or keep them outside the repository.

How do I add a licence to an existing repository?

Create a file named LICENSE in the top folder of the repository. When you create it on GitHub, the editor offers a licence template picker, so you can choose one such as MIT and have the text filled in. GitHub then shows the licence on the repository's front page.

How do I download a repository without using Git?

Open the green Code button and choose Download ZIP. You get the current files of that branch, but not the Git history, so you can't commit or pull with it. To work on the project properly, clone it instead.

What are repository topics?

Topics are short tags such as python, game or machine-learning that you add in the About section of a repository's page. They help people find your project through GitHub's search and topic pages, and they tell visitors at a glance what it's about.

GitHub Repositories Exercises

Answer each one and check it instantly. If you get stuck, open the hint before the answer.

Fill in the blankseasy

Complete the Markdown so it shows a main heading and a bold word.

 Weather App
A **** app that shows the forecast.
Multiple choiceeasy

Who can see a private repository?

Multiple choicemedium

Why add a licence such as MIT to a public project?

Predict the outputmedium

What happens to a line ## Installation in a README?

Multiple choicemedium

Which visibility lets only you and invited people see a repository?

GitHub Repositories Quiz

5 questions to check what you learned.

  1. What is the file name of a repository's front page?

    • index.txt
    • HOME.md
    • README.md
    • about.html

  2. What format are README.md files written in?

    • HTML
    • Markdown
    • JSON
    • Plain text only

  3. You'll push an existing project. Which starter files should you tick when creating the repository?

    • All of them
    • Only README
    • None of them
    • Only the licence

  4. Which keyboard shortcut opens GitHub's browser-based editor on a repository page?

    • E
    • Ctrl + E
    • /
    • . (full stop)

  5. What does a licence file tell people?

    • How to install the project
    • Who wrote each line
    • What they're allowed to do with the code
    • Which branch to use

Related GitHub topics

01IntroductionWhat GitHub is, how it relates to Git, the words you'll see everywhere, and how to set up your account.06Push, Pull & CloneConnect a local repository to GitHub, push your commits, pull others' changes and clone repositories.
Esc
↑↓ to navigateEnter to open