Part 1 of 5 · Beginner's Handbook

Git Basics

This part covers Git running solo on your own machine — installing it, saving snapshots of your work, and undoing mistakes. Every command below is in a terminal box you can copy with one click — open your own terminal alongside this page and type along as you read. Once you're comfortable here, move on to GitHub Essentials to start pushing real projects online.

01 What is Git & GitHub?

Git is a tool that tracks changes in your code over time. Think of it like a save history for your project — you can go back to any previous version whenever you want. It works entirely on your own computer, no internet needed.

Example: you write code, something breaks, and you have no idea what you changed. With Git you can just roll back to the last working version.

GitHub is a website that stores your Git projects online. It lets you back up your code, share it with others, and collaborate without things getting messy.

Simple way to think about it — Git is the tool on your PC, GitHub is like Google Drive but for your code.

02 Key Concepts to Know First

Before running any commands, understand these words. You will see them everywhere:

  • Repository (Repo) — A folder that Git is tracking. It has a hidden .git folder inside that stores all the history.
  • Commit — A saved snapshot of your project at a point in time. Like taking a photo of your code. You can always go back to any photo.
  • Staging Area — Before you commit, you stage files. This means you pick which changes to include in the next snapshot. git add moves files here.
  • Branch — A separate copy of your project where you can work without affecting the main code. Great for trying new features safely.
  • Main / Master — The default branch. This is usually your official working version.
  • Remote — The version of your repo that lives online on GitHub. Your local copy talks to it using push and pull.
  • Push / Pull — Push means upload your local changes to GitHub. Pull means download the latest changes from GitHub to your PC.
  • Clone — Downloading a full copy of a repo from GitHub to your computer for the first time.

The Git workflow at a glance

Your code moves through four stages. This is the mental model to keep in your head for everything that follows:

Working Directory Staging Area Local Repository Remote (GitHub) add commit push pull / fetch you edit files changes picked snapshot saved shared online

03 Installation

