Git tutorial: install Git, configure it and add an SSH key

This chapter installs Git, sets the three options without which your first commit will be refused, and puts authentication with GitHub or GitLab in place. Allow about fifteen minutes, SSH key included.

If you have landed straight here, the difference between Git and GitHub and the outline of the series are covered in the introduction to the tutorial.

Installing Git

Git is probably already on your machine if you are on macOS or Linux. Check before you install anything:

git --version

If the command answers with a version number, Git is installed and you can move on to the configuration. If it says the command cannot be found, follow the section for your system.

Windows

The simplest route is the package manager built into Windows:

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

Otherwise, download the installer from git-scm.com/install/windows and leave the default options alone. The latest version published at the time of this check is Git for Windows 2.55.0(5), from 20 August 2026. The installation gives you Git Bash, a terminal that reproduces the Unix environment. Use it rather than the command prompt: every command in this tutorial works there as it stands.

macOS

Git ships with the Xcode command line tools. The first time you invoke git it offers to install them, or you can force the installation:

xcode-select --install

That version is reliable, but often a few months behind the official release. To stay up to date, go through Homebrew:

brew install git

Linux

Use your distribution’s package manager.

# Debian, Ubuntu and derivatives
sudo apt update && sudo apt install git

# Fedora, RHEL, Rocky
sudo dnf install git

# Arch
sudo pacman -S git

# Alpine
sudo apk add git

The installed version depends on your distribution, and the gap is sometimes wide. The versions measured on 7 September 2026 are given in the “Measured result” section at the bottom of this chapter. Ubuntu 24.04 ships Git 2.43, released in late 2023: that is more than enough for everything in this tutorial, since the most recent commands we use date from Git 2.23.

Declaring yourself: name and email address

Git writes the author of every commit into the history. Until you have told it who you are, it refuses to record anything:

Author identity unknown

*** Please tell me who you are.

Run

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

to set your account's default identity.
Omit --global to set the identity only in this repository.

fatal: unable to auto-detect email address (got 'root@23d1d26b6831.(none)')

So set both values before anything else:

git config --global user.name "Damien Flandrin"
git config --global user.email "dam@example.com"

The --global option writes to your personal file and applies to all your projects. Without it, the setting only covers the current repository, which is handy when you use a work address on some projects and a personal one on others.

Use an address you are happy to make public: it appears in the history, and the history is handed to everyone who clones the project. GitHub offers a substitute address at @users.noreply.github.com if you would rather not expose your own.

Choosing the default branch name

This is the point where the most false information circulates. You often read that Git now creates a main branch. That is wrong. Here is what git init produces with Git 2.55, the current version in September 2026:

hint: Using 'master' as the name for the initial branch. This default branch name
hint: will change to "main" in Git 3.0. To configure the initial branch name
hint: to use in all of your new repositories, which will suppress this warning,
hint: call:
hint:
hint: 	git config --global init.defaultBranch <name>
hint:
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint:
hint: 	git branch -m <name>
hint:
hint: Disable this message with "git config set advice.defaultBranchName false"
Initialized empty Git repository in /root/a1/.git/

So the branch really is called master, and Git says itself that the default will move to main in version 3.0. What has changed is the hosting services: GitHub has created new repositories with a main branch since October 2020, GitLab since version 14. Hence the permanent mismatch between what your machine does and what the server does.

Settle the question once and for all:

git config --global init.defaultBranch main

The message goes away and the repositories you create afterwards start on main. Careful though, the setting only applies to new repositories. For a repository that already exists and whose branch is called master:

git branch -m master main

Checking your configuration

Three commands are enough to see where you stand:

git config --global --list                # what is set
git config --global --list --show-origin  # and in which file
git config --global --edit                # open the file

Your personal configuration is a plain text file, ~/.gitconfig, which you can read and edit directly:

[user]
	name = Damien Flandrin
	email = dam@example.com
[init]
	defaultBranch = main

Two more settings are worth putting in place straight away. The editor Git uses for commit messages, without which you will sooner or later land in Vim with no idea how to get out:

git config --global core.editor "code --wait"   # Visual Studio Code
git config --global core.editor "nano"          # or any terminal editor

And the behaviour of git pull, which we go into in the chapter on branches:

git config --global pull.rebase true

Authenticating with GitHub or GitLab

A point of vocabulary is needed here, because it costs beginners a lot of time. Your GitHub password is no use to Git any more. GitHub stopped accepting account passwords for Git operations on 13 August 2021. Here is what the server answers if you try anyway:

Cloning into 'depot-prive'...
remote: Invalid username or token. Password authentication is not supported for Git operations.
fatal: Authentication failed for 'https://github.com/damienflandrin/depot-prive.git/'

Two valid methods remain: the SSH key and the personal access token. The SSH key takes five minutes to set up and is never asked for again. That is the one we recommend.

Creating an SSH key

ssh-keygen -t ed25519 -C "dam@example.com"

Accept the path it suggests. The passphrase is optional but recommended: it protects the key if your machine is compromised.

Generating public/private ed25519 key pair.
Created directory '/root/.ssh'.
Your identification has been saved in /root/.ssh/id_ed25519
Your public key has been saved in /root/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:s5YjDRbNgv3/o8SvEFh4A6hzpWddSsquX0l0k4aUptw dam@example.com

Two files have been created. id_ed25519 is the private key: it never leaves your machine, is never copied anywhere, is never pasted into any form. id_ed25519.pub is the public key, the one you hand to the server.

Print the public key and copy the whole line:

cat ~/.ssh/id_ed25519.pub

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINjiBkboRdOPXk2UWn3UUMSv2qr8G9cGvzKsTd+ZyYCa dam@example.com

Then paste it into Settings > SSH and GPG keys > New SSH key on GitHub, or into Preferences > SSH Keys on GitLab.

Checking that the key works

ssh -T git@github.com

The first connection asks you to confirm the server’s fingerprint. GitHub’s, for Ed25519 keys, is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU, compare it with the one published by GitHub before you answer yes. If everything is in order, GitHub replies with a welcome message mentioning your username and stating that shell access is not allowed, which is normal. If instead you get:

git@github.com: Permission denied (publickey).

then the public key has not been registered on your account, or you have pasted the private key by mistake.

The alternative: the personal access token

If SSH is blocked on your network, or in a continuous integration script, use a personal access token. On GitHub, create it under Settings > Developer settings > Personal access tokens, favouring fine-grained tokens, which limit access to one specific repository and expire on their own. On GitLab, the equivalent sits under Preferences > Access tokens.

The token is used in place of the password when Git asks for one. To avoid retyping it on every command, turn on a credential helper:

git config --global credential.helper store    # simple, but the token is stored in plain text
git config --global credential.helper osxkeychain  # macOS, stored in the keychain

On Windows, Git Credential Manager is installed and enabled by default with Git for Windows.

Treat a token exactly like a password: it does not go into a repository, nor into a versioned configuration file, nor into a URL you share.

Your machine is ready. The next chapter creates a repository on GitHub or GitLab and links it to a folder on your machine.

Measured result

Git version installed by the package manager on the official image of each distribution, measured on 7 September 2026:

All of them are fine: the most recent command used in this tutorial, git switch, dates from Git 2.23.