Creating Your First Repository

Understanding Repositories

A repository, often shortened to "repo," is a storage location for a project on GitHub. Each repository contains:

• All the files for one project
• The complete history of changes made to those files over time
• Documentation (README files, etc.)

Understanding what repositories are and how they work is essential for using GitHub effectively.

Public vs Private Repositories

Repositories can be either public or private:

Public Repositories:

• Visible to anyone on the internet who has the repository URL
• Anyone can view your code, download your files, and see your commit history
• Common for learning and portfolio projects because they allow you to:
  • Share your work
  • Demonstrate your skills
  • Receive feedback from others

Private Repositories:

• Only visible to you and people you specifically invite as collaborators
• Useful for:
  • Projects you're not ready to share
  • Assignments you're working on
  • Projects that contain sensitive information

GitHub provides free private repositories, so you can choose the privacy level that makes sense for each project. You can also change this setting later!

Learn more about repository visibility in GitHub's documentation.

Repository URLs

Each repository has its own unique URL on GitHub, following the pattern:

This URL serves as both:

• The web address where you can view the repository online
• The remote location where your code is stored in the cloud

Example: If your GitHub username is "johndoe" and your repository is called "my-first-website", your repository URL would be:

This URL structure makes it easy to predict your repository address and share it with others.

Version History

Repositories track the complete history of your project. Every time you save changes to GitHub, Git creates a snapshot called a commit.

Each commit records:

• What changed (which files were modified)
• When it changed (timestamp)
• Who made the change (your username)

This history allows you to:

• See how your project evolved
• Revert to previous versions if something goes wrong
• Understand what each change accomplished

For beginners, this history is valuable for learning from your progress and recovering from mistakes. You can view the commit history at any time to see how your project developed over time.

README Files

Repositories also include a README file option, which is a markdown document that describes the project. The README appears on the repository's main page and helps visitors understand:

• What the project does
• How to use it
• How to contribute (if applicable)

While optional, adding a README to your repositories is good practice because it:

• Helps others understand your work
• Serves as documentation for your future self
• Establishes professionalism and clarity

Even for simple projects, a brief README explaining what the project is and what technologies it uses helps establish professionalism and clarity.

Learn how to create great README files in GitHub's README documentation.

Creating a Repository

Creating a repository on GitHub is a simple process completed through the GitHub web interface. The process involves a few configuration choices that determine how your repository behaves and appears to others.

Step 1: Access Repository Creation

After logging into your GitHub account, look for a plus icon (+) in the top right corner of the page. This icon appears near your profile picture and notifications.

Clicking this icon opens a dropdown menu with several options including:

• "New repository" - Create a new repository
• "Import repository" - Import from another location
• "New codespace" - Start a development environment

Select "New repository" from this menu. This action takes you to the repository creation page where you'll configure your new repository.

Alternative: You can also visit github.com/new directly.

Step 2: Choose a Repository Name

On the repository creation page, you'll see a form asking for several pieces of information. The first and most important field is the repository name.

Choose a name that clearly describes your project. Good repository names are:

• Short - Easy to remember and type
• Descriptive - Tells others what the project is about
• Web-friendly - Use lowercase letters with hyphens instead of spaces

Good examples:

• my-first-website ✓
• portfolio-site ✓
• html-css-tutorial ✓

Avoid:

• My Website ✗ (has spaces, mixed case)
• project1 ✗ (not descriptive)

The repository name becomes part of the URL, so it should be web-friendly. GitHub will check if the name is available - if someone else has already used your chosen name, you'll need to pick a different one.

For detailed guidance, see GitHub's repository creation documentation.

Step 3: Add a Description (Optional)

The next section asks for a description, which is optional but helpful.

A good description briefly explains what the project is:

• "My first HTML and CSS website project"
• "A responsive portfolio site built with HTML and CSS"

This description appears on your repository's main page, in search results, and when others browse your repositories. While you can skip this field, adding a description helps others understand your project at a glance and makes your repositories more professional and discoverable.

Step 4: Choose Public or Private

You'll see options for making the repository public or private:

Public Repositories:

• Typically preferred for learning projects and portfolios
• Allow you to share your work and demonstrate your skills
• Enable GitHub Pages hosting (free website publishing)
• Potentially receive feedback from the community

