READMEs and project hygiene

Why it matters

The README is the front page of a repository. Recruiters, teammates and your future self decide in seconds whether a project is understandable and usable. A .gitignore file keeps the repository clean by stopping clutter (system files, dependencies, build output) and, more importantly, secrets from being committed. Together they are the difference between a pile of files and a professional project.

The README

GitHub shows README.md below the file list. It is written in Markdown:

# Project title

**Bold**, *italic*, `inline code`, [a link](https://example.com)

## A section
- a bullet
1. a numbered step

Fenced code blocks use three backticks with a language name, which GitHub colours.

What to include

1. Title and one-sentence description: what it is and who it is for.
2. Why it exists or what problem it solves.
3. Getting started: prerequisites and install steps, as copyable commands.
4. Usage: a short example of running it and what the output looks like. A screenshot helps for visual projects.
5. Project structure (optional): what the main folders hold.
6. Contributing: how to report issues or open PRs.
7. License: what others may do with it.
8. Contact or credits.

Small projects can be short, but everyone needs at least 1, 3 and 4.

Worked example

# unit-converter

A tiny command-line tool that converts lab measurements between metric and US units.

## Getting started
Requires Python 3.10 or newer.

```bash
git clone https://github.com/<you>/unit-converter.git
cd unit-converter
python3 convert.py --help
```

## Usage
```bash
python3 convert.py 12.5 psi kPa
# 86.18 kPa
```

## License
MIT. See LICENSE.

Test your own instructions: clone the repo into a fresh folder and follow the README exactly. If a step is missing, you will find out.

The .gitignore file

A text file named .gitignore in the repository root. Each line is a pattern of paths Git should not track:

# operating system clutter
.DS_Store
Thumbs.db

# dependencies and build output
node_modules/
__pycache__/
dist/
build/

# logs and local data
*.log
data/raw/

# secrets and local settings
.env
*.pem

• # starts a comment.
• A trailing / matches folders.
• * is a wildcard: *.log ignores every log file.
• ! re-includes something: !keep.log.

Commit the .gitignore itself so everyone shares the rules. GitHub's template collection (github.com/github/gitignore) has ready-made files for Python, Node, Unity, Java and more, and you can pick one when creating a repository.

Check why a file is ignored with git check-ignore -v path/to/file.

Already-tracked files

.gitignore only affects untracked files. If you already committed debug.log, adding *.log does not remove it. Stop tracking it (but keep it on disk) with:

$ git rm --cached debug.log
$ git commit -m "Stop tracking debug.log"

Secrets

If a password, API key or token is ever committed and pushed, assume it is compromised: revoke it and create a new one at the provider. Deleting it in a later commit does not remove it from history. Prevent this by keeping secrets in .env (ignored) and committing a .env.example with placeholder values so others know which settings exist.

Other hygiene

• LICENSE: without one, others have no clear permission to reuse your code. choosealicense.com explains common options (MIT, Apache 2.0, GPL).
• Descriptive repository name and About text on GitHub, with a few topic tags.
• Small, clearly messaged commits (lesson 2 of module 2) make the history readable too.
• Do not commit large datasets or binaries; link to where they can be downloaded instead.

Common mistakes

• A README that is only the title, or a template left unchanged.
• Install steps that worked only on your machine.
• Adding .gitignore after committing node_modules/ or .env, and assuming that fixed it.
• Ignoring files the project needs to run (for example a small sample data file).

Quick recap

• README: what it is, how to install, how to use, license. Test the steps from a fresh clone.
• .gitignore: patterns for OS files, dependencies, build output, logs and secrets; commit it.
• git rm --cached stops tracking an already committed file; leaked secrets must be revoked.

Try it

Open the Do tab to give your repository a proper README and .gitignore.