Git & GitHub — Setup Workshop

00 · Orientation

Two tools, one workflow

Before installing anything, it helps to know exactly what each tool does — and why professional workflows always use both together.

What is Git?

A distributed version control system that runs on your machine. Created by Linus Torvalds in 2005 to manage Linux kernel development — now the standard everywhere.

Records every change, with a message explaining why
Lets you branch off and experiment safely
Merges work back together automatically
Can revert any file to any past state

What is GitHub?

A cloud platform that hosts Git repositories. Git is the tool on your computer; GitHub is the server where that history is stored and shared.

Remote repositories, backed up automatically
Pull requests for reviewing changes
Issues for tracking bugs and features
Actions for automated testing & deploys

Why both?

Git alone means your history lives on one machine — if it fails, you lose everything. GitHub needs Git underneath it to receive anything at all.

You commit locally with Git, constantly
You push to GitHub, periodically
Together: safe, shared, professional

00.5 · The spatial model

Inside the four layers

This whole page reads Git the way Git actually works: as physical depth. Every command below moves a file forward or backward between four real layers. Click one to bring it to the front.

Working Directory

Unstaged

The nearest layer — the actual files in your project folder, exactly as your editor last saved them. Git is watching this folder, but nothing here is protected yet: an accidental overwrite or delete is real damage.

Look around git status

Which files changed since the last commit.

Move forward → git add <file>

Stages a snapshot of the file for the next commit.

Staging Area

Staged

Also called the index. A curated snapshot, separate from what's on disk — it holds exactly what the next commit will contain, no more and no less. This is what lets you commit half your changes and keep working on the rest.

Move back ← git restore --staged <file>

Unstages the file without discarding the edit.

Move forward → git commit -m "…"

Seals the staged snapshot into permanent history.

Local Repository

Committed

This is what "Git" actually is — every commit you've ever made, stored in the hidden .git/ folder on this machine. It's a complete, self-contained history; nothing here needs the internet.

Look around git log --oneline

The commit history, one line per snapshot.

Move forward → git push origin main

Sends new commits up to GitHub.

GitHub (Remote)

Pushed

The farthest layer — the same history, hosted on GitHub's servers. Backed up, shareable with one link, and the copy every collaborator pulls from. Parts 2 and 3 of this guide are entirely about wiring your machine up to this layer.

Arrive here via git clone <url>

First time only — downloads the whole repository.

Move back ← git pull

Brings GitHub's commits down into your local repository.

01 · Local layer

Install Git

First, check whether Git is already on your machine.

# check for an existing install
git --version

If Git is installed you'll see something like git version 2.44.0. If not, follow your platform below.

macOS — two ways to install

Method 1 · Xcode Command Line Tools (quick)

macOS ships an old Git via Apple's developer tools. Fast to get, but it lags behind the latest release.

1
Open Terminal.
⌘+Space → type Terminal → Return. Or Finder → Applications → Utilities → Terminal.
2
Trigger the installer.
Run git --version. If Git is missing, macOS shows a dialog: "The xcode-select command requires the command line developer tools." Click Install — not Get Xcode.
3
Wait for the download.
About 150–200 MB, typically 2–5 minutes depending on your connection.
4
Accept the licence agreement.

Confirm it worked.

git --version
# Expected: git version 2.x.x (Apple Git-xxx)

Method 2 · Homebrew (recommended)

Homebrew is macOS's most popular package manager — gives you the latest Git, updatable with one command.

1
Install Homebrew.
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
It will ask for your system password. Nothing appears as you type — that's normal.

Apple Silicon: add Homebrew to your PATH.

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

3
Install Git.
```
brew install git
```

Confirm.

git --version
# Expected: git version 2.x.x (NOT Apple Git)

5
Update later, anytime.
```
brew upgrade git
```

Note

If git --version still says Apple Git, run which git. If it shows /usr/bin/git instead of /opt/homebrew/bin/git, reopen your terminal — or see Troubleshooting.

Windows — two ways to install

Method 1 · Official installer (recommended)

Git for Windows bundles Git, a Bash emulator (Git Bash), and a GUI tool.

