Quickstart for repositories

Learn how to create a new repository and commit your first change in 5 minutes.

Tool navigation

In this article

Create a repository

GitHub repositories store a variety of projects. In this guide, you'll create a repository and commit your first change.

  1. In the upper-right corner of any page, select , then click New repository.

    Screenshot of a GitHub dropdown menu showing options to create new items. The menu item "New repository" is outlined in dark orange.

  2. Type a short, memorable name for your repository. For example, "hello-world".

    Screenshot of the first step in creating a GitHub repository. The "Repository name" field contains the text "hello-world" and is outlined in dark orange.

  3. Optionally, add a description of your repository. For example, "My first repository on GitHub."

  4. Choose a repository visibility. For more information, see About repositories.

  5. Select Initialize this repository with a README.

  6. Click Create repository.

Congratulations! You've successfully created your first repository, and initialized it with a README file.

Note

To learn more about GitHub CLI, see "About GitHub CLI."

  1. In the command line, navigate to the directory where you would like to create a local clone of your new project.
  2. To create a repository for your project, use the gh repo create subcommand. When prompted, select Create a new repository on GitHub from scratch and enter the name of your new project. If you want your project to belong to an organization instead of to your personal account, specify the organization name and project name with organization-name/project-name.
  3. Follow the interactive prompts. To clone the repository locally, confirm yes when asked if you would like to clone the remote project directory.
  4. Alternatively, to skip the prompts supply the repository name and a visibility flag (--public, --private, or --internal). For example, gh repo create project-name --public. To clone the repository locally, pass the --clone flag. For more information about possible arguments, see the GitHub CLI manual.

Commit your first change

A commit is like a snapshot of all the files in your project at a particular point in time.

When you created your new repository, you initialized it with a README file. README files are a great place to describe your project in more detail, or add some documentation such as how to install or use your project. The contents of your README file are automatically shown on the front page of your repository.

Let's commit a change to the README file.

  1. In your repository's list of files, select README.md.

    Screenshot of a list of files in a repository. A file name, "README.md", is highlighted with an orange outline.

  2. In the upper right corner of the file view, click to open the file editor.

    Screenshot of a file. In the header, a button, labeled with a pencil icon, is outlined in dark orange.

  3. In the text box, type some information about yourself.

  4. Above the new content, click Preview.

    Screenshot of a file in edit mode. Above the file's contents, a tab labeled "Preview" is outlined in dark orange.

  5. Review the changes you made to the file. If you select Show diff, you will see the new content in green.

    Screenshot of the "Preview" view for a file. A checkbox labeled "Show diff" is selected, and an addition to the file is indicated by a green line marker. Both are outlined in orange.

  6. Click Commit changes...

  7. In the "Commit message" field, type a short, meaningful commit message that describes the change you made to the file. You can attribute the commit to more than one author in the commit message. For more information, see Creating a commit with multiple authors.

  8. Below the commit message fields, decide whether to add your commit to the current branch or to a new branch. If your current branch is the default branch, you should choose to create a new branch for your commit and then create a pull request. For more information, see Creating a pull request.

    Screenshot of a GitHub pull request showing a radio button to commit directly to the main branch or to create a new branch. New branch is selected.

  9. Click Commit changes or Propose changes.

Now that you have created a project, you can start committing changes.

README files are a great place to describe your project in more detail, or add some documentation such as how to install or use your project. The contents of your README file are automatically shown on the front page of your repository. Follow these steps to add a README file.

  1. In the command line, navigate to the root directory of your new project. (This directory was created when you ran the gh repo create command.)

  2. Create a README file with some information about the project.

    echo "info about this project" >> README.md

  3. Enter git status. You will see that you have an untracked README.md file.

    $ git status

Untracked files:
  (use "git add <file>..." to include in what will be committed)
  README.md

nothing added to commit but untracked files present (use "git add" to track)

  4. Stage and commit the file.

    git add README.md && git commit -m "Add README"

  5. Push the changes to your branch.

    git push --set-upstream origin HEAD

Next steps

You have now created a repository, including a README file, and created your first commit on GitHub.

  • You can now clone a GitHub repository to create a local copy on your computer. From your local repository you can commit, and create a pull request to update the changes in the upstream repository. For more information, see Cloning a repository and Set up Git.

  • You can find interesting projects and repositories on GitHub and make changes to them by creating a fork of the repository. Forking a repository will allow you to make changes to another repository without affecting the original. For more information, see "Fork a repository."

  • Each repository on GitHub is owned by a person or an organization. You can interact with the people, repositories, and organizations by connecting and following them on GitHub. For more information, see "Finding inspiration on GitHub."

  • GitHub has a great support community where you can ask for help and talk to people from around the world. Join the conversation on GitHub Community.