Git Made Simple: Install, SSH Keys & GitHub Setup

Once per computer

1. Installation and global settings

Windows

Download the installer from git-scm.com, or run in PowerShell:

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

The default installer options are fine.

macOS

Git comes with the Xcode command line tools:

xcode-select --install

If you use Homebrew, you can also install it like this:

brew install git

Linux

Ubuntu / Debian:

sudo apt update && sudo apt install git

On other distributions use their package manager (e.g. sudo dnf install git).

Check – prints the installed version

git --version

Commit author identity

Every commit carries the author’s name and e-mail. Choose how you want to manage them:

No global identity (recommended)

You set the identity in each project separately (step 3.3). When working under multiple accounts or on projects with different security levels, there is nothing to switch and you never commit under the wrong account.

Setup

git config --global user.useConfigOnly true

Git will then refuse to commit until the project has an identity. Without this line, Git may guess one from the system (e.g. user@pc-name) and commit without asking.

Check – empty output = all good

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

A name or e-mail was printed? Remove it:

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

Global identity

Suitable if you work under one account. The setting applies to all projects – you then set a local identity (step 3.3) only where you want a different one.

Setup

git config --global user.name "Jane Doe"
git config --global user.email "jane@example.com"

Check – prints the configured values

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

Once per computer

2. Connect to GitHub

GitHub and other web Git services require an SSH key (or a Personal Access Token). Each GitHub account has its own key and its own alias you connect through. One computer can be connected to several accounts at the same time, with nothing to switch.

Enter your accounts – the commands in all steps below adapt to them.

Your details – the commands in the steps below adapt to them

Computer name

Account name

Service

Generate an SSH key

Mac / Linux

ssh-keygen -t ed25519 -C "my-pc" -f ~/.ssh/github_account1

Windows

ssh-keygen -t ed25519 -C "my-pc" -f $env:USERPROFILE\.ssh\github_account1

It says the file can’t be saved? The .ssh folder doesn’t exist yet – create it and run the command again:

mkdir $env:USERPROFILE\.ssh

Each account gets its own key. We recommend a passphrase – it protects the key if it ever gets into the wrong hands.

Add the key to the SSH agent

You add the private key (= the file without the .pub extension).

Mac / Linux

eval $(ssh-agent -s)
ssh-add ~/.ssh/github_account1

Windows

Once – in PowerShell started as Administrator

Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent

This starts the SSH agent and enables it on every system start. “Service already running” is fine.

Add the key – in a regular PowerShell

ssh-add $env:USERPROFILE\.ssh\github_account1

The output should be:

Identity added: C:\Users\<you>\.ssh\github_account1 (my-pc)

Add the public key to your GitHub account

Mac / Linux

to account account1 (GitHub):

cat ~/.ssh/github_account1.pub

Windows

to account account1 (GitHub):

Get-Content $env:USERPROFILE\.ssh\github_account1.pub

Print each key, copy it and add it to the matching account:

Log in to the account and open github.com/settings/keys (SSH and GPG keys tab).
Click New SSH key, name it after your PC and paste the copied key.

Careful

Only the public key goes to GitHub – the file ending in .pub. The file without an extension is your private key; never paste it anywhere.

Assign the key to the account (SSH config)

Open ~/.ssh/config (Windows: C:\Users\<you>\.ssh\config, no extension). Create it if it doesn’t exist. The config is built from your accounts – just copy and paste it:

# GitHub account1
Host github-account1
  HostName github.com
  User git
  IdentityFile ~/.ssh/github_account1
  IdentitiesOnly yes

Host is the alias you then use instead of github.com. IdentitiesOnly yes makes sure only that account’s key is used – otherwise SSH could offer another account’s key from the agent and GitHub would log you in as that account.

Test the connection

ssh -T git@github-account1

On the first connection, confirm the server fingerprint by typing yes. A successful connection responds with the name of the correct account:

Hi <username>! You've successfully authenticated, but GitHub does not provide shell access.

Getting Permission denied (publickey) instead?

See common errors for the fix.

GitLab or Bitbucket?

Same steps – just pick the service for the account at the top of this section. Add the key in GitLab under Preferences → SSH Keys, in Bitbucket under Personal settings → SSH keys.

For every project

3. New project

Create a repository on GitHub

Click New repository, enter a name and choose public or private. If the project already exists on GitHub, skip this step.

Connect it to a folder on your computer

The project belongs to account

You’ll find the repository address on GitHub under Code → SSH. Replace github.com in it with the account alias (github-account1) – the commands below already include it.

Starting from scratch / project already on GitHub

When creating the repository on GitHub, tick Add a README file. Then download it – the project folder is created and the connection is set up automatically:

git clone git@github-account1:<user>/<repo>.git
cd <repo>

I already have a folder with code

