Repository

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

A repository is where you store your code and make changes to it. Your changes are tracked with version control.

Each project contains a repository.

Create a repository

To create a repository, you can:

• Create a project or
• Fork an existing project.

A repository cannot exist without a project. A project contains many things, one of which is a repository.

Add files to a repository

You can add files to a repository:

• When you create a project.
• After you create a project, by using:
  • The web editor.
  • The UI.
  • The command line.

Add a file from the UI

You can upload a file from the GitLab UI.

1. On the left sidebar, select Search or go to and find your project.
2. Go to the directory where you want to upload the file.
3. Next to the directory name, select the plus icon ({plus}) > Upload file.
4. Complete the fields. To create a merge request with your changes, enter a branch name that's not your repository's default branch.
5. Select Upload file.

Commit changes to a repository

You can commit your changes, to a branch in the repository. When you use the command line, you can commit multiple times before you push.

• Commit message: A commit message identifies what is being changed and why. In GitLab, you can add keywords to the commit message to perform one of the following actions:
  • Trigger a GitLab CI/CD pipeline: If the project is configured with GitLab CI/CD, you trigger a pipeline per push, not per commit.
  • Skip pipelines: Add the ci skip keyword to your commit message to make GitLab CI/CD skip the pipeline.
  • Cross-link issues and merge requests: Use cross-linking to keep track of related parts of your workflow. If you mention an issue or a merge request in a commit message, they are displayed on their respective thread.
• Cherry-pick a commit: In GitLab, you can cherry-pick a commit from the UI.
• Revert a commit: Revert a commit from the UI to a selected branch.
• Sign a commit: Add extra security by signing your commits.

Clone a repository

You can clone a repository by using the command line.

Alternatively, you can clone directly into a code editor.

Clone and open in Apple Xcode

Projects that contain a .xcodeproj or .xcworkspace directory can be cloned into Xcode on macOS.

1. From the GitLab UI, go to the project's overview page.
2. In the upper-right corner, select Code.
3. Select Xcode.

The project is cloned onto your computer and you are prompted to open Xcode.

Clone and open in Visual Studio Code

All projects can be cloned into Visual Studio Code from the GitLab user interface, but you can also install the GitLab Workflow extension for VS Code to clone from Visual Studio Code:

• From the GitLab interface:

  1. Go to the project's overview page.

  2. In the upper-right corner, select Code.

  3. Under Open in your IDE, select Visual Studio Code (SSH) or Visual Studio Code (HTTPS).

  4. Select a folder to clone the project into.

     After Visual Studio Code clones your project, it opens the folder.

• From Visual Studio Code, with the extension installed, use the extension's Git: Clone command.

Clone and open in IntelliJ IDEA

All projects can be cloned into IntelliJ IDEA from the GitLab user interface.

Prerequisites:

• The JetBrains Toolbox App must be also be installed.

To do this:

1. Go to the project's overview page.
2. In the upper-right corner, select Code.
3. Under Open in your IDE, select IntelliJ IDEA (SSH) or IntelliJ IDEA (HTTPS).

Download the code in a repository

You can download the source code that's stored in a repository.

1. On the left sidebar, select Search or go to and find your project.

2. Above the file list, select Code.

3. From the options, select the files you want to download.

   • Source code: Download the source code from the current branch you're viewing. Available extensions: zip, tar, tar.gz, and tar.bz2.
   • Directory: Download a specific directory. Visible only when you view a subdirectory. Available extensions: zip, tar, tar.gz, and tar.bz2.
   • Artifacts: Download the artifacts from the latest CI job.

The checksums of generated archives can change even if the repository itself doesn't change. For example, this occurs if Git or a third-party library that GitLab uses changes.

Repository languages

For the default branch of each repository, GitLab determines which programming languages are used. This information is displayed on the Project overview page.

When new files are added, this information can take up to five minutes to update.

Add repository languages

Not all files are detected and listed on the Project overview page. Documentation, vendor code, and most markup languages are excluded.

You can change this behavior by overriding the default settings.

1. In your repository's root directory, create a file named .gitattributes.

2. Add a line that tells GitLab to include files of this type. For example, to enable .proto files, add the following code:

   *.proto linguist-detectable=true

