Project Files

Written & tested for accuracy by a developer (not AI) · Updated November 2026

What Is a README File?

What is a README file. It is the "start here" note in a project folder. What to put in README.md and how to read it on a Mac.

A README file tells you what a project is, how to set it up and run it, and where to get help. When you find one in a project folder, open it first.

Many people skip README files, and ignoring one usually never matters. But experienced developers open the README before anything else, because it is the fastest way to learn what a project does and how to start working with it. They also write one for every project of their own, so that they can find their way around the project again months later.

What's in a Project Folder? explains the other files and folders you'll find beside a README in a project. Finding your way around a project folder is one early thing to learn in Mac development.

What goes in a README

GitHub's page, About the repository README file, lists what a README usually covers:

  • What the project does - one or two sentences that say what it does.
  • Why it is useful - who would want it, and what it saves them.
  • How to get started - how to install it and run it.
  • Where to get help - a link, an email address, or a place to report problems.
  • Who maintains it - the people or company behind it.

A README for your own small project can be much shorter, with a few lines that say what it is and how to run it.

README.md, README.txt and README

The filename appears in capital letters (so it will stand out). The file extension tells you the format:

  • README.md - written in Markdown, a plain-text format that uses symbols such as # for a heading and ** for bold text. This is the most common kind today. GitHub displays it with formatting.
  • README.txt - plain text with no formatting.
  • README - plain text with no extension, common in older projects.

README example

Here's an example README.md for a small website project:

# Recipe Box

A small website for saving family recipes, built with plain HTML and CSS.

## How to run it

Open `index.html` in your web browser. Nothing needs to be installed.

## How to add a recipe

Copy `recipes/template.html`, give it a new name, and fill in the ingredients and steps.

## License

MIT License. See the `LICENSE` file.

The name comes first, as a heading, then one sentence that says what the project is. Each section answers a question a newcomer would ask. The last one names the license, which is in a separate license file.

How to open a README file on Mac

The quickest way to read a README is Quick Look. Select the file in the Finder and press Space. Quick Look shows README.md as plain text, so you'll see the Markdown symbols, such as # and **, along with the words. A README.txt, or a README with no extension, is already plain text.

To see a README.md with formatting, with real headings and bold text, open it in a Markdown editor. Markdown Editors for AI compares different kinds of Markdown editors, and also describes QLMarkdown, a free add-on that makes Quick Look show Markdown formatted.

Where GitHub shows a README

On GitHub, a project's README automatically appears as the project's first page. GitHub looks for one in three places, and shows the first it finds in this order:

  • the hidden .github folder
  • the project's top folder
  • the docs folder

Most projects keep the README in the top folder, where you'll see it in the Finder. The .github folder is hidden because its name starts with a dot. See the article Show Hidden Files on Mac to learn how to see it in the Finder.

README files and AI agents

A README says what the project is and how to run it, which is useful for both people and AI agents. Put instructions for an AI agent in a separate file, AGENTS.md (or CLAUDE.md for Anthropic Claude). Agent Instructions explains where it goes.

I recommend starting every project with a README, even a few lines long. When you work with Claude or ChatGPT Codex, ask the AI agent to write the README and to update it whenever the project changes. My Starter Projects article shows more from example projects in my "Set Up Your Mac" apps.

A README usually accompanies a license file and a changelog.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.