Himanshu SharmaSoftware engineer
Let’s talk

Git and GitHub · Lesson 16 of 30

GitHub repositories, README files and licences

Create a GitHub repository, connect it to a local one, write a useful Markdown README, and see why a licence file matters before others reuse your code.

13 minRemotes and GitHubUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonDescribe how to create a GitHub repository and connect your local project to it, write a good README, and explain why a licence matters.

What you can do after this lesson

You will know how a project goes from your laptop to a GitHub page, how to make that page useful with a README, and why a licence file is part of sharing code responsibly. The web steps are described in words, because they happen in a browser and their layout changes over time. Where we mention a button, treat the name as approximate and consult docs.github.com.

Creating a repository on GitHub

After signing in, you choose the option to create a new repository. The form asks for:

  • Owner: your account or an organisation you belong to.
  • Name: short, lowercase with hyphens works well, such as shelf-tracker. It becomes part of the URL.
  • Description: one sentence.
  • Visibility: public (anyone can see it) or private (only people you invite).
  • Starter files: GitHub can add a README, a .gitignore template and a licence file at creation.

If you already have a local project, create the repository empty, without starter files. Otherwise GitHub makes a first commit that your local repository does not have, and your first push is rejected like the rejected push in the remotes lesson. (It is fixable with a pull first, but avoidable.)

Connecting your local project

GitHub then shows the address of the new repository. In your local repository, add it as a remote and push:

bash
git remote add origin https://github.com/your-name/shelf-tracker.git
git push -u origin main

Those two lines need your real GitHub account and credentials, so no output is shown here. The command shape is the same one we ran against a local bare repository in the previous lessons, which is why practising with a local remote is a faithful rehearsal. After the push, refreshing the repository page shows your files and commit history.

If you start from the website instead, you clone the new repository, with git clone <url>, and work from the copy.

The README

GitHub shows the file named README.md (or similar) at the top level as the front page of the repository. .md means Markdown, a simple way to write headings and lists in plain text. A useful README answers five questions in under a minute:

  1. What is this? One or two sentences.
  2. Why would I use it? Who it is for.
  3. How do I run or install it? Exact steps a newcomer can follow.
  4. How do I use it? A short example.
  5. How do I contribute or get help? Where to open issues, any rules.

A compact example for a fictional project:

markdown
## Shelf Tracker

A small command line tool that lists the books you plan to read.

### Install

Clone the repository and run the script with PHP 8 or newer.

### Usage

Run `php shelf.php add "Dune"` to add a book.

### Contributing

Open an issue first to discuss large changes. Pull requests are welcome.

### Licence

See the LICENSE file.

Only claim what is true. Do not describe features that do not exist yet, and avoid invented statistics or testimonials.

Other files you will meet at the top level: LICENSE, .gitignore, CONTRIBUTING.md (how to help), CODE_OF_CONDUCT.md (how people should behave) and SECURITY.md (how to report a vulnerability privately). GitHub recognises these names and links to them.

Public, private and who can do what

A public repository can be read and cloned by anyone, though only people you grant access can push to it. A private repository is invisible to everyone else. Choose private for anything containing client details or unfinished work you are not ready to share. Remember the lesson from .gitignore: privacy is not a substitute for keeping secrets out of the repository, because access settings change and people copy repositories.

You can invite collaborators with write access. Within an organisation, finer roles exist such as read, triage, write and admin. To control a branch such as main, repositories offer branch protection rules, which can require a pull request and passing checks before changes land. We return to this in the lessons on pull requests and workflows.

Choosing a licence

Here is the part many people skip. If you publish code with no licence, the default under copyright law in most places is that you keep all rights, which means others are not clearly allowed to copy, modify or redistribute it, even though they can read it on GitHub. A licence is the statement that grants those permissions, with conditions.

Some well-known examples (described very briefly, since the exact wording matters):

  • MIT: very permissive. People may reuse the code, including in commercial products, if they keep your copyright and licence notice.
  • Apache 2.0: permissive, with an explicit patent grant and requirements to state changes.
  • GPL family: reuse is allowed, but distributed derivative works must also be released under the same kind of licence.
  • Creative Commons: designed for creative content, not typically for software.

GitHub lets you add a licence file from a list of templates when creating the repository, and its documentation on licensing repositories explains the options (check the current wording; not verified for this lesson). This is general information, not legal advice. If a licence matters commercially, for instance because a company will use your code, read the full text and consider professional advice. Also check the licence of anything you copy into your project, since you inherit its conditions. Contributions from others come under whatever your project's terms say, which is one reason bigger projects write contributor policies.

Common mistakes

  • Creating the GitHub repository with starter files when you already have a local history. It leads to an immediate rejected push.
  • A README that says nothing. A title and nothing else gives visitors no reason to stay.
  • No licence on code you want others to use. Without one, their permission is unclear.
  • Believing private means safe for secrets. Keep secrets out entirely.
  • Copying code from elsewhere without checking its licence. The conditions come with it.

Exercise

  1. Pick a small project of yours and write a README for it with the five answers above, each in one or two sentences.
  2. Decide whether it should be public or private and give your reasoning.
  3. Decide which licence family fits your intent and write down what you want others to be allowed to do.
Show one possible answer

A README with sections "What is this", "Install", "Usage" and "Contributing" is enough. For visibility, a personal learning project with no secrets can be public so that others can learn from it, while a draft containing a client's data should be private. If you want anyone to reuse the code freely with credit, a permissive licence such as MIT matches that intent; if you want improvements to stay open, a GPL-family licence does. Confirm the actual text before publishing.

Next: Issues and pull requests on GitHub.

Key points

  • Creating a repository on GitHub gives you an empty remote; you add it as origin to a local repository and push.
  • A README.md at the top of the repository is shown on its front page and should say what the project is, how to use it and how to contribute.
  • Public means anyone can read; private means only people you invite.
  • Without a licence file, others have no stated permission to reuse your code, so choose a licence deliberately.
  • Licences are legal documents; read the text or ask a professional if it matters, because this lesson is general information only.

Check yourself

1. You have a local repository and a new empty GitHub repository. What connects them?
2. What is a README for?
3. A public repository has no licence file. What is the safest assumption for someone who wants to reuse the code?
4. Which Markdown line creates a second-level heading in a README?