View a list of supported data types.

This feature can use excessive CPU. For more information, see the troubleshooting section.

Repository size

• Introduced in GitLab 15.3, feature flags gitaly_revlist_for_repo_size and gitaly_catfile_repo_size for alternative repository size calculations.

FLAG: On self-managed GitLab, by default GitLab uses the du -sk command to determine the size of a repository. GitLab can use either git-rev-list (enabled with feature flag gitaly_revlist_for_repo_size) or git-cat-file (enabled with feature flag gitaly_catfile_repo_size) instead. To switch between different calculation methods, an administrator can enable or disable these feature flags.

The Project overview page shows the size of all files in the repository. The size is updated, at most, every 15 minutes. The file size includes repository files, artifacts, and LFS.

The size can differ slightly from one instance to another due to compression, housekeeping, and other factors.

Administrators can set a repository size limit. GitLab sets the size limits for GitLab.com.

Repository contributor analytics

You can view a list and charts of commits made by project members in Contributor analytics.

Repository history graph

A repository graph displays a visual history of the repository network, including branches and merges. This graph can help you visualize the Git flow strategy used in the repository.

Go to your project's Code > Repository graph.

What happens when a repository path changes

When a repository path changes, GitLab handles the transition from the old location to the new one with a redirect.

When you rename a user, change a group path, or rename a repository:

• URLs for the namespace and everything under it, like projects, are redirected to the new URLs.
• Git remote URLs for projects under the namespace redirect to the new remote URL. When you push or pull to a repository that has changed location, a warning message to update your remote is displayed. Automation scripts or Git clients continue to work after a rename.
• The redirects are available as long as the original path is not claimed by another group, user, or project.
• API redirects may need to be followed explicitly.

After you change a path, you must update the existing URL in the following resources, because they can't follow redirects:

• Include statements except include:component, otherwise pipelines fail with a syntax error. CI/CD component references can follow redirects.
• Namespaced API calls that use the encoded path instead of the numeric namespace and project IDs.
• Docker image references.
• Variables that specify a project or namespace.

Related topics

• GitLab Workflow extension for VS Code
• Lock files and prevent change conflicts
• Repository API
• Files
• Branches
• Create a directory
• Find file history
• Identify changes by line (Git blame)

Troubleshooting

Search sequence of pushes to a repository

If it seems that a commit has gone "missing", search the sequence of pushes to a repository. This StackOverflow article describes how you can end up in this state without a force push. Another cause can be a misconfigured server hook that changes a HEAD ref in a git reset operation.

If you look at the output from the sample code below for the target branch, you see a discontinuity in the from/to commits as you step through the output. The commit_from of each new push should equal the commit_to of the previous push. A break in that sequence indicates one or more commits have been "lost" from the repository history.

Using the rails console, the following example checks the last 100 pushes and prints the commit_from and commit_to entries:

p = Project.find_by_full_path('project/path')
p.events.pushed_action.last(100).each do |e|
  puts "%-20.20s %8s...%8s (%s)", e.push_event_payload[:ref], e.push_event_payload[:commit_from], e.push_event_payload[:commit_to], e.author.try(:username)
end ; nil

Example output showing break in sequence at line 4:

master f21b07713251e04575908149bdc8ac1f105aabc3...6bc56c1f46244792222f6c85b11606933af171de root
master 6bc56c1f46244792222f6c85b11606933af171de...132da6064f5d3453d445fd7cb452b148705bdc1b root
master 132da6064f5d3453d445fd7cb452b148705bdc1b...a62e1e693150a2e46ace0ce696cd4a52856dfa65 root
master 58b07b719a4b0039fec810efa52f479ba1b84756...f05321a5b5728bd8a89b7bf530aa44043c951dce root
master f05321a5b5728bd8a89b7bf530aa44043c951dce...7d02e575fd790e76a3284ee435368279a5eb3773 root

Error: Xcode fails to clone repository

GitLab provides an option to restrict a list of allowed SSH keys. If your SSH key is not on the allowed list, you might encounter an error like The repository rejected the provided credentials.

To resolve this issue, create a new SSH key pair that meets the guidelines for supported SSH key types. After you generate a supported SSH key, try cloning the repository again.