1
Download.
Go to git-scm.com/download/win and get the 64-bit installer.
2
Run it.
Open the .exe, click Yes on the UAC prompt.
3
Licence, destination, components.
Accept the defaults and click Next through each.
4
Default editor.
Change from Vim to VS Code, Notepad++, or Nano.
5
Initial branch name.
Choose Override and type main.
6
PATH environment — critical.
Select "Git from the command line and also from 3rd-party software." This makes git work in PowerShell, Command Prompt, and VS Code.
7
SSH.
Select "Use bundled OpenSSH."
8
HTTPS backend.
Select "Use the OpenSSL library."
9
Line endings — critical.
Select "Checkout Windows-style, commit Unix-style line endings." Prevents false diffs when collaborating across platforms.
10
Terminal.
Select "Use MinTTY."
11
git pull behaviour.
Keep the default.
12
Credential helper.
Select "Git Credential Manager," then Install.

Verify.

Open Git Bash from the Start Menu:

git --version
# Expected: git version 2.x.x.windows.x

Method 2 · winget (command line)

Open PowerShell as Administrator:

winget install --id Git.Git -e --source winget

Restart your terminal, then confirm with git --version.

02 · Cloud layer

Create a GitHub account

Git manages history locally. A GitHub account gives that history a home online — backed up, accessible anywhere, and shareable with one link.

Choosing your username

Your username becomes part of every URL tied to your work:

https://github.com/yourusername https://github.com/yourusername/your-project

Pick something professional (based on your real name), short and memorable, consistent with LinkedIn, and free of random numbers unless necessary.

1
Go to github.com in any browser.
2
Click "Sign up" top-right.
3
Enter your email address.
Use the same one you'll configure Git with in Part 3 — otherwise commits won't link to your profile.
4
Create a password of at least 8 characters — ideally from a password manager.
5
Choose your username.
Effectively permanent — changing it later breaks links to your existing repositories.
6
Email preferences.
Optional — your call on product updates.
7
Solve the CAPTCHA.
8
Click "Create account."
GitHub sends a verification email.
9
Verify your email.
Click the link in the email — some features stay locked until you do.
10
Onboarding survey.
Optional — only affects the tips GitHub shows you.

Ready

Once your email is verified, your account is fully active. Next: connect it to the Git you just installed.

03 · Bridge

Configure Git

Your name and email are attached to every commit and become a permanent part of project history — like a signature on each saved change.

Three levels of configuration

Level	Scope	Stored in
--system	Every user on the machine	/etc/gitconfig (macOS)C:\Program Files\Git\etc\gitconfig
--global	Your user, all repositories — used in this guide	~/.gitconfig
--local	One repository only — overrides global	.git/config

Name & email

git config --global user.name "Your Full Name"
git config --global user.email "youremail@example.com"

Why it matters: every commit says who made it — how teammates identify changes, and part of your professional identity.

Critical

The email here must exactly match an email on your GitHub account. It's how GitHub links commits to your profile. Mismatched, and commits show as an "unknown user," are excluded from your contribution graph, and your name won't display correctly.

Check your GitHub emails: github.com/settings/emails

Default text editor

Running git commit without -m opens an editor — the default is Vim, which trips up most beginners.

VS Code (recommended):

git config --global core.editor "code --wait"

The --wait flag pauses Git until you close the tab. Without it, Git continues before you're done writing.

Nano (simple):

git config --global core.editor "nano"

VS Code:

git config --global core.editor "code --wait"

Notepad++:

git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"

Notepad (built-in):

git config --global core.editor "notepad"

Default branch name

Git historically named the first branch master. GitHub and the community now use main — a mismatch will fail your first push.

git config --global init.defaultBranch main

Line endings

Windows uses CRLF; macOS and Linux use LF. Left unconfigured, Git sees every line as changed across platforms — polluting history.

git config --global core.autocrlf input

Strips CRLF to LF on commit; adds nothing on checkout. Files on disk and in the repo both stay LF.

git config --global core.autocrlf true

Converts LF→CRLF on checkout (for Windows apps) and CRLF→LF on commit (so the repo stays consistent for everyone).

Reviewing your configuration

git config --global --list

Expected output:

user.name=Jane Doe user.email=jane.doe@gmail.com core.editor=code --wait init.defaultbranch=main core.autocrlf=inputtrue

Or view the file directly:

cat ~/.gitconfig

04 · Proof of connection

Verify your setup

Skipping verification is where quiet failures hide: the wrong Git version active, a typo'd email, an editor that isn't installed, a branch still called master. Five minutes now saves hours later.

1 · Version & path

git --version

Check which binary is active:

which git

Expected: /opt/homebrew/bin/git (Apple Silicon) or /usr/local/bin/git (Intel). /usr/bin/git means Homebrew isn't taking priority — see Troubleshooting.

where git

Expected: a path inside C:\Program Files\Git\. Nothing returned means Git isn't on PATH — re-run the installer.

2 · Name & email

