debian-mirror-gitlab/doc/user/project/repository/index.md

Repository

A repository is what you use to store your codebase in GitLab and change it with version control. A repository is part of a project, which has a lot of other features.

Create a repository

To create a new repository, all you need to do is create a new project.

Once you create a new project, you can add new files via UI (read the section below) or via command line. To add files from the command line, follow the instructions that will be presented on the screen when you create a new project, or read through them in the command line basics documentation.

Important: For security reasons, when using the command line, we strongly recommend that you connect with GitLab via SSH.

Files

Create and edit files

Host your codebase in GitLab repositories by pushing your files to GitLab. You can either use the user interface (UI), or connect your local computer with GitLab through the command line.

To configure GitLab CI/CD to build, test, and deploy you code, add a file called .gitlab-ci.yml to your repository's root.

From the user interface:

GitLab's UI allows you to perform lots of Git commands without having to touch the command line. Even if you use the command line regularly, sometimes it's easier to do so via GitLab UI:

• Create a file
• Upload a file
• File templates
• Create a directory
• Start a merge request

From the command line:

To get started with the command line, please read through the command line basics documentation.

Find files

Use GitLab's file finder to search for files in a repository.

Supported markup languages and extensions

GitLab supports a number of markup languages (sometimes called lightweight markup languages) that you can use for the content of your files in a repository. They are mostly used for documentation purposes.

Just pick the right extension for your files and GitLab will render them according to the markup language.

Markup language	Extensions
Plain text	txt
Markdown	mdown, mkd, mkdn, md, markdown
reStructuredText	rst
Asciidoc	adoc, ad, asciidoc
Textile	textile
rdoc	rdoc
Orgmode	org
creole	creole
Mediawiki	wiki, mediawiki

Repository README and index files

When a README or index file is present in a repository, its contents will be automatically pre-rendered by GitLab without opening it.

They can either be plain text or have an extension of a supported markup language:

Some things to note about precedence:

1. When both a README and an index file are present, the README will always take precedence.
2. When more than one file is present with different extensions, they are ordered alphabetically, with the exception of a file without an extension which will always be last in precedence. For example, README.adoc will take precedence over README.md, and README.rst will take precedence over README.

Jupyter Notebook files

Introduced in GitLab 9.1

Jupyter Notebook (previously IPython Notebook) files are used for interactive computing in many fields and contain a complete record of the user's sessions and include code, narrative text, equations and rich output.

When added to a repository, Jupyter Notebooks with a .ipynb extension will be rendered to HTML when viewed.

Interactive features, including JavaScript plots, will not work when viewed in GitLab.

Branches

When you submit changes in a new branch, you create a new version of that project's file tree. Your branch contains all the changes you are presenting, which are detected by Git line by line.

To continue your workflow, once you pushed your changes to a new branch, you can create a merge request, perform inline code review, and discuss your implementation with your team. You can live preview changes submitted to a new branch with Review Apps.

With GitLab Starter, you can also request approval from your managers.

To create, delete, and view branches via GitLab's UI:

• Default branches
• Create a branch
• Protected branches
• Delete merged branches
• Branch filter search box

Alternatively, you can use the command line.

To learn more about branching strategies read through the GitLab Flow documentation.

Commits

When you commit your changes, you are introducing those changes to your branch. Via command line, you can commit multiple times before pushing.

• Commit message: A commit message is important to identity what is being changed and, more importantly, why. In GitLab, you can add keywords to the commit message that will perform one of the actions below:
  • Trigger a GitLab CI/CD pipeline: If you have your project configured with GitLab CI/CD, you will trigger a pipeline per push, not per commit.
  • Skip pipelines: You can add to you commit message the keyword [ci skip] and GitLab CI will skip that pipeline.
  • Cross-link issues and merge requests: Cross-linking is great to keep track of what's is somehow related in your workflow. If you mention an issue or a merge request in a commit message, they will be shown on their respective thread.
• Cherry-pick a commit: In GitLab, you can cherry-pick a commit right from the UI.
• Revert a commit: Easily revert a commit from the UI to a selected branch.
• Sign a commit: Use GPG to sign your commits.

Repository size

On GitLab.com, your repository size limit is 10GB (including LFS). For other instances, the repository size is limited by your system administrators.

You can also reduce a repository size using Git.

Contributors

All the contributors to your codebase are displayed under your project's Settings > Contributors.

They are ordered from the collaborator with the greatest number of commits to the fewest, and displayed on a nice graph:

Repository graph

The repository graph displays visually the Git flow strategy used in that repository:

Find it under your project's Repository > Graph.

Repository Languages

For the default branch of each repository, GitLab will determine what programming languages were used and display this on the projects pages. If this information is missing, it will be added after updating the default branch on the project. This process can take up to 5 minutes.

Not all files are detected, among others; documentation, vendored code, and most markup languages are excluded. This behaviour can be adjusted by overriding the default. For example, to enable .proto files to be detected, add the following to .gitattributes in the root of your repository.

*.proto linguist-detectable=true

Compare

Select branches to compare using the branch filter search box, then click the Compare button to view the changes inline:

Find it under your project's Repository > Compare.

Locked files

Available in GitLab Premium.

Lock your files to prevent any conflicting changes.

File Locking is available only in GitLab Premium.

Repository's API

You can access your repos via repository API.

Clone in Apple Xcode

Introduced in GitLab 11.0

Projects that contain a .xcodeproj or .xcworkspace directory can now be cloned in Xcode using the new Open in Xcode button, located next to the Git URL used for cloning your project. The button is only shown on macOS.