GitLab is a popular platform to share code, store software solutions, and host documentation.
Project owners control access to GitLab repositories. You may log in and create your projects and repositories, and share them with others.
Jump to a Section:
Would you prefer not to use the Atom Text Editor? We also have documentation for Git in the command line.
It is assumed that users of this guide understand basic Git/version control principles. To learn more about Git basics, visit this page.
This section covers the setup procedures for Atom and Git.
While there are many text editors to choose from, Atom is recommended due to its ability to be customized and integrated with GitLab/Git.
Install Atom: https://atom.io/
Atom has several packages which enhance the user experience and some of them you'll need for the workflow. The packages can be installed by entering the
Settings screen and choosing
Install. There are thousands of packages, so try some out and have fun.
git-plus (integrates Git)
git-checkout (allows checking out remote branches within Atom)
Optional but Recommended Packages:
linter (aids in code validation, will also need linter package for each language)
minimap (displays thumbnail version of document along with your location within it)
todo-show (provides visuals for TODO and FIXME tags)
Navigate to the GitLab repository in your web browser. For this example, we'll use the
user-documentation repository. Copy the SSH address to your machine's clipboard.
(Optional) Consider adding your SSH key to your GitLab profile so you are not prompted for credentials after every commit. To add your public SSH key to GitLab:
Click on your user image in the top-right of the GitLab window.
On the left, click
Paste your public SSH key in the box, provide a title, and save by clicking
Now, back inside Atom, open the
Command Palette. On Mac, press
p. In Windows/Linux, press
git clone and press
Paste the SSH address in the resulting window. You may also modify the location of the local folder.
Wait for the repository to clone.
Now you can see the files have populated into the folder you specified. These files represent a local copy, to which you will make changes.
First, use the command line to see if Git is installed. (Windows users may check their list of currently installed programs.)
To install or update Git using your package manager:
sudo yum install gitsudo yum update git
sudo apt-get install gitsudo apt-get update git
MacOS, use Homebrew:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"brew install gitbrew upgrade git
Windows: download Git for Windows and install it.
Set up Git with your access credentials to GitLab with the following commands:
git config --global user.name "your_username"git config --global user.email "[email protected]"
You can review the information that you entered during set-up:
git config --global --list
At this point, you likely either want to create a new branch and add your contributions there or checkout a different branch you or someone else has already created. Each of these option is shown next. Unless you have reason otherwise you should choose one of these, rather than attempting to work from the master branch.
Create a Git branch by clicking on the
master button on the bottom-right of the Atom window. Name the branch something descriptive.
We need the name of the remote branch we wish to work on
The GitLab project page displays a droplist with the name of available branches.
Open the Atom command palette and search for
git checkout checkout (requires Git checkout plugin having been installed).
You may also open the checkout dialog directly using the hotkeys
c on Mac).
The checkout dialog is a list of branches to checkout or switch to. Using the arrow keys, highlight the
custom entry and hit enter. Now type in the name of the remote branch name. You may find this in GitLab.
A notice will display if the checkout was successful. You may then switch between branches using the branch selector in the bottom-right toolbar.
📝 Note: If checking out a remote branch within Atom using the 'git checkout' plugin, ensure you read the directions carefully. Do not click on the 'custom' branch, use the arrow keys and press
Enter, then supply the name of the remote branch you wish to checkout. Lastly, if you make a mistake while typing in the branch name, you will end up creating a new branch with the typo. Be sure to type the branch name correctly.
Rather than using the checkout dialogs in Atom, you may also list and checkout remote branches using the Git command line tools.
List remote branches:
$ git branch -rorigin/GettingStartedWorkorigin/HEAD -> origin/masterorigin/masterorigin/wendi-5origin/user-contributions
Checkout a remote branch from the command line.
git checkout --track origin/wendi-5 after which you may select the branch within Atom.
Once you clone a repository, it opens automatically in Atom. However, if you need to open the repository again, click on
Add Project Folder and select your repository. Select files from the directory tree on the right of the Atom screen. Make your edits and save your changes.
You do not have to use Atom for editing. You can click the
edit button in GitLab, edit directly from the webpage, and preview before committing. Note that only repository owners can edit this way - otherwise, you can create a branch and edit your branch.
You can open the Git window by pressing
(. Here you view unstaged and staged changes.
Unstaged means the files are not ready to be committed.
Staged means the files are ready to be committed.
Stage all of the files that you'd like to commit to the branch. This is accomplished by selecting the
+ symbol next to each file. Alternatively, on the top-right of the Git window, there is a
Stage All button.
Commit your changes either within the Git window or by entering
git commit in Atom's command palette. Enter a commit message that helps you and others understand what changes were made. Then click
Push changes to GitLab by typing
git push in the command palette, or using Atom's up/down Git arrows located on the bottom-right of the window.
📝 Note: If you get an error after typing
git push that says "No upstream branch" open your terminal and navigate to the local copy of the repository. Then type
git push --set-upstream origin name_of_branch. From then on you should be able to use the command palette to type
git push or use the up/down arrows on the bottom-right of the window.
At this time, GitLab does not natively support submissions for merge requests via the command line.
You can create a merge request using the GitLab GUI.
From the left menu panel in Gitlab, select
Merge Request then the green
New merge request button.
Select your branch in the "Source Branch" side.
Target branch is master.
On the next screen the only thing needed is:
Assign to: < Project Owner, etc. >
Submit merge request.