Windows / Mac

  • Go to git-scm.com/downloads and download Git for your OS.
  • Run the installer. Just keep all the default settings and click Next through everything (except if you see "master" — change it to "main" if it isn't already the default).
  • Open your terminal (Git Bash on Windows, Terminal on Mac) and verify it worked:
    terminal
    $git --version
    git version 2.44.0

    If it prints a version number, you're good to go.

Linux

  • Git usually isn't installed by default, but it's one command to get it. Run the one for your distro:
    terminal
    # Ubuntu / Debian
    $sudo apt update && sudo apt install git
    # Fedora
    $sudo dnf install git
    # Arch / Manjaro
    $sudo pacman -S git
  • It will ask for your password. Type it and press Enter, then wait for it to finish.
  • Verify it worked:
    terminal
    $git --version
  • On Linux you'll also want an SSH key so you can push to GitHub without typing your password every time:
    terminal
    $ssh-keygen -t ed25519 -C "youremail@example.com"
    $cat ~/.ssh/id_ed25519.pub

    Press Enter through the key-generation prompts to accept the defaults. Copy the output of the second command, then go to GitHub → Settings → SSH and GPG keys → New SSH key, and paste it in.

All platforms

  • Create a GitHub account at github.com — it's free. Use the same email you'll use for setup in the next section.

04 First Time Setup

You only need to do this once per device. This tells Git who you are, so your commits show your name.

terminal
$git config --global user.name "Your Name"
$git config --global user.email "youremail@example.com"
$git config --global init.defaultBranch main
  • Use the same email as your GitHub account for user.email. This links your commits to your GitHub profile and counts your contributions.
  • Older versions of Git use "master" as the default branch name — the last line changes it to "main", which is the current standard.

05 Basic Workflow (Starting a New Project)

This is the flow you'll use almost every day. Do these steps in order:

  • Go to github.com/new, give your repo a name, and click "Create repository." Copy the URL it gives you.
  • Open your terminal inside your project folder and run:
    terminal
    $git init
  • Connect your local folder to GitHub:
    terminal
    $git remote add origin YOUR_REPO_URL

    Replace the URL with the one you copied. "origin" is just the nickname for your GitHub repo.

  • Stage your files:
    terminal
    $git add .

    The dot means "add everything in this folder." You can also stage one file at a time with git add index.html.

  • Commit — take a snapshot:
    terminal
    $git commit -m "first commit"

    The -m flag is for your message. Write something that makes sense — future you will thank you.

  • Push to GitHub:
    terminal
    $git push -u origin main

    This uploads everything. The -u origin main part is only needed the first time — after that, just git push.

Your everyday cycle

After the first push, this is the loop you'll repeat for every change:

terminal
$git add .
$git commit -m "what I changed"
$git push

06 Ignoring Files with .gitignore

Some files should never be committed — dependency folders, build output, secrets, and OS clutter. A .gitignore file tells Git to skip them automatically.

Create a file named exactly .gitignore in your project's root folder with contents like this:

.gitignore
node_modules/
.env
*.log
.DS_Store
dist/
terminal
$git add .gitignore
$git commit -m "add gitignore"

Heads up: .gitignore only stops files from being added from now on. If a file is already tracked, add it to .gitignore and also run git rm --cached <file> to make Git forget it (your local copy stays put).

07 Setting Up an Existing Folder

If you already have a project folder and want to connect it to GitHub, follow these steps. You might hit a couple of errors along the way, but they're easy to fix:

  • terminal
    $git init -b main
  • terminal
    $git remote add origin YOUR_REPO_URL

    If you get "remote origin already exists," use this instead: git remote set-url origin YOUR_REPO_URL

  • Check that the connection worked:
    terminal
    $git remote -v
    origin https://github.com/you/repo.git (fetch)
    origin https://github.com/you/repo.git (push)
  • terminal
    $git fetch origin

    This downloads the latest info from GitHub without touching your local files.

  • terminal
    $git reset --soft origin/main

    This syncs your local history with GitHub's without deleting anything — your files stay as staged changes.

  • terminal
    $git push -u origin main

    Done — your old folder is now fully synced with GitHub.

08 Working with Branches

Branches let you work on a new feature without touching the main code. Think of it as making a copy of your notebook to try things out, then pasting the good parts back into the original.

  • Create a new branch and switch to it:
    terminal
    $git checkout -b feature-name

    Replace feature-name with something descriptive, like add-login-page.

  • Do your work, then stage and commit as usual:
    terminal
    $git add .
    $git commit -m "added login page"
  • Switch back to main, then merge your branch in:
    terminal
    $git checkout main
    $git merge feature-name
  • git branch — lists all your branches. The one with * is where you currently are.
  • git checkout branch-name — switch to a branch that already exists.

09 Undoing Mistakes

Everyone messes up commits and staged files. These are the safe, everyday ways to undo things — ordered from "haven't committed yet" to "already pushed to GitHub."

  • Discard uncommitted changes in a file, back to the last commit:
    terminal
    $git restore <file>
  • Unstage a file (undo git add) without losing your changes:
    terminal
    $git restore --staged <file>
  • Fix the message of your last commit (only safe if you haven't pushed it yet):
    terminal
    $git commit --amend -m "new message"
  • Undo your last commit but keep the changes staged, so you can re-commit them properly:
    terminal
    $git reset --soft HEAD~1
  • Undo a commit that's already pushed: this is the safest option because it doesn't rewrite history — it adds a new commit that reverses the old one.
    terminal
    $git revert <commit-hash>

    Find the hash you need with git log.

Reading a merge conflict

When Git can't automatically combine two changes, it marks the conflicting spot directly in the file. Open the file, pick which version to keep (or blend them), then delete the marker lines entirely before you save:

index.html — conflict markers
<<<<<<< HEAD
<h1>Welcome to my site</h1>
=======
<h1>Hello, world</h1>
>>>>>>> feature-name

Everything above ======= is your current branch's version; everything below, down to the second marker, is the branch you're merging in. Once the file looks right, stage and commit it like normal to finish the merge.

10 Common Errors & Fixes

These are the messages almost every new Git user hits in their first week. None of them mean you broke anything.

fatal: not a git repository (or any of the parent directories): .git

Fix: you're not inside a folder Git is tracking. Either cd into the right project folder, or run git init if this folder hasn't been set up yet.

Please tell me who you are.

Fix: you skipped first-time setup. Run the git config --global user.name and user.email commands from section 04.

! [rejected] main -> main (fetch first) / Updates were rejected because the remote contains work that you do not have locally

Fix: GitHub has changes you don't have yet — usually from editing a file directly on the GitHub website. Run git pull origin main, resolve any conflicts, then push again.

fatal: refusing to merge unrelated histories

Fix: this happens when you created the GitHub repo with a README but your local folder has its own separate commits. Run git pull origin main --allow-unrelated-histories, resolve conflicts if any appear, then push.

You are in 'detached HEAD' state

Fix: you checked out a specific commit instead of a branch. If you didn't mean to make changes here, just run git checkout main to get back to safety.

11 Commands Cheat Sheet

git init Start tracking a folder with Git, creates a new local repo
git init -b main Same as above but sets the branch name to main right away
git clone <URL> Download a repo from GitHub to your computer
git status See which files are changed, staged, or untracked — use this often
git add . Stage all changed files to be included in the next commit
git add <file> Stage only a specific file
git commit -m "msg" Save a snapshot with a short description message
git commit Opens a text editor so you can write a longer, multi-line commit message
git log See the full history of all commits, press Q to exit
git remote -v List connected remote repos and their URLs
git remote add origin <URL> Connect your local repo to a GitHub repo for the first time
git remote set-url origin <URL> Change the GitHub URL if you already have one set
git fetch origin Download the latest info from GitHub without changing your local files
git push Upload your committed changes to GitHub
git push -u origin main First-time push, also sets main as the default branch going forward
git pull Download and apply the latest changes from GitHub to your local copy
git branch List all branches, the one with * is where you currently are
git checkout -b <name> Create a new branch and switch to it
git checkout <name> Switch to an existing branch
git merge <name> Merge another branch's changes into your current branch
git restore <file> Discard uncommitted changes in a file
git restore --staged <file> Unstage a file without losing your changes
git commit --amend Edit the message (or contents) of your last commit
git reset --soft HEAD~1 Undo the last commit, keeping the changes staged
git revert <hash> Safely undo an already-pushed commit with a new commit
git reset --soft origin/main Sync your local history with GitHub's without losing your files

12 Tips & Common Mistakes

  • Write useful commit messages.

    "fixed bug" is bad. "fixed login crash when email field is empty" is way better. Future you will understand it.

  • Run git status before committing.

    It's safe and tells you exactly what's going on — what's staged, what's not, what's untracked.

  • Don't forget git add before git commit.

    If you just run git commit without staging first, nothing gets saved.

  • Never commit passwords or API keys.

    Use a .gitignore file to exclude sensitive files like .env. Once something is pushed to GitHub, it's very hard to fully remove.

  • Pull before you push when working with others.

    Always run git pull first to get the latest changes and avoid conflicts.

  • Don't work directly on main.

    Create a branch for each feature or fix. Keep main clean, and only merge into it when things are actually working.

13 Practice Checklist

Reading isn't the same as doing. Work through this list in your own terminal — check items off as you go. (This checklist resets if you reload the page, so treat it as a session guide, not permanent progress.)

Comfortable with all of this? Head to Part 2 — GitHub Essentials to create real repositories on GitHub, push a whole project folder, and connect to it from the terminal.