First steps

1 · Create your account

Sign up at github.com/signup. Two decisions are worth thirty seconds of thought:

• Your username is public and semi-permanent. It appears in every repository URL you own and in every commit you're credited for. Pick something you'd be comfortable putting on a CV — plenty of people regret xX_dragonslayer_Xx.
• Turn on two-factor authentication immediately. GitHub requires it for most accounts now anyway. An authenticator app is the sensible choice; save the recovery codes somewhere that isn't your laptop.

2 · Install and configure Git

Git is separate software from your GitHub account. Check whether you already have it:

$ git --version
git version 2.45.2

If that prints a version, you're done — skip to the configuration below. If it says command not found:

Tell Git who you are

Git stamps every commit with a name and email. Set them once, globally, before you do anything else — otherwise your first commits will be attributed to nobody, and fixing that after the fact is a nuisance.

$ git config --global user.name "Ada Lovelace"
$ git config --global user.email "ada@example.com"

# name new projects' first branch "main" rather than "master"
$ git config --global init.defaultBranch main

# check it took
$ git config --global --list

3 · Connect your machine to GitHub

This is the step tutorials skip, and it's where most people get stuck. Your laptop needs to prove it's allowed to push to your account. Your GitHub password will not work — that's been disabled for Git operations since 2021.

Pick one of these. You only need one, and you only do it once per machine.

Option A — the gh CLI

Install it from cli.github.com (or brew install gh, winget install GitHub.cli), then:

$ gh auth login
? What account do you want to log into?  GitHub.com
? What is your preferred protocol for Git operations?  HTTPS
? Authenticate Git with your GitHub credentials?  Yes
! First copy your one-time code: A1B2-C3D4
✓ Logged in as adalovelace

That's it — Git will now authenticate automatically. The tool is useful for plenty more besides; see Level up.

Option B — an SSH key

Generate a key, add it to your agent, then paste the public half into GitHub.

$ ssh-keygen -t ed25519 -C "ada@example.com"
Enter file in which to save the key: ← press Enter for the default
Enter passphrase: ← optional but sensible

$ cat ~/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... ada@example.com

Copy that entire line, then go to GitHub → Settings → SSH and GPG keys → New SSH key and paste it in. Verify it worked:

$ ssh -T git@github.com
Hi adalovelace! You've successfully authenticated, but GitHub does not
provide shell access.

4 · Make your first repository

There are two directions you can come at this from, and it's worth knowing both exist because you'll hit each of them in real life.

1. Create it on GitHub

   Click the + in the top right → New repository. Name it hello-github. Tick Add a README file — this matters, because a repo with no commits in it behaves slightly differently and confuses beginners. Leave it Public or set it Private, your call.

2. Copy the clone URL

   On the new repo's page, the green Code button gives you a URL. Choose the tab matching how you authenticated in step 3 — SSH if you made a key, HTTPS if you used gh.

3. Clone it

   Move to wherever you keep projects, then pull down a copy:

   clone

   $ cd ~/projects
   $ git clone git@github.com:adalovelace/hello-github.git
   Cloning into 'hello-github'...
   remote: Enumerating objects: 3, done.
   Receiving objects: 100% (3/3), done.
   
   $ cd hello-github
   

   You now have a folder that is aware of its counterpart on GitHub. Cloning downloads the entire history, not just the current files — which is why you can browse the whole past of a project on a plane.

$ git init
$ git add .
$ git commit -m "Initial commit"
$ git remote add origin git@github.com:adalovelace/my-project.git
$ git push -u origin main

5 · Your first commit and push

Now the actual loop. Open README.md in any editor and add a line or two about what the project is.

1. Ask Git what it sees

   git status is the single most useful command in Git. Run it constantly. It tells you where you are, what's changed, and usually what to type next.

   git status

   $ git status
   On branch main
   Changes not staged for commit:
     (use "git add <file>..." to update what will be committed)
           modified:   README.md
   
   no changes added to commit
   

2. Stage the change

   Staging is you saying "this file belongs in my next snapshot".

   git add

   $ git add README.md
   

   Run git status again and the file has moved to Changes to be committed, in green. Nothing is saved yet — staging is a waiting room.

3. Commit it

   This is the actual save. The message is not a formality; it's what you or a colleague will read in eighteen months trying to work out why a line exists.

   git commit

   $ git commit -m "Describe the project in the README"
   [main 7c3f1a9] Describe the project in the README
    1 file changed, 3 insertions(+)
   

   7c3f1a9 is the start of the commit's unique ID. You'll use short IDs like that to refer to specific commits later.

4. Push it to GitHub

   Your commit exists only on your laptop until you do this.

   git push

   $ git push
   Enumerating objects: 5, done.
   To github.com:adalovelace/hello-github.git
      4b2c1e0..7c3f1a9  main -> main
   

   Refresh the repo page in your browser. Your change is there, your message is on it, and your avatar is next to it. That's the entire fundamental cycle — edit → add → commit → push — and everything else in this guide is a variation on it.

6 · What belongs in a repo

Three files show up in nearly every project. None are required, all are conventions worth following.

Getting .gitignore right early

Create a file called .gitignore at the top of the repo. Each line is a pattern Git will skip:

# secrets — never, ever commit these
.env
*.pem
credentials.json

# dependencies — reinstallable, and enormous
node_modules/
venv/

# build output
dist/
*.log

# OS noise
.DS_Store
Thumbs.db

GitHub offers ready-made .gitignore templates for most languages when you create a repo, and maintains a collection of them. Start from one rather than writing your own.

7 · The browser-only route

You can do a surprising amount without ever opening a terminal. This is a legitimate way to work — plenty of people edit documentation this way for years.

The limits you'll eventually hit: you can't run or test anything, and handling a complicated merge conflict in the web editor is unpleasant. But for a typo fix, a README update, or reviewing someone's work, the browser is often genuinely faster than cloning.

If you want a middle path — buttons instead of commands, but running on your own machine so you can test things — GitHub Desktop is free and maps closely to the concepts on this site.