GitLab with Git Essentials - Hands-on Lab: Work With Git Locally

This Hands-on Guide walks you through using Git commands to work with both a remote and local repository.

Estimated time to complete: 45 minutes

Objectives

In this lab you will practice using a repository on your local computer and learning about the following concepts:

cloning a repository
creating, using, and merging a branch
editing and committing a file
pushing and pulling changes to and from a remote repository.

Please take time to understand any code that you are asked to copy and paste in any lab. Ask your instructor to explain any code that’s not clear.

Many of the Git commands used in this lab are summarized in GitLab’s helpful git cheat sheet. This lab will require you to be able to use your local computer to have SSH access to the internet. Please make sure your machine has the required permissions.

Task A. Verify that Git is installed locally

Open a terminal on your computer and type this command:
1

git version
If the output prints a version number, Git is installed. If the command throws an error, see the documentation for installing Git.

Task B. Generate an SSH key

GitLab uses the SSH protocol to securely communicate with Git. When you use SSH keys to authenticate to the GitLab remote server, you don’t need to supply your username and password each time. You can learn more in the documentation.

We will use OpenSSH client, which comes pre-installed on GNU/Linux, macOS, and Windows 10. To check your current version run the following command in your terminal or Powershell:
1

ssh -V
Create a public and private key pair by running this command in your terminal or PowerShell.
1

ssh-keygen
The first prompt will ask you where you would like to save your SSH key. Take note of the location that the command is saving the key to. By default, the path will be ~/.ssh, and the default name will be id_rsa. Press Enter to accept the default key location and name.

If preferred, you can also provide a custom file path and key name for this step.
The second prompt will ask you to set a password for the key file. Press Enter to use a blank passphrase for the local key file.

To keep the steps simple, we are opting to not set a password for the key file. Blank passphrases are not generally considered best practices. You can set a passphrase if desired.

Task C. Add an SSH key to your GitLab profile

Open your browser to the project that you created in Lab 1.

If you closed the tab or lost the link, open a browser tab and start typing https://gitlab.com/gitlab-learn-labs in your URL and the group should appear in your history.
Click your user avatar in the top left corner.
From the dropdown menu, click Edit profile.
In the left-hand navigation pane, click SSH Keys.
Open your existing terminal window. Navigate to the directory that you saved the SSH key in by using cd ~/.ssh and print a list of all files in that directory by using the ls command, as seen below.
1 2

cd ~/.ssh ls
In Windows:
1

cd ~\.ssh
By default, the key will be saved in the ~/.ssh directory. If you saved the key to a different directory, you will need to cd to that directory instead.
You should see two key files: a public key (ex. id_rsa.pub) and a private key (ex. id_rsa). The public key ends with .pub and is what you need to share with GitLab.

Security Warning: You should never share your private key or paste it into any website form field. Only your public key should be shared.
Display the contents of your public key by using the cat id_rsa.pub command as seen below.
1

cat id_rsa.pub
If you used a different file name, you command will be cat <filename>.pub
Copy the content of the file displayed to your screen to your clipboard.
In your web browser in the GitLab Web UI, click the Add new key button.
Paste the public key contents into the Key field.
Type any title you want in the Title field (ex. your computer’s hostname), and click Add key.

Tip: To easily identify where your key is used at, you should use your computer’s hostname or description (ex. alextanuki-m2-mac) if you don’t have a different preferred naming schema.
For Usage type, make sure Authentication & Signing is selected

This usage type allows your key to be used to authenticate with GitLab, as well as for signing commits. You can learn more about signed commits in the documentation
For Expiration date, keep the default date.

It is ideal to set an expiry date on keys and rotate the keys periodically. The recommended value for the key expiration date will depend on your security requirements.
Click the Add key button.
In your terminal, run the following command to test your connection.

