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
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")
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.
Type in a name and details for your repository, and make it public.
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.
Click the green "CODE" button and copy the URL
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.
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:)
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.
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.
-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
vifor macOS). While
nanois somewhat usable (read the help at the bottom, the
^symbl means the Ctrl key, e.g. the
^Xhelp at the bottom means Ctrl+X exits), the macOS default
viis 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
-margument to avoid it!
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.
(Steps 1, 2 and 3 below:)
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
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.
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
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!
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!