Git remotes
To be able to fluently collaborate with a group of people, you need a remote repository that you use together.
The term distributed in distributed version control comes from the fact that you have both local and remote repositories. Each of your co-creators can continue using their local repositories even when the remote one is down for some reason.
Git repositories can be hosted in multiple ways. Probably the easiest option is to use services such as GitHub or GitLab. These hosted services offer many features on top of just the version control.
You can also host your own with something like Gogs or Gitea.
We're now just concentrating on using a remote repository and will use GitLab as an example.
The exercises below work with any provider, but just remember to change the URL accordingly.
Registering with GitLab
You can create a GitLab account for free. The easiest way is to use an existing account, such as Google to sign up, but you can create a separate account too:
Sign up: https://gitlab.com/users/sign_up
Warning
If you opted for using a separate service, such as Google, for the login you will need to create a Personal Access Token to be able to clone a repository using HTTP(S) authentication.
You will need to set the write_repository and read_repository scopes.
Copy the token somewhere safe, but accessible for the time being.
Cloning your first remote repository
When a remote repository exists already and you want to see or modify the contents, you first have to git clone it.
Cloning is similar to init, but is needed when you have a repository initialized elsewhere.
Start off by cloning a few separate repositories.
Jump into the root directory of your git work, if you are still in the repository we created earlier:
cd <my git root>
Example:
$ cd /Users/username/Documents/git/work
Clone an example project form Polar Squad's Gitlab project:
git clone https://gitlab.com/polarsquad/workshops/example-project
If you visit https://gitlab.com/polarsquad/workshops/example-project in a browser, you can see the README written in Markdown format and rendered by Gitlab.
As the project is open for everyone, you don't have to type in any credentials.
You can also clone any other repository you want. It is very common for open source projects to use GitHub, so let's clone Black a code formatter for the Python programming language:
$ git clone https://github.com/psf/black
Cloning into 'black'...
remote: Enumerating objects: 5069, done.
remote: Counting objects: 100% (257/257), done.
remote: Compressing objects: 100% (159/159), done.
remote: Total 5069 (delta 134), reused 194 (delta 98), pack-reused 4812
Receiving objects: 100% (5069/5069), 4.98 MiB | 3.84 MiB/s, done.
Resolving deltas: 100% (3289/3289), done.
If you visit https://github.com/psf/black with your browser again, you'll see a similar README
Creating a remote repository
You won't have write access to either of the above repositories directly. Usually the workflows for open source projects revolve around creating a fork (a copy) of the repository, making your changes and then requesting for the change to be included in the repository.
If however, you happen to have write access to a repository you can just commit and push directly.
With your Git provider of choice, create a new repository. In Gitlab these are created projects and you can initialize by selecting "New project" from the main screen.
Select these settings:
- "Create blank project"
- Project name: my-new-repository
- Visibility level: private
After creation of your blank project, you can still clone it:
git clone https://gitlab.com/username/my-new-repository.git
As the repository is private, git should ask you for access credentials.
Input your username and password (or Personal Access Token, if you created one earlier).
Example:
$ git clone https://gitlab.com/quulah/my-new-repository.git
Cloning into 'my-new-repository'...
Username for 'https://gitlab.com': quulah
Password for 'https://quulah@gitlab.com':
warning: You appear to have cloned an empty repository.
The repository is empty and equal to one created with git init.
Note
A better way to use remote repositories is to authenticate using SSH, but that is out-of-scope for these exercise.
If you are interested in learning about that, you can check out GitLab's documentation on the matter.
Since we used git clone git knew how to connect your local repository with the remote one. You can check the details with git remote -v:
Example:
$ cd my-new-repository
$ git remote -v
origin https://gitlab.com/quulah/my-new-repository.git (fetch)
origin https://gitlab.com/quulah/my-new-repository.git (push)
If you run git remote -v in your previous local repository you will find it not connected to anything.
Note
You can connect a remote to an existing local repository.
Try the following in the earlier repository: git remote add origin https://gitlab.com/username/my-new-repository.git
Pushing changes to a remote repository
After cloning your fresh, new repository you can start creating commits just like with the earlier local one.
Let's take advantage of GitLab's Markdown rendering functionality and write a README.
Change to your repository's directory, and create a file called README.md in the root:
cd my-new-repository
Markdown is a lightweight markup language that you can use to write text files that are human readable as-is, but can be rendered for extra formatting.
In the file, write:
## This is my first Gitlab repository
_Hello_ **World**!
Then git add and git commit as usual.
Example:
$ git add README.md
$ git commit -m "Initial commit"
[master (root-commit) c7af42c] Initial commit
1 file changed, 3 insertions(+)
create mode 100644 README.md
To get this file to GitLab, we need to push the changes. Pushing is similar to what cloning does, but in the other direction.
As you started from scratch, git has trouble connecting the dots. If you just use git push it will complain.
Example:
$ git push
No refs in common and none specified; doing nothing.
Perhaps you should specify a branch.
Everything up-to-date
If we do like it suggests, and add a branch everything will go as expected:
git push origin master
The remote has a name and just like the branches, they can be named anything you want. The default is origin.
Example:
$ git push origin master
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 277 bytes | 277.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To https://gitlab.com/quulah/my-new-repository.git
* [new branch] master -> master
Note
Now that the remote branch is being tracked you can omit the remote and branch name during subsequent pushes.
Now that the changes are pushed, you can check your GitLab project in the browser and see your README.md all nice and rendered.
https://gitlab.com/username/my-new-repository
Pushing to a remote branch
Branches can be commonly created from the services hosting Git, but let's have another stab at making one from the command line and then push it to the remote.
git checkout -b yet-another-branch
In addition to rendering Markdown, GitLab as lots of other features. One of them is CI/CD. By creating a .gitlab-ci.yml file in the repository, you can specify steps that GitLab will then run.
Usually these steps include testing code and building packages, but we'll keep it a bit simpler.
In your new branch, create the .gitlab-ci.yml file with an editor:
Warning
The dot in the beginning is necessary!
For the contents, let's make a very basic pipeline:
image: ubuntu
hello-world:
script:
- echo "Hello world!"
Despite the dot in the beginning, it is a file like any other so add, commit and push.
Example:
$ git add .gitlab-ci.yml
$ git commit -m "My pipeline"
[yet-another-branch 67ead3e] My pipeline
1 file changed, 5 insertions(+)
create mode 100644 .gitlab-ci.yml
$ git push origin yet-another-branch
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Delta compression using up to 8 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 349 bytes | 349.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: To create a merge request for yet-another-branch, visit:
remote: https://gitlab.com/quulah/my-new-repository/-/merge_requests/new?merge_request%5Bsource_branch%5D=yet-another-branch
remote:
To https://gitlab.com/quulah/my-new-repository.git
* [new branch] yet-another-branch -> yet-another-branch
GitLab presents you with an option to do a Merge Request. This is the same as our earlier git merge my-first-branch done locally, but from the GitLab user interface.
Let's get to that in a second, but first check your first pipeline run:
https://gitlab.com/username/my-new-repository/-/pipelines
By clicking the job ID and then the job, you can see the output from your very first pipeline.
Making a merge request
A Merge Request is what GitLab calls the action of merging a branch (or a fork!) to another one.
GitHub calls these Pull Requests, but they are the same thing.
Merge Requests, or Pull Requests, are a way of people collaborating on a project. You can do the merging of branches locally and pushing them to the remote just like we did earlier, but these hosted services offer a bit better workflow and a nicer user experience.
To create a MR, you can click the link offered by GitLab during your first push to the branch.
You can also navigate to: https://gitlab.com/username/my-new-repository/-/merge_requests and click "New merge request".
In the MR, you can comment on people's changes and make code review.
Since we're the only ones working on this, let's click merge and pull in the changes!
Pulling changes from a remote
To get changes from a remote you need to do a git pull. The command itself is actually git fetch + git merge, but we're fine with just using git pull for now.
To get our recently merged changes to the master branch, change to master locally and pull in additions from GitLab:
git checkout master
git pull
Example:
$ git checkout master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.
$ git pull
remote: Enumerating objects: 1, done.
remote: Counting objects: 100% (1/1), done.
remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (1/1), 261 bytes | 261.00 KiB/s, done.
From https://gitlab.com/quulah/my-new-repository
c7af42c..d83095a master -> origin/master
Updating c7af42c..d83095a
Fast-forward
.gitlab-ci.yml | 5 +++++
1 file changed, 5 insertions(+)
create mode 100644 .gitlab-ci.yml
You'll find the pipeline there and GitLab will also run the same job in the master branch now!
Next
That's it for now, continue to the summary for a recap.