If your instance URL includes gitlab-learn-labs/* run:
1

ssh -T git@gitlab.com
If your instance URL includes ilt.gitlabtraining.cloud run:
1

ssh -T git@ilt.gitlabtraining.cloud

If the command completes with a welcome message instead of an error, your SSH key is set up correctly.

Task D. Clone a GitLab project repository to your local computer

When you clone a repository, the files from the remote repository are downloaded to your computer, and a connection is created. You can learn more in the documentation.

Navigate back to the Top Level project that you created in Lab 1.

If you closed the tab or lost the link, open a browser tab and start typing https://gitlab.com/gitlab-learn-labs in your URL and the group should appear in your history.
In the left sidebar, click on Code > Repository.
On the right side of the project repository, click the Code button. Copy the URL under Clone with SSH to your clipboard.
In your terminal or PowerShell window, create a new directory called training in your home directory, and navigate into it via the commands below.
1 2

mkdir ~/training cd ~/training
In Windows:
1 2

mkdir ~\training cd ~\training
Run the git clone command, using the command you copied from Clone with SSH.
1

git clone <Clone with SSH Command>
Move into the repository you just cloned via the cd command. All files in this directory will be tracked by Git, and any Git commands you run in this lab should be run from this directory.
1

cd top-level-project
Show the contents of the directory, including hidden files and directories beginning with a period with the ls -a command.
1

ls -a
Notice the presence of the .git directory. The .git directory stores the metadata and object database for your project.
Check the status of your repository by running the following command:
1

git status
You’ll see nothing to commit, working tree clean in the output, which means the files in this directory have the same contents as the versions of these files that are stored in Git.

Task E. Work on a branch

Branches are versions of a project’s working tree. When you create a new project, GitLab creates a default branch for your repository named main (formerly master) that cannot be deleted. Default branch settings can be configured at the project, subgroup, group, or instance level. You can learn more in the documentation.

Create a new branch called temporary_branch on your computer.
1

git branch temporary_branch
Switch to the branch you just created.
1

git checkout temporary_branch
List all the branches in the repository.
1

git branch -a
To exit the branch list, press q (for quit) on your keyboard.
The red branches are on the remote server, which is the GitLab instance where your repositories are stored at.
The asterisk indicates the branch you are currently on.

Task F. Edit a file

Using any text editor (Visual Studio Code, Sublime Text, notepad, vi, etc.), add this line to the end of README.md and save the file.
```
a line added to temporary_branch locally
```
See if Git has noticed that the file has been modified.
1

git status
The output shows the README file in read, with a status of modified. The red font color indicates that the README file has not been added to Git’s staging area yet.

Task G. Add the edited file to Git’s staging area

Add the file to the staging area using the git add command. If the command is successful, there will be no output.
1

git add README.md
git add doesn’t move README.md on your filesystem, but it does add it to Git’s “staging area”.
Make sure that README.md is now ready to be committed (that is, it has been successfully staged).
1

git status

You will now see that the README file has a green font color. This indicates that the change is now tracked in Git’s staging area.

Task H. Commit the edit

Commit the staged file using the git commit command below. It is important to have a descriptive commit message with each commit.
1

git commit -m "Add a line to README.md"
You have now created a snapshot of the file that you can refer to later, if needed.
Make sure the staging area is empty again.
1

git status

Task I. Push your changes to the GitLab instance

Create a new branch in the remote Git repository on the GitLab server called temporary_branch, and push your changes to that branch using the git push command.
1

git push -u origin temporary_branch
If you’re ever unsure of the exact command to push your changes to the remote server, type git push and Git will output an error message with the correct command for you to copy and paste.

Task J. Edit, commit, and push the file again

In your local machine’s text editor (not GitLab’s in-browser editor), add this new line to the end of your local copy of README.md and save the file.

a second line in README.md
In your terminal, move the edited file to Git’s staging area via the git add command.
1

git add README.md
Commit the staged file using the git commit command. Make sure you have a descriptive commit message, or feel free to use the example below.
1

git commit -m "Modify README.md"
See a description of the commit you just made by using the git log command.
1

git log
Press q to exit the git log output screen.
Push your commit up to the remote repository on the GitLab instance by typing in the git push command.
1

git push
To commit your changes to the upstream branch (that is, an already-existing branch on the remote repository with the same name as the branch on your local machine), you can just run git push instead of the longer command you used the first time you pushed your commit up to the GitLab instance. The system only needs to set the upstream branch once.
Navigate to your project in the GitLab Web UI.
Once you’re on the project’s main page, navigate to Code > Branches.
Click on temporary_branch to switch to that branch. Confirm that the changes you made to README.md on your local branch were pushed up to the remote repository.

To see all of the changes applied, click the History button. This will show all of the commits applied to a branch.

Task K. Edit a remote branch

Let’s simulate someone else in your organization making a change to the temporary_branch that lives in the remote repository on the GitLab instance. When we’re done with this section, the remote and local versions of temporary_branch will be different: the code on that branch will have moved under your feet (so to speak). In the section after this one, we’ll see how to reconcile this difference.

In GitLab, navigate to the Top Level Project landing page. If you’re not already on temporary_branch, go to the left-hand navigation pane and click on Code > Branches > temporary_branch.
You are now looking at files in temporary_branch. Click README.md to see its contents.
Click Edit > Edit single file in the top right corner to edit the file.

Add a new line to the end of the file.

a third line added on the remote copy of temporary_branch

Enter an appropriate commit message.
Set the target branch to temporary_branch.
Click the Commit changes button.

After making this commit, the remote repository on the GitLab instance is now one commit ahead of your local repository.

Task L. Get metadata about changes to the remote temporary_branch

Your local temporary_branch is out of sync with the remote temporary_branch on the GitLab instance. The git fetch command gets the updated state of remote branches without updating the contents of your local branches. In other words, it tells you how many commits your local branches are behind the remote branches, but it doesn’t make any changes to the files in your local branches.

Retrieve metadata about branches on the remote copy of the repository using the git fetch command.
1

git fetch
Find out how many commits are in the remote copy of the repository but not your local copy, or vice versa.
1

git status

You will see that your branch is one commit behind in the git status output.

Task M. Pull from the remote repository

You need to update the contents of your local copy of temporary_branch by merging in changes from the remote copy of temporary_branch.

In your terminal, merge the remote copy into your local copy using the git pull command.
1

git pull
View the updated contents of the file by typing in the cat README.md command. You should see the fourth line that you added in the GitLab Web IDE.
1

cat README.md

Task N. Merge changes back into the main branch

Now that your local temporary_branch is identical to the remote temporary_branch, you can merge it into your local main branch. This will add your edits to the stable codebase that lives in main.

See what branch you are currently working on by typing in git branch.
1

git branch
Switch to the main branch by using the git checkout command in the terminal.
1

git checkout main
Incorporate all changes from your local temporary_branch (in this case, just the modified README.md) into your local main branch by typing in git merge temporary_branch.
1

git merge temporary_branch

Task O. Update the remote repository

Make sure there are no edited files that you need to stage or commit and to confirm that you are on the main branch by typing in git status.
1

git status
Update the remote copy of the main branch with any changes from your local copy by typing in git push.
1

git push
Return to the GitLab page in your browser and view README.md in your project’s main branch to view the changes you just pushed to the remote copy of main.

Lab Guide Complete

You have completed this lab exercise. You can view the other lab guides for this course.

Suggestions?

If you’d like to suggest changes to the lab, please submit them via merge request.

Last modified April 26, 2024: Update Lab Descriptions (05f28a88)

View page source - Edit this page - please contribute.