Arc 1 Quest 01

The Archivists' Guild

Installing and configuring Git

Introduction

The wind whistles between the towers of the Citadel of Knowledge as you pass through the heavy doors of the Archivists' Guild. Here, scribes bustle about preserving the memory of the entire kingdom - every royal decree, every peace treaty, every battle plan. Without them, history would be lost forever.

An old man with a silver beard approaches you. His eyes sparkle with mischief behind his round spectacles. He is the Master Archivist.

"Welcome, young recruit. I am the Master Archivist, guardian of the kingdom's history. You've arrived at just the right time, because we have a serious problem... Our scribes keep losing their work, overwriting each other's scrolls, and nobody knows who changed what anymore. We need a new archiving system. And you are going to learn to master it."

The problem: working without versioning

Before understanding the solution, you need to understand the problem. Here's what happens when you work without a versioning system:

The chaos of file names

You probably know this situation:

final_report.txt
final_report_v2.txt
final_report_v2_corrected.txt
FINAL_report_REALLY_FINAL.txt
FINAL_report_REALLY_FINAL_2.txt
FINAL_report_OK_THIS_ONE.txt

Which one is the right one? Nobody knows. Not even the person who created them.

Overwritten work

Imagine: two scribes, Aldric and Berenice, are working on the same scroll. Aldric makes his changes in the morning and saves. Berenice, who had opened the scroll the previous evening, makes her own changes in the afternoon and saves too. Result: all of Aldric's work has vanished, overwritten without warning. Aldric has a very bad day.

The mystery of modifications

"It was working yesterday! What changed?"

Someone changed something. But who? When? And most importantly, why? Impossible to tell. You waste hours searching, and sometimes you never find the version that was working.

The solution: versioning

The Master Archivist has found the solution. Instead of blindly saving over the old file, we're going to record every modification with four essential pieces of information:

  • Who made the modification
  • When it was made
  • What exactly changed (not just "I modified the file", but which lines precisely)
  • Why - a short message explaining the reason for the change

With versioning, you can go back in time at any moment, see the complete history of all modifications, and multiple people can work simultaneously without overwriting each other.

Git: the tool of modern Archivists

The system you're going to learn is called Git. It's the most widely used versioning tool in the world. But it wasn't the first - others tried before it.

Before Git: the old systems

The need to track file changes is nothing new. Several tools existed before Git:

  • RCS (1982) - One of the first versioning systems. It could only manage one file at a time - impossible to work on an entire project.
  • CVS (1990) - The first tool to manage multiple files together. But it relied on a central server: if the server went down, nobody could work.
  • SVN / Subversion (2000) - An improvement over CVS, more reliable and faster. Very popular for years, but still centralized: every operation required a connection to the server.
  • Mercurial (2005) - Created the same year as Git, with the same distributed philosophy. A good tool, but Git gradually overtook it in popularity.

The common problem with these tools? Either they were too limited, or they depended on a central server, or they were too slow for very large projects.

The arrival of Git

  • 2005 - Linus Torvalds (the creator of Linux) manages the Linux kernel source code - a project with thousands of developers and millions of lines of code. Existing tools can't handle the load. So he creates his own in just a few weeks: Git.
  • Distributed - Unlike older systems, Git is distributed: every person working on a project has a complete copy of the entire history. No need for a central server to consult the project's history.
  • Fast - Git was designed to be extremely fast, even on gigantic projects. The Linux kernel itself - with over 30 years of history and millions of lines - is managed with Git.
  • Today - Git is free, open source, and used by practically every developer on the planet. Platforms like GitHub, GitLab, and Bitbucket are built around Git.

Yes, Git has a lot of commands and can seem complex at first. But it's precisely this power that allows it to manage everything from a small personal project to a monster like the Linux kernel. And in practice, a handful of commands is enough for 90% of daily work.

Git isn't just for developers! It can be used for any project made up of text files: documentation, configuration files, websites, etc.

Installing Git

Before you start using Git, you need to install it on your machine. Here are the instructions depending on your operating system.

Windows

  1. Go to git-scm.com and download the installer.
  2. Run the installer and follow the steps (the default options work perfectly fine).
  3. The installation includes Git Bash, a terminal that will let you use Git commands.
  4. To verify: open Git Bash and type git --version.

Linux

Open a terminal and use your distribution's package manager:

# Debian, Ubuntu, Mint...
sudo apt install git

# Fedora, RHEL, CentOS...
sudo dnf install git

# Arch Linux
sudo pacman -S git

To verify: git --version

macOS

Two options:

# Option 1: via Apple command line tools
xcode-select --install

# Option 2: via Homebrew (if you have it installed)
brew install git

To verify: git --version

First configuration

Git needs to know who you are. Every modification you record will carry your signature - a name and an email address. This is mandatory.

Open a terminal (Git Bash on Windows) and type these two commands, replacing the values in quotes with your own:

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

You don't have to use your real name. A pseudonym works perfectly fine. Many open source contributors use a nickname and a dedicated email address. What matters is that Git can identify the author of each modification.

The --global option means this configuration applies to all your Git projects on this machine. You only need to do it once.

To verify that everything is properly saved:

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

These commands should display your name and email respectively.

Configure your default branch

Since 2020, the modern convention is to call the main branch main instead of the historical master. Configure this preference globally so that all your future git init commands automatically create a main branch:

git config --global init.defaultBranch main

This configuration is important for the upcoming quests. Without it, some instructions that assume a main branch will fail on your first git init.

Per-project configuration

You might want to use a nickname on your personal online projects, but your real name (or a trigram) on your professional projects. Git allows this thanks to the --local option, which overrides the global configuration only for the current repository:

# In a professional repository
cd my-pro-project/
git config --local user.name "Jane Smith"
git config --local user.email "jsmith@company.com"

The priority is simple: --local (per project) always wins over --global (per machine). This way you can keep your nickname as the global default and only configure --local in repositories that require a different identity.

--global = default configuration for the entire machine. --local = configuration specific to a single repository. Local always takes priority.

A word about security

You may have noticed: nothing prevents you from configuring user.name with someone else's name. You could very well type git config user.name "Linus Torvalds" and all your commits would bear his name. Git does not verify your identity - it simply records what you give it.

This is a known and deliberate limitation. For projects where authenticity truly matters, there's a solution: cryptographic signing of commits. By using a GPG (or SSH) key, you can mathematically prove that it was really you who created a commit. Platforms like GitHub then display a "Verified" badge next to the commit.

Commit signing is an advanced topic that we won't cover in this quest. Just remember that user.name and user.email are declarative - it's the cryptographic key that serves as real proof of identity.

Practical exercise - Quest validation

Run the verification script to confirm that Git is installed and configured correctly on your machine.

Bash (Linux / macOS / Git Bash on Windows):

bash verifier.sh

PowerShell (Windows):

.\verifier.ps1

The script checks four things:

  1. Git is installed on your machine
  2. Your name is configured (user.name)
  3. Your email is configured (user.email)
  4. Your default branch is main (init.defaultBranch)

If all four steps pass, congratulations! You are officially a member of the Archivists' Guild. The next quest awaits.

The Master Archivist nods with satisfaction.

"Good. You've taken your first steps. You now possess the fundamental tool of every Archivist. In the next quest, I'll take you to the Three Halls of Knowledge - there you'll discover how Git organizes work. Prepare yourself."