Remotes

So far everything has happened on your computer. A remote is another copy of the same repository, usually on a server, that you send commits to and get commits from. By the end of this lesson you can clone, fetch, pull and push, and you know how Git signs in to a server.

A remote is another copy

Git has no central server built in. Every copy of a repository is complete, with the whole history. A remote is another copy that your repository knows the address of. By convention the main one is called origin.

      Your computer                                  Server
 ┌──────────────────────────┐                ┌─────────────────────┐
 │ main         (your work) │   git push ──► │ main                │
 │ origin/main  (last news  │ ◄── git fetch  │                     │
 │               from the   │                │ trip-planner.git    │
 │               server)    │                └─────────────────────┘
 └──────────────────────────┘

Your repository keeps a read-only bookmark for each branch on the remote, such as origin/main. These are remote-tracking branches. They show where the server's branches were the last time you talked to it. They do not update by themselves.

Clone: get a copy

git clone downloads a whole repository, history included, into a new folder. It sets up origin for you and checks out the default branch:

git clone https://git.example.com/asha/trip-planner.git
cd trip-planner
git remote -v

Cloning into 'trip-planner'...
…
origin	https://git.example.com/asha/trip-planner.git (fetch)
origin	https://git.example.com/asha/trip-planner.git (push)

git.example.com stands for your hosting site. You copy the real address from the project's page, usually from a Clone or Code button.

Practise without an account

A remote can be a folder on your own disk. A bare repository has history but no working files, which is what servers keep:

git init --bare -b main ~/git-server/trip-planner.git
cd ~/trip-planner
git remote add origin ~/git-server/trip-planner.git
git push -u origin main

Then git clone ~/git-server/trip-planner.git laptop gives you a second copy to play "the other person" with. The push, fetch and pull examples on this page were made this way.

Push: send your commits

git push uploads the commits on your current branch that the remote does not have yet.

The first push of a branch needs to say where to:

git push -u origin main

To …/trip-planner.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

-u (--set-upstream) links your main to origin/main. That link is the branch's upstream. After that, plain git push and git pull know where to go, and git status compares your branch with it:

On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

Ahead means you have commits the remote does not. Behind means the remote has commits you do not.

BranchPilot sets the upstream for you on the first push of a new branch, labelled Push (set upstream), and shows ahead and behind counts next to each branch. See Fetch, pull and push.

When a push is refused

Someone else pushed to main while you were working. Your push is refused, because it would throw their commit away:

To …/trip-planner.git
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to '…/trip-planner.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref. If you want to integrate the remote changes, use
hint: 'git pull' before pushing again.

This is Git protecting other people's work. The fix is to get their commits first, then push again.

Fetch and pull: get other people's commits

Command	What it does	Changes your files?
git fetch	Downloads new commits and moves the origin/… bookmarks	No
git pull	git fetch, then combines origin/main into your main	Yes

Fetch is always safe: it only updates your view of the server.

git fetch
git status

From …/trip-planner
   7aa942b..9d4081a  main       -> origin/main
On branch main
Your branch and 'origin/main' have diverged,
and have 1 and 1 different commits each, respectively.
  (use "git pull" if you want to integrate the remote branch with yours)

"Diverged" is the same situation as two branches in lesson 3: you have a commit the server does not, and the server has one you do not.

* a207fc6 (HEAD -> main) Add hotel to budget
| * 9d4081a (origin/main) Plan day 3
|/
* 7aa942b Merge branch 'budget'

Pull when branches have diverged

When the branches have diverged, a pull has to merge or rebase. Current Git versions make you choose instead of guessing:

hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
…
fatal: Need to specify how to reconcile divergent branches.

Choice	What a pull then does
git pull --no-rebase (pull.rebase false)	Makes a merge commit joining your work and theirs
git pull --rebase (pull.rebase true)	Replays your commits on top of theirs, for a straight history
git pull --ff-only (pull.ff only)	Only moves forward when you have no commits of your own; otherwise stops

Any of them is a reasonable default; many teams agree on one. Set it once with --global, for example git config --global pull.rebase false. Rebasing is explained in lesson 5. BranchPilot's pull button runs git pull, so it follows the same setting.

After the pull, push again and it goes through.

Fetch first, then decide

git fetch followed by git status and git log --oneline --graph --all shows you what is coming before anything changes. It is a good habit before a pull, and before any force push.

Signing in: HTTPS or SSH

A remote address starts in one of two ways, and that decides how Git proves who you are:

	HTTPS	SSH
Address looks like	https://git.example.com/asha/trip-planner.git	git@git.example.com:asha/trip-planner.git
You prove who you are with	A personal access token, or a sign-in through a credential manager	An SSH key pair; the public key is added to your account
Remembering it	A credential helper stores the token	ssh-agent holds the unlocked key
Works through strict firewalls	Usually, it uses the normal web port	Sometimes blocked

Most hosting sites no longer accept your account password for Git over HTTPS. You create a personal access token in the site's settings, with only the permissions you need, and use it where Git asks for a password. A credential helper (such as Git Credential Manager, which comes with Git for Windows) then remembers it.

With SSH you create a key pair once, keep the private key on your computer and add the public key to your account. After that, no token is needed. SSH keys in the networking track explains how keys work and how to make one.

Cloning a public repository over HTTPS needs no sign-in at all. Pushing always does.

To switch an existing repository from HTTPS to SSH, change the address:

git remote set-url origin git@git.example.com:asha/trip-planner.git

BranchPilot never asks for a password: it uses the credential helper and ssh-agent you already have. If a fetch waits for sign-in, run the same command once in a terminal and sign in there. See When a task waits for sign-in. On Windows, DhivaLabs Shell keeps a separate SSH key for each identity, so work and personal accounts do not get mixed up.

Forks and pull requests

On hosting sites you often cannot push to someone else's project. The usual way to contribute:

 Their repository ──fork──► Your copy on the site ──clone──► Your computer
        ▲                                                          │
        └────── pull request ◄──── push a branch ◄─────────────────┘

1. Fork: the site makes your own copy of their repository under your account.
2. Clone your fork, create a branch, commit, and push the branch to your fork.
3. Open a pull request (GitLab calls it a merge request): a request for the owners to merge your branch. They review the changes, comment, and merge it or ask for changes.

Inside a team that shares one repository, you skip the fork: push a branch to the shared repository and open a pull request from it. Either way, the review happens before the work reaches main.

Stay safe

• Never put a token in a remote address, like https://asha:TOKEN@git.example.com/…. Git saves the address in plain text in .git/config, and it shows up in git remote -v. Let a credential helper store it instead.
• Treat tokens and private SSH keys like passwords. Give tokens only the permissions and lifetime they need, and revoke them when you stop using them.
• Push only to repositories you are meant to. Check git remote -v in a repository you did not create yourself.
• Do not rewrite commits you have already pushed (amend, rebase, reset) on a branch others use. Lesson 5 explains force pushing and why it needs care.

Check yourself

QuizRemotes

Question 1 of 6

What is the difference between git fetch and git pull?

Score: 0

What you learned

• A remote is another full copy of the repository; origin is the usual name for the main one.
• origin/main is your last-known view of the server's main, updated by git fetch.
• git push -u sets an upstream; after that git push, git pull and git status know where to look.
• A refused push means the remote has commits you do not: fetch, combine, then push.
• Fetch never changes your files; pull fetches and then merges or rebases.
• HTTPS signs in with a token through a credential helper; SSH signs in with a key pair.
• Forks and pull requests let you propose changes that the owners review before merging.

Next steps

• Conflicts and rebase
• Fetch, pull and push in BranchPilot
• SSH keys