git config --global user.name
git config --global user.email

Spelled correctly? Matches your GitHub account? Rerun the config command to overwrite if not.

3 · Full settings list

git config --global --list

Confirm all five: user.name, user.email, core.editor, init.defaultbranch, core.autocrlf.

4 · End-to-end push test

1
Log in at github.com.
2
Click + → New repository, name it git-test.
3
Check "Add a README file" and click Create repository.

# clone, change, and push
git clone https://github.com/yourusername/git-test.git
cd git-test
echo "Hello from my machine" >> README.md
git add README.md
git commit -m "Add a test line to README"
git push origin main

When prompted for credentials, use your GitHub username and a Personal Access Token as the password (below).

5 · Confirm on your profile

Visit github.com/yourusername/git-test and confirm your commit message appears. Then check your profile's contribution graph — today should be highlighted.

Important

GitHub removed password authentication in August 2021. Use a Personal Access Token (PAT) instead:

Go to github.com/settings/tokens
Click Generate new token (classic)
Set a name, an expiry, and tick the repo scope
Click Generate token and copy it immediately — shown once only

Use the token as your password when Git prompts. The credential manager saves it after the first time.

05 · Cheat sheet

Quick reference

Every command from this guide, in one place.

Git setup commands

Command	What it does
git --version	Check installed version
which git	Show the active Git binary path
where git	Show the active Git binary path
git config --global user.name "Name"	Set display name for all commits
git config --global user.email "email"	Set email for all commits
git config --global core.editor "code --wait"	Set VS Code as commit editor
git config --global init.defaultBranch main	New repos start on main
git config --global core.autocrlf input	Line endings (macOS/Linux)
git config --global core.autocrlf true	Line endings (Windows)
git config --global --list	Show all global settings

First repository workflow

Command	What it does
git clone <url>	Download a repo from GitHub
git status	Show changed files
git add .	Stage all changes
git add <file>	Stage one file
git commit -m "message"	Save staged changes with a description
git push origin main	Upload commits to GitHub
git pull	Download latest commits from GitHub
git log --oneline	Compact commit history

Config file locations

Platform	Global .gitconfig path
macOS	~/.gitconfig (e.g. /Users/janedoe/.gitconfig)
Windows	C:\Users\YourUsername\.gitconfig

06 · When a layer misaligns

Troubleshooting

The most common failure points, and exactly how to fix each one.

"command not found: git" (macOS)▸

CauseGit isn't installed, or the install didn't finish.

FixRun xcode-select --install, or brew install git if using Homebrew. Reopen your terminal.

"git is not recognized" (Windows)▸

CauseGit wasn't added to the Windows PATH.

FixRe-run the installer; on the PATH screen choose "Git from the command line and also from 3rd-party software." Restart your terminal.

Homebrew's Git isn't taking priority▸

Symptomwhich git shows /usr/bin/git despite installing via Homebrew.

Fix

# Apple Silicon
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Intel Mac
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Push rejected: authentication failed▸

CauseGitHub stopped accepting account passwords in August 2021.

FixGenerate a Personal Access Token at github.com/settings/tokens with the repo scope, and use it as your password. The credential manager saves it after that.

Commits missing from the contribution graph▸

CauseYour Git email doesn't match any email on your GitHub account.

Fix

Run git config --global user.email to see your configured email.
Check registered emails at github.com/settings/emails.
If different: git config --global user.email "correct@email.com"
Future commits link correctly — past ones can't be fixed retroactively.

"refusing to merge unrelated histories"▸

CauseYour GitHub repo (created with a README) and your local repo each have an independent first commit — no shared history.

Fix

git pull origin main --allow-unrelated-histories

07 · Where next

You're set up

Here's what's now in place, and where to go from here.

✓Installed Git via Xcode tools or Homebrewvia the official installer or winget
✓Created a GitHub account with a professional username and verified email
✓Configured Git with name, email, editor, default branch, and line endings
✓Verified everything end-to-end — pushed a real commit and confirmed it on GitHub

What to learn next

The daily add / commit / push cycle
Branching and merging
SSH keys, in place of tokens
Pull requests & code review
GitHub Actions for automation

Set up Git and GitHub, layer by layer.

Two tools, one workflow

What is Git?

What is GitHub?

Why both?

Inside the four layers

Working Directory

Staging Area

Local Repository

GitHub (Remote)

Install Git

Create a GitHub account

Configure Git

Verify your setup

Quick reference

Git setup commands

First repository workflow

Config file locations

Troubleshooting

You're set up

What to learn next

Further reading