Learning Center Guides GitHub Tutorial for Newbies: Creating a New Repo and Pushing Changes

GitHub Tutorial for Newbies: Creating a New Repo and Pushing Changes

May 13 2022


This guide is for folks who are new to using GitHub and git, and also perhaps new to terminal usage (bash or zsh) in general.

This guide is up-to-date with changes made to GitHub authentication in 2021 and 2022.

Most Common Troubleshooting: Are you dealing with the remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead. error? See the section Creating an "personal access token" to use as a password at the bottom of this tutorial.


Prerequisite skills: You should be able to open a terminal running Bash (Linux, Windows, old macOS) or Zsh (recent macOS), and be familiar with basic commands, such as ls and cd. You should be familiar with editing code files using a text editor, such as writing HTML files using VS Code. You should be familiar with at least the terminology of basic git concepts: repository or "repo" for short (a directory that you are using git to track changes with and may be shared with other git users), a "commit" (a "savepoint") and so on.

Prerequisite computer setup & accounts: 1) Sign-up for a GitHub account and log-in, if you haven't already, and 2) install & configure Git for your platform (Ubuntu Linux, use sudo apt install git, macOS, install brew and then run brew install git, and for Windows, install "git-bash")

Creating a new repo on GitHub

Step 1: Go to the plus & select new repo

In this tutorial, we'll start by making the repo first on GitHub, since this typically requires the fewest steps.

Click on the plus in the upper-right corner of the screen, and select new "repo" to be taken to the new repo screen.

Creating a new repo gif

Step 2: Fill in details

Type in a name and details for your repository, and make it public.

Filing in details of testing repo GIF

Step 3: Check "create with README.md" & create

We'll start with a README.md file, to make it easier to confirm the repository was made when we clone it locally, and so that GitHub fully sets-up the repo on their end.

Checking the README and finishing creating GIF

Cloning GitHub repo to local

Step 1: Copy the URL

Click the green "CODE" button and copy the URL

Step 2: Paste URL in a git clone command

Open up a new terminal, and find a good location for your code. Type in "git clone" followed by a space, and then paste in the URL.

Step 3: Change into new directory and confirm success

Git will create a new directory with the name of your repo. In the GIF demo below, which covers all 3 steps above, that will be testingrepo. In that case, we'll want to do a cd testingrepo/ (or whatever you called your repo), and then do a ls to confirm the README.md that GitHub generated is indeed copied locally. Finally, we'll want to do a git status to ensure it is connected to GitHub as expected.

(Steps 1, 2 and 3 below:)

Cloning locally GIF

Making changes and pushing up

Step 1: Making a change

It's up to you how you want to add files or make changes. You can use an editor (e.g. VS Code) to create a new file in that directory, such as an "index.html" file. You could also delete / move / rename / copy files within your graphical file-browser.

Tip: You can use git status to verify that you succesfully made a change. Note how in this example it shows it as an "untracked" file. This means you haven't told git that this change was deliberate and one that you want to track. That's the next step.

  • Troubleshooting Step 1: Make sure you are in the same directory, both with the change you make and when you run the command.

Step 2: Add & commit the change

Once you've made a change, it's time to add it to the "staging area" of the repo with git add -A, and then commit it, with git commit -m "any notes". Note the value of git status before and after each of these commands. The git status command gives you a clue of what status your repo is in, and what you need to do next.

  • Troubleshooting Step 2: Make sure you use the -m "message" part of the commit command. If you do not, it will likely put you into a difficult text editor (either nano, for Linux, or vi for macOS). While nano is somewhat usable (read the help at the bottom, the ^ symbl means the Ctrl key, e.g. the ^X help at the bottom means Ctrl+X exits), the macOS default vi is very hard for beginners (e.g. Escape followed by :q! followed by Enter to exit). Unless you like hard editors like these, then just use the -m argument to avoid it!

Step 3: Push the change up

Now that you have a "commit" locally (that is, the current contents of your files have been saved into the .git/ directory), you will need to push upward. This can be done with the git push command.

  • Troubleshooting Step 3: Did it just ask for a password? Use a personal access token instead. Look at "Creating an auth token to use as a password" below to know what to do next.

(Steps 1, 2 and 3 below:)

Making a change, adding, committing and pushing

Optional: Making another change and pushing up

Now, if you want to share any changes or additions you make on GitHub, you'll want to repeat Steps 1-3: Make a change, then run git add -A and git commit -m "message goes here", followed by git push

Repeating the previous: Making a change, adding, committing and pushing

Creating an "personal access token" to use as a password

Without an SSH key set-up, it will show something like this instead:

$ git push
Username for 'https://github.com': michaelpb
Password for 'https://[email protected]': 
remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead.
remote: Please see https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ for more information.
fatal: Authentication failed for 'https://github.com/michaelpb/testingrepo.git/'

In this situation, the quickest way to push is to generate a "personal access token" (basically, a randomly generated password) instead of the password that you used when you created your GitHub account.

Step 1: Getting to "Generate a new access token"

Click on your profile, then click on Settings, then click on Developer settings, then click on Personal access tokens then click on the button that says Generate an access token, then enter your password, and you will be at the access token generation form

Getting to generate a new auth token

Step 2: Fill in details, and paste in token

Finally, check the box next to repo to enable repo access, optionally set an expiration date and add a note to yourself (description), and then paste in the password. Note that there is no way to ever recover this password again if you do not save it, meaning you should delete old ones and generate a new one if you ever lose it!

Pasting in new auth token

Important: Make sure to check the "repo" box when creating a new auth token! Otherwise, you'll get a 403 error when you try to use it.

Consider saving a personal access token somewhere safe, such as a password manager. Or, you can always just generate a new one every time, although that can be tedious.

In the long run, you'll want to set-up SSH key based authentication. However, for beginning coding school students, generating a personal access token might be enough!

Michael Bethencourt

Michael is a software developer and instructor. His favorite teaching challenge is teaching big computer science concepts to total newbies. He believes that complex concepts don't need to be complicated! His favorite engineering approach is full stack thinking: recognizing complexity that can be shifted between low-level infrastructure and JavaScript, or vice-versa. When he's not coding, he's probably doing political work, playing video games that feel too much like work, and counting down the days until first contact.