Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 36 ยท Repositories and Collaboration

README, License and .gitignore

Write a useful README, choose an open-source license, add a .gitignore, and include community health files so visitors can understand, trust and contribute to your project.

A repository with code but no explanation is hard to use, and a repository with no license is legally off limits to most people. Three small files fix most first impressions: the README says what the project is, the license says what others may do with it, and the .gitignore keeps junk out of history. GitHub also recognizes a handful of other community files and shows them in useful places.

The README

GitHub renders README.md on the repository home page (and in any folder that has one). It is written in Markdown. A good README answers, in this order:

  1. What is this? One or two sentences, no jargon.
  2. Why would I use it? Features or a screenshot or short demo.
  3. How do I install and run it? Copy-pasteable commands.
  4. How do I use it? A minimal example.
  5. How do I contribute and who maintains it? Link to CONTRIBUTING.md, say where to ask questions.
  6. License. One line pointing to the LICENSE file.
MARKDOWN
# weather-cli

Print the weather for any city from your terminal.

## Install

    npm install --global weather-cli

## Use

    weather "Lisbon"

## Contributing

Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT. See [LICENSE](LICENSE).

GitHub generates a table of contents from headings (the list icon at the top of the rendered file) and supports task lists, tables, fenced code blocks with syntax highlighting, relative links and images, and Mermaid diagrams inside a mermaid fence. Relative links such as [docs](docs/usage.md) keep working in forks and branches, so prefer them over absolute URLs.

Where GitHub looks for a README: the root of the repository, docs/, or a special .github/ folder, in that priority order (the .github location wins). If you have an organization, a public .github repository can hold default community files for all its repositories.

Choosing a license

Without a license, the default is "all rights reserved": people can view your code on GitHub but may not copy, modify or distribute it. If you want others to use it, add a license file named LICENSE or LICENSE.md. On the website, Add file > Create new file, type LICENSE, and GitHub shows a Choose a license template button. The most common choices:

License In one sentence
MIT Do almost anything, keep the copyright notice. Very permissive.
Apache 2.0 Like MIT, plus an explicit patent grant and notice rules.
BSD 3-Clause Permissive, adds a clause against using your name to endorse derived products.
GPL 3.0 Anyone who distributes a modified version must release it under the GPL too (copyleft).
MPL 2.0 File-level copyleft: changes to MPL files stay open, the rest of a project need not.
Unlicense / CC0 Dedicate the work to the public domain as far as the law allows.

This is general information, not legal advice. If a company or serious commercial use is involved, have someone qualified read the terms. Also note that you can only license what you own: do not add a license to code you copied from somewhere with different terms. GitHub detects the license and displays it in the sidebar.

The .gitignore file

.gitignore lists patterns of files Git should not track: dependencies, build output, editor settings and, above all, secrets. It only affects untracked files. If you already committed a file, ignoring it later does not remove it from the repository; run git rm --cached <file> first.

GITIGNORE
# dependencies
node_modules/

# build output
dist/
*.log

# secrets and local config
.env
.env.*
!.env.example

# OS and editor files
.DS_Store
.vscode/

Pattern rules worth remembering:

  • A trailing / matches directories only; * matches any characters except /; **/ matches in any directory.
  • A leading ! re-includes something an earlier rule excluded (the file's parent directory must not itself be ignored).
  • A pattern with a slash in the middle is anchored to the folder containing the .gitignore.
JS Stand-in: a mini .gitignore matcher

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Real Git has more rules (anchoring, **, escapes), but the last-match-wins behavior shown here is exactly how negation works. GitHub's gitignore template collection (offered when you create a repository) covers most languages; you can also keep a personal list in ~/.config/git/ignore for editor files that are only your business.

Community health files

Files in the root, docs/ or .github/ that GitHub recognizes:

File Purpose
CONTRIBUTING.md How to propose changes; GitHub links to it when someone opens an issue or pull request
CODE_OF_CONDUCT.md Expected behavior in the community
SECURITY.md How to report vulnerabilities privately
SUPPORT.md Where to get help
CITATION.cff Adds a "Cite this repository" button
FUNDING.yml (in .github/) Shows a Sponsor button

The repository Insights > Community Standards page shows which of these you have and which are missing.

JS Stand-in: community checklist

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A repository has no license file. What is the default legal situation?

    Without an explicit license, copyright law applies and reuse is not permitted.
  2. 2. You committed .env by mistake and then added it to .gitignore. What happens?

    Ignoring only affects untracked files. Tracked files stay tracked.
  3. 3. Which license requires modified versions that you distribute to be released under the same license?

    The GPL is a strong copyleft license.
  4. 4. Which README link style keeps working in forks and other branches?

    Relative links resolve against the current branch or fork.

Summary

  • The README explains what, why, how to install, how to use, and how to contribute.
  • Add a license; no license means nobody else may legally reuse your code.
  • .gitignore keeps dependencies, builds and secrets out; it does not untrack files already committed.
  • Community files such as CONTRIBUTING, CODE_OF_CONDUCT and SECURITY are recognized and surfaced by GitHub.

Next: Branches on GitHub