Arc 2 Quest 09

The Distant Portals

Remote, push, fetch and pull

The Master Archivist takes you to a room you had never noticed. The walls are covered with immense mirrors, but each one shows a different place - a citadel in the mountains, an outpost by the sea, an underground library. At the center of each mirror, a golden light pulses softly.

"Apprentice, you have learned to create branches, to merge timelines, and to resolve conflicts between them. But you have always worked alone, in your own citadel. Yet the Archives of the Guild do not live in a single place. Look at these mirrors - they are Distant Portals. Each one connects our citadel to a Guild outpost somewhere in the kingdom. Through these portals, Archivists send their chronicles and receive those of others. Today, you will learn to master these portals."

What is a remote?

A remote (or remote repository) is another Git repository that yours is connected to. It is a portal to a copy of the Archives that lives elsewhere - on a server, on a colleague's machine, or even in another folder on your own machine.

A remote is a connection to another Git repository. It is the magic portal that allows Archivists to share their chronicles across the kingdom.

When you ran git clone in quest 04, Git automatically created a remote named origin that pointed to the source repository. That was your first portal, even if you didn't know it yet.

List remotes

To see which portals are configured in your repository:

git remote -v

The -v (verbose) flag displays the associated URLs:

origin  /path/to/repo.git (fetch)
origin  /path/to/repo.git (push)

Each remote has two lines: one for fetch (receiving) and one for push (sending). Usually, they point to the same location.

Add a remote

To open a new portal to another repository:

git remote add <name> <url>

Example:

git remote add origin /tmp/portail-central.git

By convention:

  • origin is the main remote (automatically created by git clone)
  • You can add as many remotes as you want with names of your choice

Sending commits: git push

To send your commits through a portal:

git push <remote> <branch>

Example:

git push origin main

This sends all commits from your main branch that do not yet exist on the origin remote.

Setting up tracking with -u

The first time you push a branch, you can set up tracking:

git push -u origin main

The -u option (or --set-upstream) creates a permanent link between your local main branch and the main branch on the origin remote. After that, you can simply write:

git push

Without specifying the remote or the branch - Git will know where to send.

Retrieving changes: fetch vs pull

This is one of the most important distinctions to understand.

git fetch - Observe without touching

git fetch <remote>

git fetch downloads new commits from the remote, but does not modify anything in your work. The changes are stored in tracking branches (like origin/main), not in your local branches.

git fetch is like looking through the portal to see what other Archivists have done, without touching your own scrolls.

git pull - Retrieve and merge

git pull <remote> <branch>

git pull does two things in a single command:

  1. git fetch - downloads new commits
  2. git merge - merges the changes into your current branch

It is like opening the portal, grabbing the scrolls, and integrating them directly into your chronicle.

When to use one or the other?

Situation Command Why
You want to see what changed before deciding git fetch You keep total control
You want to retrieve and integrate immediately git pull Faster, less control
You are working on a sensitive branch git fetch + git merge You inspect before merging
You are alone on the branch git pull No risk of surprise conflicts

As a general rule: git fetch followed by an examination then a git merge is the safest method. git pull is a handy shortcut when you are sure everything will go well.

Tracking branches

When you run git fetch, the retrieved commits are stored in tracking branches. These are read-only branches that reflect the state of a remote.

# View all branches, including tracking branches
git branch -a

You will see something like:

* main
  remotes/origin/main

origin/main vs main

  • main: your local branch. This is where you work.
  • origin/main (or remotes/origin/main): the tracking branch. It is the last known snapshot of the main branch on the origin remote.

After a git fetch, the tracking branch origin/main is up to date with the remote, but your local main branch has not moved. It is up to you to decide when to merge.

# View remote commits not yet merged
git log main..origin/main --oneline

# Merge when you are ready
git merge origin/main

Delete a remote branch

If a branch no longer needs to exist on the remote:

git push <remote> --delete <branch>

Example:

git push origin --delete old-expedition

This deletes the branch on the remote only. Your local branch is not affected.

The recommended workflow

Here is the typical workflow when you collaborate through a portal:

  1. git fetch - Download the latest changes
  2. Examine - git log main..origin/main to see what changed
  3. Merge or rebase - git merge origin/main or git rebase origin/main
  4. Work - Make your own commits
  5. Push - git push to share your work

This cycle repeats throughout the collaboration.

Practical exercise - The Central Portal

"A Guild outpost has just been established: the Central Portal. You will open it, send your chronicles through it, then discover that another Archivist has also contributed through this same portal. It is up to you to retrieve their work and integrate it with yours."

Create a local bare repo, connect it as a remote, push your commits, simulate a second Archivist, then retrieve their changes with fetch and merge.

Step 1 - Create your working repository

mkdir portails-distants
cd portails-distants

# Create your working repository
mkdir citadelle
cd citadelle
git init -b main
echo "# Chroniques de la Citadelle" > chroniques.md
git add chroniques.md
git commit -m "Fonder la chronique de la Citadelle"
cd ..

Step 2 - Create the Central Portal (bare repo)

git init -b main --bare portail-central.git

Step 3 - Open the portal from your citadel

cd citadelle
git remote add origin ../portail-central.git
git remote -v
cd ..

Step 4 - Send your chronicles

cd citadelle
git push -u origin main
cd ..

Step 5 - Another Archivist arrives

# Simulate a second Archivist
git clone portail-central.git avant-poste
cd avant-poste
echo "Outpost report: all is calm at the borders." >> chroniques.md
git add chroniques.md
git commit -m "Add the outpost report"
git push origin main
cd ..

Step 6 - Discover the changes (fetch)

cd citadelle
git fetch origin

# Examine what changed
git log main..origin/main --oneline

Step 7 - Integrate the changes (merge)

git merge origin/main

# Verify the file contains both contributions
cat chroniques.md

Step 8 - Verification

From the citadelle/ folder, run the verification script:

bash verifier.sh
.\verifier.ps1

The script checks:

  1. You are in a Git repository
  2. At least one remote is configured
  3. You have pushed at least once to a remote
  4. You have retrieved changes from a remote

Command summary

Command Description
git remote -v List remotes and their URLs
git remote add <name> <url> Add a new remote
git push <remote> <branch> Send commits to a remote
git push -u <remote> <branch> Push and set up tracking
git fetch <remote> Download without merging
git pull <remote> <branch> Download and merge
git branch -a View all branches (local + tracking)
git log main..<remote>/main View unmerged remote commits
git push <remote> --delete <branch> Delete a remote branch

You gaze at the room's mirrors. Each portal glows with a steady light - the connections are established, chronicles flow freely between your citadel and the Guild's outposts. The Master Archivist nods with satisfaction.

"You now know how to open portals, send your chronicles across the kingdom, and receive the work of other Archivists. You understand the difference between observing and integrating, between fetch and pull. This is an essential skill, for an Archivist who works alone in their tower serves no one. True power comes from collaboration through the portals."