Last updated on 2022-05-06 | Edit this page
- How can I use GitLab to manage my project’s files?
- Create a project.
- Change name, description, visibility, and avatar of a project.
- Push a local Git repository to a newly created project.
- Archive (or delete) a project.
Creating a Project
After knowing how to find groups and projects. We want to go from passively browsing GitLab to actively using it. We are going to create a project and connect a local Git repository to it.
To create a project, click on the button with the “+” symbol in the top menu bar and select “New project/repository”.
Multiple options are presented for how to create the new project. In this lesson we will only look at, and use, the first option: “Create blank project”. So click on that.
This leads to the following page:
The “Project name” field is for just that, the project name. Its value has no other purpose and can be changed at anytime without indirect consequences (the direct consequence being, that its name will be different). We will call it “Research Diary”.
As we fill in the project name, a project slug gets suggested in the respective field. The project slug is the last part of the project’s, and the associated Git repository’s, URL or web address.
If the user belongs to at least one group, the URL’s middle part can be chosen in the drop-down field labeled “Project URL”, which defaults to the current user’s username. This is the location for a user’s project (and groups). Other options in the drop-down list are the groups in which the current user may create projects.
Project URL and Project Slug
The two fields under labels “Project URL” and “Project slug” are the only fields in this form for which changing the value later might cause problems. Since they determine the URL under which the project’s pages and the project’s Git repository can be found, changing them later might brake links and bookmarks as well as connections from Git repositories on other systems, for example on contributors’ machines.
The project description appears in many lists and on some pages under the project’s name. We add a concise description: “My research diary, a collection of Markdown files”
Markdown is a markup language, like HTML on which the World Wide Web is based or wikitext used to write Wikipedia’s content. Its markup directives, indicating for example that something is a headline or a list item, are such that they serve their purpose even in the plain text form.
There exist many variants (or flavors) of Markdown and GitLab has its own. Other than for rendering Markdown files in repositories on its web interface, GitLab allows for Markdown input in many of its interface’s text fields, such as issue descriptions or comments.
This will be pointed out as we get to use these fields during the lesson.
We ignore the field labeled “Project deployment target (optional)”.
The choice of radio button under label “Visibility Level” determines the project’s visibility. As mentioned in the previous episode “Finding Projects and Groups”, the visibility “Internal” is disabled on GitLab.com, so only “Private”, the default, and “Public” are available. We choose “Private”.
If, as per default, the checkbox “Initialize repository with a README” is checked, the project’s repository will be initialized with a commit that adds a file called
README.md. Otherwise, a the project will start with an empty repository. We will be adding such a file later ourselves, so we uncheck the box.
A project’s README file usually contains basic information about the project: what it contains, how it can be used (for example build or installed, if it is a software project), how to contribute, how to get help, and licensing information.
It is common to write README files in Markdown format, indicated by the filename suffix
Platforms like GitLab show the contents of a project’s README file on its homepage; if it is in Markdown format, in its rendered form.
We will ignore any other fields that may be visible depending on the GitLab instances configuration.
After clicking the “Create project” button, GitLab creates the project and redirects us to the project’s homepage, which looks similar to this:
The page is split into the menu on the left and the project overview on the right.
The menu leads to pages related to various properties, processes, and content of the project. It is visible on each of these pages. The number of menu entries may seem overwhelming, in particular when one notices that the entries have subentries. However, it is not necessary to know what hides behind all these entries to use GitLab. Following this lesson, we will get to know parts of what lies behind the entries “Project Information”, “Issues”, “Merge requests”, “CI/CD”, “Wiki”, and “Settings”.
The project overview shows (from the top): The project’s avatar (or icon), name and description; a prompt to invite team members (we will cover members later on); a statement that our repository is currently empty with buttons for several options to add content to it; and finally the beginning of the instructions on how to push a local repository to this project’s repository to fill it with content. We will follow them in just a bit.
The project overview page will look slightly different, once we have content in its repository. We will have another look at the page then.
Change Name, Description, Visibility, or Avatar
Click on the “Settings” menu entry and change any of the project’s name, description, visibility, and avatar. Do not forget to click the “Save changes” button once you are done.
This exercise should take about 5 minutes.
The project overview page presents us with many options to add content to the project’s repository directly in GitLab. However, we will fill the project from a local Git repository. To do that, we need a local Git repository with some content.
Before we initialize a local Git repository, we make sure that Git is properly configured.
To check for our name and email address, We run
$ git config --global --get user.name
$ git config --global --get user.email
If both return sensible values, we are good to go. Otherwise we provide the missing values, for example:
$ git config --global user.name "Some Novice" $ git config --global user.email "firstname.lastname@example.org"
It is now common to name the default branch
main, rather than
master as is still the default in Git. For more information see, for example, the announcement of GitLab to change the default branch Since the discussion on this topic has started, Git has introduced a configuration value for the initial branch created by the
git init command. We will use this, to make sure that all future repositories created locally start with a branch called
$ git config --global init.defaultBranch main
Creating a Local Repository
In Markdown, headlines are marked by one up to six
# characters followed by a space character in front of the text. The number of
# characters indicates the heading’s level, with 1 being the most significant.
For example, a level 3 headline:
### Interesting Section Title
Research Diary’s Initial Content (Required)
Create a Git repository anywhere on your computer. Add a README file in markdown format that describes the repository’s future contents.
Remember to use a good commit message for your commit.
This exercise should take about 10 minutes.
We start by creating and navigating to a new directory,
research-diary. There we initialize a git repository.
$ mkdir research-diary $ cd research-diary $ git init
Next we create a file called
README.md with the following content using our preferred text editor.
# Research Diary This repository contains our research diary. Each day gets its own file. We use the Markdown format for our files.
Finally, we stage the added file using and create a commit.
$ git add README.md $ git commit -m "Add README.md"
Checking the status of the git repository, we should see that it exists and that there are no changes in the working directory or in the stating area:
$ git status
On branch main nothing to commit, working tree clean
There is one file,
Connecting Local and Remote Repository
Having thus created our local repository, we want to save it to our repository in GitLab. To that end, we have a look at the project overview page again; this time at the instructions toward the bottom of the page. They read:
Git global setup
git config --global user.name "Some Novice" git config --global user.email "email@example.com"
Create a new repository
git clone https://gitlab.com/somenovice/research-diary.git cd test git switch -c main touch README.md git add README.md git commit -m "add README" git push -u origin main
Push an existing folder
cd existing_folder git init --initial-branch=main git remote add origin https://gitlab.com/somenovice/research-diary.git git add . git commit -m "Initial commit" git push -u origin main
Push an existing Git repository
cd existing_repo git remote rename origin old-origin git remote add origin https://gitlab.com/somenovice/research-diary.git git push -u origin --all git push -u origin --tags
We already covered the global setup.
The next three sets of instructions are mutually exclusive. The first is not for us, because we already created a repository. Neither is the second, because although we have a directory with contents, its already a Git repository. That leaves us with the third option, which is the one applicable to our situation: “Push an existing Git repository.”
Transferring our changes to a remote repository is called pushing, because we are sending the changes from us, the local repository, to somewhere else, a remote repository. Later on we will “pull” changes from a remote repository, completing the analogy.
Going back to the shell, we configure our project’s repository as a remote in our local repository:
$ git remote add origin https://gitlab.com/somenovice/research-diary.git
https:// vs git@
We assume throughout this lesson that the user has no SSH key is configured, because we do not want to make the setup of such a key a prerequisite.
If however, a user has configured an SSH key for their account, GitLab would default to showing links to repositories in the form for Git over SSH instead.
For example, without a configured key GitLab shows
for our example repository, whereas with a configured key it would show
The HTTPS link still works if a SSH key is configured, it is only no longer shown by default.
We instruct Git to add a remote called
origin with the last part as the address. Make sure to copy that last part from the project overview page, because it represents the Git address of your project’s repository on GitLab. It will be different for everyone.
Note also, that we skipped the second line of the instructions. It renames an existing remote
old-origin, but we have no existing remote.
Names for remotes
Apart from following restrictions that Git puts on remote names, which can be avoided without much thought by using only letters, numbers, underscores, and hyphens, we should choose meaningful names for remotes, in particular, when we add multiple remotes to a local repository.
In most examples,
origin is used as the name for a remote, because it is the name of the remote created when cloning a repository. It is a meaningful name for the main remote repository, if there is one. This together with its ubiquitous use make it a very good name.
In other cases, we might call a remote to a private copy of the main repository after our username or server it is located on, for example
uni for a university GitLab instance.
Finally, we push our changes to the remote repository. The command will prompt for our user name and password:
$ git push -u origin --all
Enumerating objects: 3, done. Counting objects: 100% (3/3), done. Writing objects: 100% (3/3), 250 bytes | 250.00 KiB/s, done. Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 To https://gitlab.com/somenovice/research-diary.git * [new branch] main -> main branch 'main' set up to track 'origin/main'.
Having successfully pushed our commit to the GitLab repository, we change to our browser and navigate to the project (or reload it, if we still have it open). We will be greeted by the project homepage, similar to the following screenshot:
Let us look at what has changed compared to its initial state. The interface elements encouraging us to add members to the project are gone. Of course, we can still navigate to the project’s Members later on, if we need to. We also, correctly, no longer get told that the repository is empty and the instructions on how to push content to the repository have vanished.
Instead, we see some statistics below the project’s title: 1 Commit, 1 Branch, 0 Tags, 72 KB Files, 72 KB Storage. They double as buttons other project pages.
Below the description is a new button bar, followed by a box presenting information on last commit of the currently select branch.
The buttons below, that we saw earlier, allow us to add specific files or navigate to the configuration of certain GitLab features. Note that one button changed from reading “Add README” to just “README”, since we added
README.md. The button is now a link to the latest version of that file in the current branch.
Then we see a list of files. So far, there is only
README.md. The list also tells us through which commit it was last changed and when that commit was created.
Finally, we see the markdown file
README.md rendered. Because having a README-file in the root directory of a repository is a widespread convention, GitLab (and other platforms like it) usually render it on a project’s homepage.
Archiving a Project
We just went through the beginning of a GitLab project’s life cycle. At its end, if it has one, a project gets archived (or deleted). We will now go through the process of archiving a project, without completing the step.
Using the menu on the left, we navigate to the projects settings.
At the bottom the page, we find a section named “Advanced”. We hit the “Expand” button right next to it and scroll down the page.
Notice that many of buttons here are not the usual blue or white, but after scrolling a little they are red. This indicates that we should be careful about clicking them. Things might break or get deleted.
Scrolling back up, we find a section labeled “Archive Project”. Clicking the button will not delete the project. Instead it will be placed in a read-only mode. Everything will be preserved but nothing can be changed anymore. In addition, the project no longer shows up in search results and on the page for exploring projects.
Most of the time archiving a project is preferable to deleting it, in particular when it comes to research projects. Do not archive the project now! We will work with it throughout this lesson.
At the bottom of the page is also a section for deleting a project, in case you ever think that is the right thing to do.
- Creating a GitLab project requires not more than a few clicks and providing a name.
- Changing the name of description of a GitLab project after creation has no indirect consequences.
- You can fill a fresh GitLab project’s repository by pushing a local repository.
- You can archive a project (and you can delete a project, but often should not.)