Create, review and deploy code together
GitLab CE (Community Edition)
GitLab EE (Enterprise Edition)
GitLab.com (On Our Server)
git repository management
CI: continuous integration
Start using Git on the commandline
Create an account on GitLab.com.
Find the shell of your preference.
・Terminal on Mac OSX
・GitBash on Windows
・Linux Terminal on Linux
Check if Git has already been installed:
Git is usually preinstalled on Mac and Linux.
If you don't receive a "Git version" message, you need to download Git.
Add your Git username and set your email.
Every Git commit that you create will use this information.
To add your username:
git config --global user.name ADD YOUR USERNAME
To verify your username:
git config --global user.name
To set your email address:
git config --global user.email ADD YOUR EMAIL
To verify your email:
git config --global user.email
--global: It tells Git to always use this information for anything you do on that system.
If you want to override this with a different username or email address for specific projects, you can run the command without the "--global" option when you're in that project.
To view the information:
git config --global --list
How to create your SSH Keys
You need to connect your computer to your GitLab account through SSH Keys. They are unique for every computer that you link your GitLab account with.
Generate your SSH Key
Create an account on GitLab.
Sign up and check your email for your confirmation link.
After you confirm, go to GitLab.com and sign in to your account
Add your SSH Key
Click on "profile settings"
Click on "SSH Keys"
Click on "Add SSH Key"
Paste the SSH Key that your commandline will generate for you.
When you copy a project you say you "clone" it.
To work on a git project locally (from your own computer), you will need to clone it. To do this, sign in to GitLab.com
When you are on your Dashboard, click on the project that you'd like to clone, which you'll find at the right side of your screen
To work in the project, you can copy a link to the Git repository through a SSH or a HTTPS protocol.
SSH is easier to use after it's been setup.
When you're in the project, click on the HTTPS or SSH button at the right side of your screen.
Then copy the link (you'll have to paste it on your shell in the next step)
On the command line
To clone your project, go to your computer's shell and type the following command:
git clone PASTE HTTPS OR SSH HERE
Go into a project, directory or file to work in it:
Go back one directory or file:
To see what's in the directory that you are in:
Create a directory:
Create a README.md or file in directory:
#### ADD YOUR INFORMATION
#### Press: control + X
#### Type: Y
#### Press: enter
Remove a file:
Remove a directory and all of its contents:
rm -rf NAME-OF-DIRECTORY
View history in the command line:
Carry out commands for which the account you are using lacks authority. (You will be asked for an administrator's password):
Basic Git commands
Go to the master branch to pull the latest changes from there:
git checkout master
Download the latest changes in the project, so that you work on an up-to-date copy (this is important to do every time you work on a project), while you setup tracking branches:
git pull REMOTE NAME-OF-BRANCH -u
(REMOTE: origin) (NAME-OF-BRANCH: could be "master" or an existing branch)
Create a branch (remember that spaces won't be recognized, you need to use a hyphen or underscore):
git checkout -b NAME-OF-BRANCH
Work on a branch that has already been created:
git checkout NAME-OF-BRANCH
To see the changes you've made:
Add changes to commit (you'll be able to see your changes in red when you type "git status"):
git add CHANGES IN RED
git commit -m "DESCRIBE THE INTENTION OF THE COMMIT"
Send changes to gitlab.com:
git push origin NAME-OF-BRANCH
Throw away all changes in the Git repository, but leave unstaged things:
git checkout .
Delete all changes in the Git repository, including untracked files:
git clean -f
Remove all the changes that you don't want to send to gitlab.com:
git add NAME-OF-FILE -all
Merge created branch with master branch. You need to be in the created branch:
git checkout NAME-OF-BRANCH
git merge master
Create a project
Sign in to GitLab.com.
Go to your Dashboard and click on "new project" on the right side of your screen.
Fill out the required information.
1. Project path or the name of your project (you can't add spaces, so you can use hyphens or underscores)
2. Your project's description
3. Select a visibility level
4. You can also import your existing projects
5. Click on "create project"
Create a group
Your projects in GitLab.com can be organized in 2 different ways:
under your own namespace for single projects, such as ´your-name/project-1'; or under groups.
If you organize your projects under a group, it works like a folder. You can manage your group members' permissions and access to the projects.
To create a group:
Sign in to GitLab.com.
When you are on your Dashboard, click on "Groups" on the left menu of your screen.
Click on "New group" on the top right side of your screen:
Fill out the information required:
1. Add a group path or group name (you can't add spaces, so you can use hyphens or underscores).
2. Add details or a group description.
3. You can choose a group avatar if you'd like.
4. Click on "create group".
Add a project to a group
There are 2 different ways to add a new project to a group:
・Select a group and then click on "New project" on the right side of your screen. Then you can create a project。
・When you are creating a project, click on "create a group" on the bottom right side of your screen
How to create a branch
A branch is an independent line of development.
New commits are recorded in the history for the current branch, which results in taking the source from someone's repository (the place where the history of your work is stored) at certain point in time, and apply your own changes to it in the history of the project.
To add changes to your GitLab project, you should create a branch. You can do it in your shell or in GitLab.
To create a new branch in GitLab, sign in and then select a project on the right side of your screen:
Click on "commits" on the menu on the left side of your screen:
Click on the "branches" tab:
Click on the "new branch" button on the right side of the screen:
Fill out the information required:
1. Add a name for your new branch (you can't add spaces, so you can use hyphens or underscores)
2. On the "create from" space, add the the name of the branch you want to branch off from
3. Click on the button "create branch"
You will be able to find and select the name of your branch in the white box next to a project's name:
How to fork a project
A fork is a copy of an original repository that you can put somewhere else or where you can experiment and apply changes that you can later decide if publishing or not, without affecting your original project.
1. Sign in to GitLab.
2. Select a project on the right side of your screen.
3. Click on the "fork" button on the right side of your screen.
4. Click on the user or group to where you'd like to add the forked project.
How to add a file
You can create a file in your shell or in GitLab.
To create a file in GitLab, sign in to GitLab.
Select a project on the right side of your screen:
It's a good idea to create a branch, but it's not necessary.
Go to the directory where you'd like to add the file and click on the "+" sign next to the name of the project and directory:
Name your file (you can't add spaces, so you can use hyphens or underscores). Don't forget to include the markup language you'd like to use :
Add all the information that you'd like to include in your file:
Add a commit message based on what you just added and then click on "commit changes":
Besides its regular files, every directory needs a README.md or README.html file which works like an index, telling what the directory is about. It's the first document you'll find when you open a directory.
How to add an image
The following are the steps to add images to your repository in GitLab:
Find the image that you'd like to add.
In your computer files, find the GitLab project to which you'd like to add the image (you'll find it as a regular file). Click on every file until you find exactly where you'd like to add the image. There, paste the image.
Go to your shell, and add the following commands:
Add this command for every directory that you'd like to open:
Create a new branch:
git checkout -b NAME-OF-BRANCH
Check if your image was correctly added to the directory:
You should see the name of the image in the list shown.
Move up the hierarchy through directories:
Check the status and you should see your image's name in red:
Add your changes:
git add NAME-OF-YOUR-IMAGE
Check the status and you should see your image's name in green:
Add the commit:
git commit -m “DESCRIBE COMMIT IN A FEW WORDS”
Now you can push (send) your changes (in the branch NAME-OF-BRANCH) to GitLab (the git remote named 'origin'):
git push origin NAME-OF-BRANCH
Your image will be added to your branch in your repository in GitLab. Create a Merge Request to integrate your changes to your project.
How to create a merge request
Merge Requests are useful to integrate separate changes that you've made to a project, on different branches.
To create a new Merge Request, sign in to GitLab.
Go to the project where you'd like to merge your changes:
Click on "Merge Requests" on the left side of your screen:
Click on "+ new Merge Request" on the right side of the screen:
Select a source branch or branch:
Click on the "compare branches" button:
Add a title and a description to your Merge Request:
Select a user to review your Merge Request and to accept or close it. You may also select milestones and labels (they are optional). Then click on the "submit new Merge Request" button:
Your Merge Request will be ready to be approved and published.
After you created a new branch, you'll immediately find a "create a Merge Request" button at the top of your screen. You may automatically create a Merge Request from your recently created branch when clicking on this button:
Users have different abilities depending on the access level they have in a particular group or project.
If a user is both in a project group and in the project itself, the highest permission level is used.
If a user is a GitLab administrator they receive all permissions.
In order for a group to appear as public and be browsable, it must contain at least one public project.
Any user can remove themselves from a group, unless they are the last Owner of the group.
Settings in the Profile > Preferences page allow the user to customize various aspects of the site to their liking.
Changing this setting allows the user to customize the color scheme used for the navigation bar on the left side of the screen.
The default is Charcoal.
Syntax highlighting theme
Changing this setting allows the user to customize the theme used when viewing syntax highlighted code on the site.
The default is White.
For users who have access to a large number of projects but only keep up with a select few, the amount of activity on the default Dashboard page can be overwhelming.
Changing this setting allows the user to redefine what their default dashboard will be. Setting it to Starred Projects will make that Dashboard view the default when signing in or clicking the application logo in the upper left.
The default is Your Projects.
Default Project view
It allows user to choose what content he or she want to see on project page.
The default is Readme.
GitLab allows you to open selected projects to be accessed publicly or internally.
Projects with either of these visibility levels will be listed in the public access directory.
Internal projects will only be available to authenticated users.
Public projects can be cloned without any authentication.
It will also be listed on the public access directory.
Any logged-in user will have Guest permissions on the repository.
Internal projects can be cloned by any logged in user.
It will also be listed on the public access directory for logged in users.
Any logged-in user will have Guest permissions on the repository.
How to change project visibility
Go to your project dashboard
Click on the "Edit" tab
Change "Visibility Level"
Visibility of users
The public page of users, located at /u/username is visible if either:
You are logged in.
You are logged out, and the target user is authorized to (is Guest, Reporter, etc.) at least one public project.
Otherwise, you will be redirected to the sign in page.
When visiting the public page of an user, you will only see listed projects which you can view yourself.
Restricting the use of public or internal projects
In the Admin area under Settings you can disable public projects or public and internal projects for the entire GitLab installation to prevent people making code public by accident. The restricted visibility settings do not apply to admin users.
Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later. ----
VCS: Version Control System
One of the more popular VCS tools was a system called RCS, which is still distributed with many computers today. Even the popular Mac OS X operating system includes the rcs command when you install the Developer Tools.
CVCS: Centralized Version Control Systems
a single server contains all the versioned files, and a number of clients that check out files from that central place.
DVCS: Distributed Version Control Systems
clients fully mirror the repository.
Git thinks of its data like a set of snapshots of a miniature filesystem. Every time you commit, or save the state of your project in Git, it takes a picture of what all your files look like at that moment and stores a reference to that snapshot.
If files have not changed, Git doesn't store the file again, just a link to the previous identical file it has already stored.
Git thinks about its data like a stream of snapshots.
Most operations in Git only need local files and resources to operate – generally no information is needed from another computer on your network.
Everything in Git is check-summed before it is stored and is then referred to by that checksum.
This means it's impossible to change the contents of any file or directory without Git knowing about it.
The mechanism that Git uses for this checksumming is called a SHA-1 hash. This is a 40-character string composed of hexadecimal characters (0–9 and a–f) and calculated based on the contents of a file or directory structure in Git. A SHA-1 hash looks something like this:
When you do actions in Git, nearly all of them only add data to the Git database. It is hard to get the system to do anything that is not undoable or to make it erase data in any way.
Three main states that files can reside in: Committed: data is stored in your local database.
Modified: file changed but not committed to database yet.
Staged: a modified file in its current version marked to go into your next commit snapshot.
The three main sections of a Git project:
Git directory: the metadata and object database for your project.
Working directory: is a single checkout of one version of the project.
Staging area: a file, contained in your Git directory, that stores information about what will go into your next commit.
1. modify files in your working directory.
2. stage the files, adding snapshots of them to your staging area.
3. do a commit, which takes the files as they are in the staging area and stores that snapshot permanently to your Git directory.
configuration variables: control all aspects of how Git looks and operates. These variables can be stored in three different places:
/etc/gitconfig file: Contains values for every user on the system and all their repositories. If you pass the option --system to git config, it reads and writes from this file specifically.
~/.gitconfig or ~/.config/git/config file: Specific to your user. You can make Git read and write to this file specifically by passing the --global option.
config file in the Git directory (that is, .git/config) of whatever repository you're currently using: Specific to that single repository.
Each level overrides values in the previous level, so values in .git/config trump those in /etc/gitconfig.
On Windows systems, Git looks for the .gitconfig file in the $HOME directory (C:\Users\$USER for most people).
It also still looks for /etc/gitconfig, although it's relative to the MSys root, which is wherever you decide to install Git on your Windows system when you run the installer.
However, if you are using Git for Windows 2.x, it is C:\Documents and Settings\All Users\Application Data\Git\config on Windows XP, and it is C:\ProgramData\Git\config on Windows Vista and newer.
To set your user name and email address:
git config --global user.name "John Doe"
git config --global user.email firstname.lastname@example.org
If you want to override this with a different name or email address for specific projects, you can run the command without the --global option when you're in that project.
To check your settings:
git config --list
To check a specific key's value:
git config [key]
git config user.name
To get the manual page:
git help <verb>
git <verb> --help
git help config
If you're starting to track an existing project in Git, you need to go to the project's directory and type:
This creates a new subdirectory named .git that contains all of your necessary repository files – a Git repository skeleton.
If you want to start version-controlling existing files (as opposed to an empty directory), you should begin tracking those files and do an initial commit.
git add *.c
git add LICENSE
git commit -m 'initial project version'
To clone (a copy of an existing Git repository):
git clone [url]
git clone https://github.com/libgit2/libgit2
That creates a directory named “libgit2”, initializes a .git directory inside it, pulls down all the data for that repository, and checks out a working copy of the latest version.
To clone the repository into a different directory:
git clone [url] [directory]
git clone https://github.com/libgit2/libgit2 mylibgit
Each file in your working directory can be in one of two states: tracked
Tracked: files that were in the last snapshot; they can be unmodified, modified, or staged.
Untracked: everything else – any files in your working directory that were not in your last snapshot and are not in your staging area.
When you first clone a repository, all of your files will be tracked and unmodified because you just checked them out and haven't edited anything.
As you edit files, Git sees them as modified, because you've changed them since your last commit.
You stage these modified files and then commit all your staged changes, and the cycle repeats.
To determine which files are in which state:
git status -s
git status --short
New files not tracked have a ??.
New files added to the staging area have an A.
Modified files have an M.
To track and stage a file or directory:
git add [file or directory]
git add README
If you modify a file after you run "git add", you have to run "git add" again to stage the latest version of the file.
To ignore files:
create a file named .gitignore.
$ cat .gitignore
# To ignore any files ending in “.o” or “.a”
# To ignore all files that end with a tilde (~)
The rules for the .gitignore file:
Blank lines or lines starting with # are ignored.
Standard glob patterns work.
You can start patterns with a forward slash (/) to avoid recursivity.
You can end patterns with a forward slash (/) to specify a directory.
You can negate a pattern by starting it with an exclamation point (!).
Glob patterns are simplified regular expressions.
An asterisk (*) matches zero or more characters;
[abc] matches any character inside the brackets (in this case a, b, or c);
a question mark (?) matches a single character;
brackets enclosing characters separated by a hyphen([0-9]) matches any character between them (in this case 0 through 9). You can also use two asterisks to match nested directories; a/**/z would match a/z, a/b/z, a/b/c/z, and so on.
Example .gitignore file:
# no .a files
# but do track lib.a, even though you're ignoring .a files above
# only ignore the TODO file in the current directory, not subdir/TODO
# ignore all files in the build/ directory
# ignore doc/notes.txt, but not doc/server/arch.txt
# ignore all .pdf files in the doc/ directory
To show the lines added and removed (only changes that are still unstaged):
To see what you've staged that will go into your next commit:
git diff --staged
This command compares your staged changes to your last commit.
a graphical or external diff viewing program:
To commit staged files:
To type your commit message inline:
git commit -m "your message"
To stage tracked files and commit:
git commit -a -m 'added new benchmarks'
To remove a file:
It also removes the file from your working directory so you don't see it as an untracked file the next time around.
To rename a file:
git mv file_from file_to
with no arguments, git log lists the commits made in that repository in reverse chronological order
git log -p -2
-p: shows the difference introduced in each commit.
-2: limits the output to only the last two entries
to see some abbreviated stats for each commit:
git log --stat
git log --pretty=oneline
--pretty: changes the log output to formats other than the default.
oneline: prints each commit on a single line
format: allows you to specify your own log output format.
git log --pretty=format:"%h - %an, %ar : %s"
To try the last commit again:
git commit --amend
This command takes your staging area and uses it for the commit.
if you commit and then realize you forgot to stage the changes in a file you wanted to add to this commit:
git commit -m 'initial commit'
git add forgotten_file
git commit --amend
You end up with a single commit – the second commit replaces the results of the first.
git reset HEAD CONTRIBUTING.md
The CONTRIBUTING.md file is modified but once again unstaged.
Unmodifying a Modified File:
git checkout -- [file]
git checkout -- CONTRIBUTING.md
Any changes you made to that file are gone – you just copied another file over it. Don’t ever use this command unless you absolutely know that you don’t want the file.
Remote repositories: versions of your project that are hosted on the Internet or network somewhere.
To see which remote servers you have configured:
To show the URLs that Git has stored for the shortname to be used when reading and writing to that remote:
git remote -v
origin https://github.com/schacon/ticgit (fetch)
origin https://github.com/schacon/ticgit (push)
To add a new remote Git repository:git remote add [shortname] [url]
To fetch all the information in the repository but that you don’t yet have in your repository:
git fetch [remote-name]
git fetch origin
You should have references to all the branches from that remote, which you can merge in or inspect at any time.
If you clone a repository, the command automatically adds that remote repository under the name “origin”.
git fetch origin
It fetches any new work that has been pushed to that server since you cloned (or last fetched from) it.
It pulls the data to your local repository – it doesn’t merge it with any of your work or modify what you’re currently working on.
You have to merge it manually into your work when you’re ready.
If you have a branch set up to track a remote branch, it fetches and merges a remote branch into your current branch.
It automatically sets up your local default branch (usually called "master") to track the remote default branch on the server you cloned from.
It fetches data from the server you cloned from and tries to merge it into the current branch.
To share, you have to push it upstream:
git push [remote-name] [branch-name]
To push your master branch to your origin server :
git push origin master
To see information about a remote:
git remote show [remote-name]
git remote show origin
To rename a reference:
git remote rename [old name] [new name]
git remote rename pb paul
This changes your remote branch names, too.
What used to be referenced at pb/master is now at paul/master.
To remove a remote:
git remote rm [remote]
git remote rm paul
Git has the ability to tag specific points in history as being important. Typically people use this functionality to mark release points (v1.0, and so on).
To list the tags in alphabetical order:
To list tags starting with 1.8.5:
git tag -l 'v1.8.5*'
Two main types of tags: lightweight and annotated.
lightweight: a pointer to a specific commit.
Annotated: full objects in the Git database. They’re checksummed; contain the tagger name, email, and date; have a tagging message; and can be signed and verified with GNU Privacy Guard (GPG).
To create an annotated tag:
git tag -a [name] -m '[message]'
git tag -a v1.4 -m 'my version 1.4'
To create a lightweight tag, don’t supply the -a, -s, or -m option:
git tag [name]-lw
git tag v1.4-lw
Branching means you diverge from the main line of development and continue to do work without messing with that main line.
To create a new branch:
git branch [name]
git branch testing
HEAD: a pointer to the local branch you’re currently on.
To show where the branch pointers are pointing:
git log --oneline --decorate
To switch to an existing branch:
git checkout [another branch]
To switch back to the master branch:
git checkout master
Switching branches changes files in your working directory
To print out the history of your commits, showing where your branch pointers are and how your history has diverged:
git log --oneline --decorate --graph --all
To create a branch and switch to it at the same time
git checkout -b [new branch]
git checkout -b iss53
This is shorthand for:
git branch iss53
git checkout iss53
To merge with current branch:
git merge [branch]
When the commit pointed to by the branch you merged in is directly upstream of the commit you’re on, Git moves the pointer forward.
When you try to merge one commit with a commit that can be reached by following the first commit’s history, Git simplifies things by moving the pointer forward because there is no divergent work to merge together.
To delete a branch:
git branch -d [branch]
If you changed the same part of the same file differently in the two branches you’re merging together, Git won’t be able to merge them.
To use a graphical tool to resolve merge conflict:
To list your branches:
Notice the * character that prefixes the branch: it indicates the current branch.
To see the last commit on each branch:
git branch -v
The useful --merged and --no-merged options can filter this list to branches that you have or have not yet merged into the branch you’re currently on.
To see the branches merged into the current branch:
git branch --merged
Branches on this list without the * in front of them can be deleted;
you’ve already incorporated their work into another branch, so you’re not going to lose anything.
To see all the branches that contain work you haven’t yet merged in:
git branch --no-merged