Ctrl+K

1.5 Remote Repositories

1.5 Remote Repositories#

In this section, you will see how to create and manage your first remote repository with GitLab, including remote configuration, pushing changes, and cloning repositories.

Creating a remote repository in GitLab#

Let’s start by setting up your local project to push changes to a remote repository on GitLab.

Inside the my-project directory, we will tell Git that we want to work with a remote repository on GitLab. Even though we have not created the remote repository yet, we can still configure the local repository to push changes to it. If the repository does not exist, GitLab will create the remote repository when we push the first changes.

Adding a remote repository to your local repository#

To add a remote repository, use the remote add <short name> <url> command. This command adds, to your local repository, a reference to a remote repository. We will follow the convention of using origin as the short name of the remote repository. For the URL we will use the HTTPS URL of the remote repository on GitLab.

For GitLab user msdp.book, and a repository named my-project, the command to add the remote repository would be:

git remote add origin https://gitlab.com/msdp.book/my-project.git

Note

  • For the URL, we used the HTTPS URL of the remote repository. You will be prompted for your credentials when pushing or pulling.

  • If you used Single Sign-On (SSO) to log in to GitLab, you will need to create a personal access token with the api scope and use it as your password when prompted.

  • If you want to use SSH instead of HTTPS, you can use the SSH URL of the remote repository. Conventions:

  • We used origin for the remote repository reference.

  • We used the name of the local repository (my-project) for the name of our remote repository. These are two common conventions but you can use any names you want.

List remote repository connections#

Git provides the remote command to list the remote repositories linked to your local repository.

git remote

origin

With the -v option, you can see the URLs used for fetching and pushing data.

git remote -v

origin	https://gitlab.com/msdp.book/my-project.git (fetch)
origin	https://gitlab.com/msdp.book/my-project.git (push)

  • (fetch): This specifies the URL used for fetching data from the remote repository. Fetching involves downloading objects and refs from the remote repository to update your local repository’s history.

  • (push): This indicates the URL used for pushing data to the remote repository. Pushing involves sending your local commits to the remote repository to update its history and potentially update branches on the remote.

Inner workings: remote config#

If we inspect the .git/config file, we can now see the configuration for the remote repository.

cat .git/config

[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
[remote "origin"]
	url = https://gitlab.com/msdp.book/my-project.git
	fetch = +refs/heads/*:refs/remotes/origin/*

Checking references#

Even though we configured the remote repository, we have not yet pushed any changes to it. Therefore, the .git/refs directory does not contain any references to the remote repository. If we look into the .git/refs directory to see references, we still only see heads and tags.

ls .git/refs

heads  tags

Pushing to the remote repository#

Push your changes to the remote repository on GitLab, setting origin as the upstream for main.

git push -u origin main

Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 96 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (9/9), 763 bytes | 763.00 KiB/s, done.
Total 9 (delta 0), reused 0 (delta 0), pack-reused 0
To https://gitlab.com/msdp.book/my-project.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

Now that we have pushed our changes to the remote repository, we can see the branches and commits in the remote repository. You can go to the GitLab website and navigate to the my-project repository to see the changes.

Inner workings: remote refs#

After pushing, if we inspect the .git/refs again we see that the remotes directory has been created and now contains a reference to the remote repository.

ls .git/refs

heads  remotes  tags

ls .git/refs/remotes

origin

Listing branches and commits#

git branch --all

  feature
* main
  remotes/origin/main

git log

commit 3484e86d59bb0b402abc8a73ade2b1c86bb6a0ee (HEAD -> main, origin/main)
Author: msdp-book <msdp.book@gmail.com>
Date:   Sat Aug 9 13:10:59 2025 +0200

    Add third line to file1.txt

commit 55fac8297a1e5af85d855da4c497fde7e15d40cc
Author: msdp-book <msdp.book@gmail.com>
Date:   Sat Aug 9 13:10:57 2025 +0200

    Add second line to file1.txt

commit df6b154238d004670d31691a2e0ef484bad25d33
Author: msdp-book <msdp.book@gmail.com>
Date:   Sat Aug 9 13:10:49 2025 +0200

    Create file1.txt with the first line

What to notice

  • We see a new branch origin/main which is a reference to the main branch in the remote repository.

  • origin/main points to the same commit as main.

Cloning a repository#

Clone the my-project into a new directory named my-project-remote.

cd ..
git clone https://gitlab.com/msdp.book/my-project.git my-project-remote
ls

Cloning into 'my-project-remote'...
remote: Enumerating objects: 9, done.
remote: Counting objects: 100% (9/9), done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 9 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Unpacking objects: 100% (9/9), 747 bytes | 74.00 KiB/s, done.
my-project  my-project-remote

Deleting a remote repository#

To delete the remote repository in GitLab, navigate to the repository settings and click on the General. Navigate to the Advanced section and click on Expand. At the bottom of the page, you will find the Delete project button. Click on it and confirm the deletion.

Contents