Create the repository on GitHub empty – without README, .gitignore or license. Then run in your project folder:

git init -b main
git remote add origin git@github-account1:<user>/<repo>.git

Check – shows where the project is connected

git remote -v

Pointing somewhere else (e.g. github.com instead of the alias)? Change the address:

git remote set-url origin git@github-account1:<user>/<repo>.git

Set the local identity

Without a global identity (step 1) this step is required. With a global identity, use it only where you want to commit under a different one.

Setup – inside the project folder

git config user.name "Jane Doe"
git config user.email "jane@example.com"

Use the e-mail of the GitHub account the project belongs to – otherwise your commits won’t be linked to your profile.

Check – prints the identity you will commit as in this project

git config user.name
git config user.email

Something unexpected was printed? Find out where the value comes from:

git config --list --show-origin

First commit and push

.gitignore first

Make sure the project root contains a .gitignore file listing everything that doesn’t belong in the repository (node_modules/, .env, build output…). Passwords and keys that make it into the history are very hard to remove. Ready-made templates: github.com/github/gitignore.

git add .
git commit -m "Initial commit"
git push -u origin main

Command	What it does
`git add .`	Marks changed files for the commit (except those in .gitignore).
`git commit -m`	Creates a commit with a message.
`git push -u origin main`	Uploads the commits to GitHub. `-u` is only needed the first time – after that just `git push`.

Ongoing

4. Everyday work

Everyday work is the same four-step cycle:

1.git pullGet other people’s changes.
2.git add .Mark your changes.
3.git commit -m "…"Save them with a message.
4.git pushUpload them to GitHub.

Not sure where you are?

Run git status. It shows changed files and suggests the next step.

Command overview

Command	What it does
Status and history
`git status`	What changed and what is staged for commit.
`git diff`	The exact changes in files.
`git log --oneline`	Short commit history.
Branches
`git switch -c <branch>`	Creates a new branch and switches to it.
`git switch main`	Switches back to the main branch.
`git merge <branch>`	Merges the branch into the current one.
`git push -u origin <branch>`	First upload of a new branch to GitHub.
Undoing changes
`git restore <file>`	Discards uncommitted changes in a file.
`git restore --staged <file>`	Unstages a file after `git add` (changes are kept).
`git commit --amend`	Fixes the last commit – only if it hasn’t been pushed yet.

Ongoing

5. Common errors

Author identity unknown *** Please tell me who you are.

The project has no identity set – expected without a global identity. Set it locally (step 3.3).

Permission denied (publickey)

GitHub rejected the key. Check one by one:

Is the key in the agent? – lists loaded keys

ssh-add -l

Key missing? Add it again (step 2.2).

On Mac/Linux the key has to be added to the agent again after a restart.

Does the alias work?

ssh -T git@github-account1

Not working? Check the block in ~/.ssh/config (step 2.4) and the public key in your GitHub account (step 2.3).

Does the project use the alias?

git remote -v

Shows github.com or https://? Change the address:

git remote set-url origin git@github-account1:<user>/<repo>.git

Windows: Git doesn’t see the key in the agent? – e.g. keeps asking for the passphrase

Make Git use the Windows SSH client (the same one as the agent):

git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

Could not open a connection to your authentication agent

The SSH agent isn’t running.

Mac / Linux

eval $(ssh-agent -s)
ssh-add ~/.ssh/github_account1

Windows

In PowerShell as Administrator (permanent setup see step 2.2):

Start-Service ssh-agent

error: remote origin already exists

The connection already exists. Use set-url instead of add:

git remote set-url origin git@github-account1:<user>/<repo>.git

error: src refspec main does not match any

The main branch has no commit yet, or it has a different name (e.g. master). Commit first (step 3.4), or rename the branch: git branch -M main.

! [rejected] main -> main (fetch first)

GitHub has changes you don’t have locally. Get them and push again:

git pull --rebase origin main
git push

Commits aren’t linked to my GitHub profile

The commit e-mail doesn’t match any e-mail in your account. Check git config user.email (step 3.3).

Git made simple

1. Installation and global settings

Commit author identity

2. Connect to GitHub

Generate an SSH key

Add the key to the SSH agent

Add the public key to your GitHub account

Assign the key to the account (SSH config)

Test the connection

3. New project

Create a repository on GitHub

Connect it to a folder on your computer

Set the local identity

First commit and push

4. Everyday work

Command overview

5. Common errors

Anything unclear?

1. Installation and global settings

Commit author identity

2. Connect to GitHub

Generate an SSH key

Add the key to the SSH agent

Add the public key to your GitHub account

Assign the key to the account (SSH config)

Test the connection

3. New project

Create a repository on GitHub

Connect it to a folder on your computer

Set the local identity

First commit and push

4. Everyday work

Command overview

5. Common errors

Related

Anything unclear?