Opening a repository for the first time can feel like walking into someone else's workshop. There are folders, files with odd names, buttons for things you didn't ask for, and a star count you're not sure how to read. Most people click around for a minute, find nothing that explains the project, and leave.

A repository is the home of one project on GitHub. It holds the project's files and the complete history of every change made to them. The repository page puts the most useful parts up front: the current files, the latest change to each one, and a README that explains what the project is for and how to use it. A few other files carry quiet but important jobs, from setting the rules for reuse to telling contributors how to help. Settings decide whether the whole world can see the repository or only the people invited to it. Popular repositories also show stars and forks, which hint at how widely a project is used.

You don't need to understand every file to find your way around. Knowing where a repository explains itself is enough to judge what it is, who maintains it, and whether it's safe to build on. A clear README and a tidy file list are good signs that a project is well looked after.

Repository contents and history

A repository, often shortened to repo, is the home of one project. It holds the project's files and folders, and next to them, the complete history of every change ever saved. That history is what separates a repository from an ordinary shared folder.

On a computer, the history lives in a hidden .git folder inside the project. On GitHub, the same repository gains a public face: a page that shows the current files, a timeline of changes, and the conversations around them, such as issues and pull requests.

For the bakery website, the repository might hold an index.html page, a style.css file, and an images folder of cupcake photos. Every edit to any of them, from a fixed typo to a new menu page, is recorded with its author, date, and message.

Anatomy of the repository page

Anatomy of the repository page

Every repository on GitHub opens on the same layout. Across the top sit the owner and repository name, a visibility badge such as Private, and tabs for Code, Issues, Pull requests, and more.

The Code tab shows, from top to bottom:

  • A branch menu, set to main by default, that decides which version of the files is shown
  • The latest commit, with its author, message, and the total number of commits
  • The file list, where each file shows the message and date of the last change to it
  • The rendered README, the project's front page

A sidebar called About adds a short description, topic tags, and counts of stars, watchers, and forks. Once this layout is familiar, any repository on GitHub can be read in seconds, whether it holds a website, a design system, or documentation.

README files that orient newcomers

README files that orient newcomers Best Practice
Do
README files that orient newcomers Bad Practice
Don't

A README is a file named README.md at the top of a repository. GitHub renders it below the file list, so it's usually the first thing a visitor reads. A good README answers a few questions straight away: what the project does, why it's useful, how to get started, where to get help, and who maintains it [1].

A weak README says almost nothing. A single line like This is the repository for the upcoming website tells a newcomer the project exists, but not what to open first or whom to ask. Each person who joins then has to interrupt someone to find out.

Writing a useful README takes a few minutes and saves hours later. Because it's written in Markdown, it can use headings, lists, and links to keep the information easy to scan.

Pro Tip! Write the README for someone joining six months from now with nobody to ask. That reader is often a future teammate, or a future self.

LICENSE, CONTRIBUTING, and SECURITY files

Beyond the README, a few files with capitalized names carry special meaning on GitHub, which links to them automatically:

  • LICENSE sets the rules for reusing the code. Without one, default copyright applies, so others can see a public project but have no right to copy or change it [2]
  • CONTRIBUTING explains how to propose changes, and GitHub points to it when someone opens an issue or pull request
  • SECURITY tells people how to report a vulnerability privately rather than in public
  • CODEOWNERS names the people who are asked to review changes to certain files

These files turn unwritten habits into clear expectations. For a small team, a short CONTRIBUTING file and a license are often enough to make a repository easy to join and safe to share.

The default branch: main

Every repository has a default branch: the version GitHub shows first and the one new changes are usually merged into. On new repositories, it's called main.

Older repositories may use master instead. GitHub switched the default name for new repositories to main in October 2020 [3], and many existing projects renamed theirs to match. Both names work the same way. Only the label differs.

The name still matters in practice. Tools, scripts, and AI builders often assume the main branch is called main, so a repository that still uses master can trigger confusing errors like cannot find main. Knowing which name a repository uses is the first step in fixing that.

Public vs. private repositories

Public vs. private repositories

A repository's visibility decides who can see it. A public repository is visible to anyone on the internet, including its files and full history, and anyone can copy it. A private repository is visible only to its owner and the people invited to it [4].

Public repositories suit open-source projects, portfolios, and documentation meant for everyone. Private repositories suit client work, unreleased products, and anything with internal details. Organizations on some plans also offer internal visibility, which opens a repository to everyone in the company but no one outside it.

Visibility can be changed later in the repository's settings, but the change is bigger than it looks. Making a private repository public exposes everything in it at once, including every past version of every file.

Pro Tip! Before going public, check old commits. A password or key removed months ago is still in the history and becomes visible to everyone.

Stars, forks, and watchers

Stars, forks, and watchers

Public repositories on GitHub show three counters near the top of the page. Each one means something different:

  • Stars work like bookmarks. People star a repository to save it or to show appreciation, so a high count signals popularity
  • Watchers have asked to be notified about activity, such as new issues and releases
  • Forks are copies other people have made under their own accounts, usually to build on the project or propose changes

Together, these numbers hint at how widely a project is used and how active its community is. They're signals, not guarantees. A repository with thousands of stars can still be outdated, so the date of the latest commit is worth checking too.

Creating a repository on GitHub

A new repository takes about a minute to create. The New repository form asks for an owner, a name, an optional description, and a visibility setting. Short, lowercase names with hyphens, like bakery-website, are easiest to share and type.

The form also offers to add starter files:

  • A README, which gives the repository a front page and its very first commit
  • A .gitignore template, which keeps files like system clutter out of the history
  • A license, which sets the rules for reuse

Adding a README at creation is a good habit. A repository with no commits is technically empty, and some tools, including certain AI builders, can't connect to it until it holds at least one.