Private Repositories:

• Free on GitHub (unlimited private repositories)
• Useful if you want to keep a project private while working on it
• You can make it public later when it's ready

You can change the privacy setting at any time after creating the repository, so you're not locked into your initial choice.

Step 5: Initialize Options

GitHub offers to initialize the repository with:

• README file - A markdown document describing your project
• .gitignore file - Helps exclude files you don't want to track
• License - Specifies how others can use your code

For your first repository:

• ✓ Add a README - Recommended! It gives you a file you can edit to describe your project
• ✗ .gitignore - Not needed for simple HTML/CSS projects (more relevant for projects that build or compile code)
• ? License - Optional for learning projects (you can add one later if needed)

Step 6: Create the Repository

After filling in the repository name, optionally adding a description, choosing public or private, and deciding whether to initialize with a README, click the green "Create repository" button at the bottom of the page.

GitHub will create your repository and display a page with instructions for getting started. This page shows different options depending on whether you're creating a new project or adding an existing project to GitHub.

Since you likely have HTML and CSS files already created on your computer, you'll want to follow the instructions for adding files to your repository.

Adding Files to Your Repository

Once your repository is created, you need to add your HTML and CSS files to it. GitHub provides several methods for adding files, and the web interface method is simplest for beginners.

Accessing the Upload Interface

If you didn't initialize your repository with a README, GitHub will show you instructions for creating your first file or uploading existing files.

Look for links or buttons that say:

• "uploading an existing file"
• "Add file"

Clicking these options takes you to GitHub's file upload interface.

You can also navigate to your repository's main page and click the "Add file" button, then select "Upload files".

Uploading Files

The upload interface allows you to:

• Drag and drop files directly from your computer into the browser
• Click to browse and select files
• Upload multiple files at once by selecting them all

After selecting your files, GitHub shows them in a list with options to:

• Rename files before committing
• Remove files from the upload list

You can also create new files directly in the interface by clicking "Add file" and choosing "Create new file", then typing or pasting your code.

Committing Your Files

After uploading or creating your files, scroll down to the "Commit changes" section at the bottom of the page.

Here you'll see a field for a commit message. Write a descriptive message explaining what you're adding:

• "Add initial HTML and CSS files" ✓
• "Upload first website project" ✓
• "Initial commit: Add website files" ✓

Commit messages help you track what changed and when, so clear messages are valuable even for your first commit.

Once you've written your commit message, click the green "Commit changes" button. GitHub saves your files and creates the first commit in your repository's history.

Viewing Your Files

After the commit completes, you'll see your files listed in the repository. You can:

• Click on any file to view its contents
• See syntax highlighting that makes code easier to read
• Edit files directly through the web interface

For more detailed instructions, see GitHub's guide on adding files to a repository.

Verifying Your Repository

After uploading files, verify that everything is stored correctly. Navigate to your repository's main page by clicking the repository name or using the breadcrumb navigation at the top. You should see all your files listed in the file browser interface. Click on files to view their contents and confirm they display correctly.

Check that file paths are correct, especially if your HTML files link to CSS files or images. Relative paths should work correctly since the file structure in your repository matches how files will be served. If you have an index.html file, GitHub will automatically recognize it as the main page when viewing your repository, though this doesn't automatically publish it as a website - that requires enabling GitHub Pages, which is covered in a later guide.

Your repository now serves as both backup storage and a way to share your project with others. The repository URL can be shared with anyone, allowing them to view your code and download your files. Each time you make changes and commit them, those changes are permanently recorded in your repository's history, creating a complete record of your project's development.

Next Steps

With your repository created and files uploaded, you're ready to learn about making commits and managing changes. The next guide, "Making Your First Commit," explains how to save changes to your repository and write effective commit messages that document your project's evolution.

Bibliography

GitHub. "Creating a new repository." GitHub Docs. https://docs.github.com/en/get-started/quickstart/create-a-repo

GitHub. "Adding a file to a repository." GitHub Docs. https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository

Pro Git Book. "Git Basics - Getting a Git Repository." Pro Git. https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository

The Odin Project. "Introduction to Git." The Odin Project Curriculum. https://www.theodinproject.com/paths/foundations/courses/foundations