The previous lesson made clear what a remote is: a short name for a URL. Now we have to create one. And we get to do it with the case we have been postponing for three modules: Ana is going to publish task-manager.

Until today the project has lived entirely on her Ubuntu laptop. It has a respectable history — four base commits, two merges, a squash, a resolved conflict — and main sits at c2a8f1e. In lesson 02-02 we watched Bruno clone the project and saw that the clone registered a remote called origin without anybody asking it to. That lesson explained half the story: how a remote is inherited. This one explains the other half: how to create one from scratch, which is what Ana needs now, because her repository was born with git init and has never spoken to anybody in its life.

We will also open .git/config and pick apart the line fetch = +refs/heads/*:refs/remotes/origin/*. It is called a refspec, it appears in every repository in the world and hardly anyone knows what it says. Understanding it is what turns fetch and push from magic commands into predictable ones.

1. The starting point: a repository with no remotes
2. git remote add: registering the first one
3. git remote -v: which remotes do I have
4. git remote show: the full X-ray
5. How it ends up in .git/config
6. The refspec, explained calmly
7. Renaming, removing and changing the URL
8. set-url --push: read from one place, write to another
9. Working with several remotes
10. init versus clone: two ways of having a remote

Ana is in her project, exactly as we left it at the end of module 3:

And now the question of the day:

Silence. There is no remote configured, which is exactly what you would expect in a repository created with git init. We can confirm it by looking at the disk:

Four lines of basic configuration and no [remote …] section at all. Compared with Bruno's .git/config that we saw in lesson 02-02, both the remote section and the branch tracking section are missing here.

Before we go on, somebody has to have created the destination repository. In a real case, Ana would go into the web interface of GitHub, GitLab or the company's Gitea and click "New repository", getting a URL back. To practise without depending on anything, we set up the exact equivalent with what we learnt in the previous lesson:

Important: the destination repository is empty. Not one commit, not one branch. That is normal and desirable: publishing a project means pouring your history into a freshly created repository.

In the narrative we will use the team's real URL, https://git.example.com/team/task-manager.git; in the commands you can reproduce, the local path. They are interchangeable: as far as Git is concerned, both are valid URLs.

The syntax is as simple as the concept:

Ana runs it:

Absolute silence, which in Git means success. And rightly so: nothing has happened beyond writing three lines into a text file. It has not connected anywhere, has not checked that the URL exists, has not downloaded anything and has not asked for credentials.

Let us prove it in the most emphatic way possible:

Git accepts it happily. git remote add is a purely local, offline operation. Only when you run fetch or push against that name will Git discover that the URL leads nowhere. This detail explains a lot of bafflement: people believe "the remote must be fine because git remote add did not complain", when that command never complains about a bad URL.

Let us clean up the experiment:

• It must be unique within the repository: if origin already exists, git remote add origin … fails with error: remote origin already exists.
• It accepts letters, numbers, hyphens and underscores. Avoid spaces, slashes and accented characters.
• There are no reserved words. origin is pure convention, as we saw in 04-01.

With -f (fetch), Git registers the remote and immediately runs a git fetch against it. It is a handy shortcut when you add a remote that already has content and you want it straight away. In Ana's case it adds nothing, because the destination repository is empty.

The two basic query commands:

Names only. And the useful version:

Why does the same remote appear twice? Because Git stores the read URL (fetch) and the write URL (push) separately. They are usually identical, which is why the line repeats, but they can differ: we will see that in section 8, and there the output of -v stops being redundant and becomes informative.

git remote -v should be your first reflex when you land in somebody else's repository, along with git status and git log --oneline -5. In three seconds it tells you who that repository talks to.

This command is in another category, and it is worth understanding why:

This one does hit the network. Unlike git remote -v, which only reads your .git/config, git remote show queries the server to ask which branches it has right now. With no connection or with failing credentials, this command fails.

Since Ana's repository is still empty, the output is sparse. Let us look instead at the one Bruno gets later on, once there is content, because that is the one that teaches you something:

It is worth reading line by line, because it packs in five separate pieces of information:

The three possible states of a remote branch deserve an explanation:

• tracked: it exists on the server and you hold its local reference. The normal situation.
• new: it exists on the server but you do not have it yet. Somebody created it since your last fetch.
• stale: you hold the reference but it no longer exists on the server. Somebody deleted it there. You clear it out with git remote prune, which we will see in lesson 04-04.

If you want the information without going out to the network:

With -n (no query), Git shows only what it knows from its local configuration. It is fast and works offline, but the list of remote branches will be the one from your last synchronisation, not the real one.

Let us go back to the file, which is where you really see what has happened:

That is everything git remote add did. A new section with two keys. You can edit it by hand in any editor and it will work just the same; the git remote commands are nothing more than a convenient interface for writing into this file.

The same keys can be queried and modified with git config, because they are perfectly ordinary configuration:

Remember from lesson 01-05 that these keys live at the local level (.git/config), the most specific of the three. A remote belongs to one particular repository, and configuring it with --global would make no sense at all.

And now, that second line.

This line appears in every Git repository on the planet and hardly anyone could explain it. That is a shame, because it is straightforward and because understanding it lights up the whole module. It is called a refspec: a specification of how the other repository's references are translated into references of your own.

A refspec has three parts:

Read out in plain English:

"Take every branch from the remote and store it on my disk under refs/remotes/origin/, overwriting whatever is there."

Concrete examples of the translation the asterisk performs:

Here is where the slash in origin/main comes from, the question left open at the end of module 3. It is not an arbitrary separator or a special syntax: it is the real path of the file inside .git/refs/. origin/main is called that because it sits at refs/remotes/origin/main.

It might look like an unnecessary detour. Would it not be simpler for the server's branches to be copied straight onto your local branches?

No, and for a fundamental reason: they would be the same references and would trample each other. If the server's refs/heads/main were copied over your refs/heads/main, every fetch would destroy your unpushed local work. The separate namespace is what allows three things to coexist:

• Your main, which you control and where you commit.
• Your photograph of their main (origin/main), which Git updates.
• Their main, which is on another machine.

It is also what makes it possible for Git to tell you "you are 2 commits ahead": it holds the two references separately and can compare them.

The + modifier means "update this reference even when the change is not a fast-forward".

Remember from module 3 that a fast-forward is a clean advance: the new value is a descendant of the old one. Without the +, Git would refuse to update origin/main if somebody had rewritten history on the server (with a push --force, say), because the new commit would not be a descendant of the one you had recorded.

For remote references we want the +: their job is to faithfully reflect the server's state, whatever it happens to be. If the server changed in a strange way, your photograph must show that strange state; you can then decide what to do with your local branches. Protection against rewrites applies in the other direction, when pushing, and it is the subject of lesson 04-05.

The default refspec brings all the branches, but it can be narrowed down. If a repository has hundreds of branches and you only care about main:

No wildcard: that branch only. This is in fact what git clone --single-branch does internally, as mentioned in lesson 02-02.

You can stack several lines to bring in several groups:

Now git fetch origin will bring main and every release branch, and ignore the rest. In a corporate repository with seven hundred open branches, that is the difference between a two-second fetch and a thirty-second one.

The same concept comes back when pushing. When you write git push origin main:main in lesson 04-05, you will be supplying a refspec by hand, in the same source:destination syntax. The consistency is complete: the two sides of : always mean the same thing, "from here" and "to here".

Three maintenance operations, all local, all instant and none of them dangerous.

And this is not just a change of label. Renaming a remote forces Git to rewrite everything that depended on the name:

• The remote references move from refs/remotes/origin/* to refs/remotes/central/*. Your origin/main becomes central/main.
• The refspec is updated to point at the new namespace.
• The branches' tracking configuration (branch.main.remote) is rewritten so that main keeps pointing at the right remote.

All consistent. Git has done the complete job. Let us go back to the conventional name:

Removing a remote deletes its section from .git/config, all its remote references (refs/remotes/<name>/*) and the tracking configuration of the branches that used it.

What it does not delete: not a single commit. The objects stay in .git/objects/. If you remove a remote by mistake, just add it again and run fetch; the only thing you lose is time.

This is the most frequent case in real life: the company migrates servers, or you move from HTTPS to SSH after setting up your keys.

Same repository, same history, same references: only the route to get there changes. Nothing else is affected, because a commit's identity lies in its hash, not in the URL it arrived from.

This is where that idea from lesson 04-01 becomes tangible: the "official" repository is official by convention. Migrating a whole team to another server is one set-url per person.

A twist that explains why git remote -v distinguishes (fetch) from (push):

Ana now reads over HTTPS and writes over SSH. Both paths lead to the same repository, but by different routes.

What is this good for in practice?

• Reading without credentials, writing with them. A public repository is cloned over HTTPS without authenticating; pushing requires an identity, and SSH supplies it without typing anything (lesson 04-03).
• Corporate firewalls. On some networks only port 443 for HTTPS is open outbound, but pushing goes by another route.
• Read-only mirrors. Read from a fast, nearby replica, always write to the original.
• Preventing accidental pushes. There is a well-known trick: point the push URL at something invalid so that no accidental push ever gets through.

Good insurance when you clone somebody else's project purely to read it.

To undo any of these settings:

And the related options, to round out the picture:

With two push URLs, a single git push sends to both places. It is the simplest way to keep a mirror in sync without external tools.

A repository can have as many remotes as you like, and that is no oddity: it is the norm as soon as a project grows a little.

Suppose Bruno also keeps a personal copy of the project and the team deploys by pushing to a staging server:

Each remote has its own reference space, completely separate:

Now origin/main, personal/main and staging/main are three different references that can point at three different commits. And you can compare them like any other reference:

That last case illustrates what we were saying in 04-01 about Git's distributed nature. If Ana and Bruno are sitting in the same room working together:

No server in the middle, nothing published. It is Git doing exactly what it was designed for.

And one useful command when you have several:

We close with the comparison that makes sense of the whole lesson, because it is the difference between Ana's path and Bruno's.

Both paths arrive at the same place. clone is nothing more than init + remote add + fetch + switch, packed into a single command, just as we broke it down in lesson 02-02. You now have the loose pieces and can assemble them by hand:

That last git switch main deserves a note: even though no local branch called main exists yet, Git sees that origin/main does, works out what you mean and creates the local branch with its tracking already configured. It is called DWIM (Do What I Mean) and it is the subject of lesson 04-06.

Ana's repository now has its remote:

But she has not pushed anything yet. And if she tried right now against a real server over HTTPS, she would run into this:

A question she cannot answer, because her web-interface password probably will not do. Authentication has to be sorted out before pushing, and that is exactly the subject of the next lesson.

Mistake 1: believing that git remote add validates the URL. It does not: it only writes to a file. You can register https://this.does.not.exist/nothing.git without a single warning. The first real check comes with git fetch, git push or git ls-remote.

Mistake 2: error: remote origin already exists. This happens when you try to add a remote that is already there, very typical in cloned repositories where origin comes preset. If what you want is to change its address, the command is git remote set-url origin <url>, not add.

Mistake 3: confusing git remote -v with git remote show. The first reads your configuration and works offline; the second asks the server and can fail because of the network or credentials. To diagnose "which URL do I have configured?" use -v; for "what is on the server right now?", show.

Mistake 4: not understanding the refspec, and therefore not understanding why origin/main is not a branch. The line +refs/heads/*:refs/remotes/origin/* says literally where the remote's references are stored: in a namespace separate from your branches. Without that separation, every fetch would flatten your work.

Mistake 5: trying to git push to a non-bare remote. If you set up the server yourself with git init instead of git init --bare, the push will be rejected with branch is currently checked out. Remember lesson 04-01: repositories that receive pushes must be bare.

Mistake 6: letting dead remotes pile up. After a server migration, plenty of people add the new one and leave the old one in place. Months later, git fetch --all takes forever waiting for a switched-off server to time out. Clean up with git remote remove.

Tip 1: check a freshly added remote with git ls-remote. It is the cheapest way to verify that the URL, the network and the credentials work, without downloading any objects:

If it returns the server's list of references, everything is in order. If it fails, you get the specific error before having invested anything.

Tip 2: always use origin for the main repository. The convention is so entrenched that any documentation, script or colleague will assume it. Save your creativity for the secondary remotes.

Tip 3: build git remote -v into your arrival routine for a repository. That command and git log --oneline --graph -10 give you the complete map of where you are in five seconds.

Simulate Ana's case from start to finish, locally:

1. Create a normal repository with two or three commits and one extra branch.
2. Check that it has no remote.
3. Create a bare repository to act as the server.
4. Register it as origin.
5. Show the contents of .git/config before and after, pointing out exactly which lines the command added.
6. Verify with git ls-remote that the remote responds, and explain what it returns while the server is empty.

Translate each of these refspecs into plain English and say what a git fetch would do with each one:

1. +refs/heads/*:refs/remotes/origin/*
2. +refs/heads/main:refs/remotes/origin/main
3. refs/heads/main:refs/remotes/origin/main (without the +)
4. +refs/heads/release/*:refs/remotes/origin/release/*
5. +refs/tags/*:refs/tags/*

Then configure number 4 in a test repository and demonstrate with commands that a fetch no longer brings branches that do not start with release/.

Set up this situation and solve it with commands:

1. A bare team.git and another bare personal.git.
2. A working repository with both registered as origin and personal.
3. Push a different commit to each one, so that their histories diverge.
4. Answer: which commits does personal have that origin does not? And the other way round?
5. Configure the repository to read from origin but push to personal, and demonstrate that it works.

Solution 1:

The two new lines are the [remote "origin"] section with its url and its fetch. Nothing more. No references, no objects, no connection.

The absence of output is the correct answer: the server replied and its list of references is empty, because the bare repository does not have a single commit yet. What matters is that the exit code is 0: it means Git got there and was able to talk. Compare it with a bad URL:

Solution 2:

1. +refs/heads/*:refs/remotes/origin/* — "Bring every branch from the remote and store them under refs/remotes/origin/, forcing the update even when it is not a clean advance." This is the default behaviour of any clone.

2. +refs/heads/main:refs/remotes/origin/main — "Bring only the main branch and store it as origin/main." The server's other branches are ignored entirely; they will not even show up in git branch -r. Equivalent to --single-branch.

3. refs/heads/main:refs/remotes/origin/main — The same, but without the +: if history were rewritten on the server's main, the fetch would fail instead of updating the reference, because the new value would not be a descendant of the old one. You rarely want this on a remote reference, whose job is to mirror the server as it is.

4. +refs/heads/release/*:refs/remotes/origin/release/* — "Bring only the branches whose name starts with release/ and keep them with the same structure under origin/release/." Useful in huge repositories where only the release branches matter to you.

5. +refs/tags/*:refs/tags/* — "Bring every tag from the remote and store them as local tags, under the same name." Notice that here there is no namespace translation: source and destination are the same. Tags are not separated per remote the way branches are, and that is why a fetched tag is indistinguishable from one you created yourself. Tags are the subject of lesson 05-05.

Checking case 4:

origin/main and origin/docs/update-notes do not appear. The restricted refspec has left them out: Git did not even bother to fetch them.

Solution 3:

Each one has a commit the other does not: they have diverged from the common initial commit. You can see it all at once:

One exclusive commit on each side. This three-dot syntax and how to read it are the subject of lesson 04-06.

Confirmed: origin reads from team.git and writes to personal.git. It is the mechanism used by people who clone somebody else's project read-only and push their changes to their own copy.

In this lesson Ana took the step she had been putting off for three modules: connecting her repository to the world. What you have learnt:

• git remote add <name> <url> registers a remote, and it is a purely local operation: it writes three lines into .git/config, does not validate the URL and does not touch the network. The first real check comes with fetch, push or git ls-remote.
• git remote -v lists the remotes with their read and write URLs, offline. git remote show <name> does query the server and gives you the full X-ray: default branch, remote branches with their status (tracked, new, stale) and the pull and push configuration.
• Everything lives in .git/config, in a [remote "origin"] section with two keys: url and fetch.
• The refspec +refs/heads/*:refs/remotes/origin/* says: "bring every branch from the remote and store them under refs/remotes/origin/, forcing the update". The + allows non-fast-forward updates; the : separates source from destination. That is where the slash in origin/main comes from: it is the real path of the file. And that namespace separation is what stops a fetch from flattening your local branches.
• Renaming, removing and changing the URL are local, harmless operations. Renaming also moves the remote references and rewrites the tracking configuration; removing deletes no commit.
• set-url --push lets you read from one place and write to another, or block pushes by pointing at an invalid URL.
• Several remotes coexist without any trouble, each with its own reference space, and they are compared with one another like any other commit name.
• init versus clone: the first requires registering the remote by hand; the second inherits it. Both arrive at the same place, because clone is init + remote add + fetch + switch.

Ana's remote is configured, but if she tried to push right now she would hit an uncomfortable question: Username for 'https://git.example.com':. Registering a URL does not grant permission to write to it.

In lesson 04-03: Authenticating with Remote Repositories we take down that wall. We will see why cloning a public repository asks for nothing while pushing does, what a personal access token is and why it replaced the password, how to generate and use an SSH key with ssh-keygen -t ed25519, and how each operating system stores credentials so that you do not have to type them forty times a day. It matters especially for Carla, who is about to join from Windows 11 and needs this sorted out before writing her first line of code.