index.md 9.79 KB
Newer Older
1 2 3 4
---
type: concepts, howto
---

5 6 7 8
# Repository

A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository)
is what you use to store your codebase in GitLab and change it with version control.
9
A repository is part of a [project](../index.md), which has a lot of other features.
10 11 12 13

## Create a repository

To create a new repository, all you need to do is
14 15
[create a new project](../../../gitlab-basics/create-project.md) or
[fork an existing project](forking_workflow.md).
16 17 18 19 20 21 22 23 24 25

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](../../../gitlab-basics/start-using-git.md)
documentation.

> **Important:**
For security reasons, when using the command line, we strongly recommend
26
that you [connect with GitLab via SSH](../../../ssh/README.md).
27

28 29
## Files

30
### Create and edit files
31 32 33 34 35 36

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](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project).

To configure [GitLab CI/CD](../../../ci/README.md) to build, test, and deploy
37
you code, add a file called [`.gitlab-ci.yml`](../../../ci/quick_start/README.md)
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
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](web_editor.md):

- [Create a file](web_editor.md#create-a-file)
- [Upload a file](web_editor.md#upload-a-file)
- [File templates](web_editor.md#template-dropdowns)
- [Create a directory](web_editor.md#create-a-directory)
- [Start a merge request](web_editor.md#tips)

**From the command line:**

To get started with the command line, please read through the
[command line basics documentation](../../../gitlab-basics/command-line-commands.md).

57 58
### Find files

59
Use GitLab's [file finder](file_finder.md) to search for files in a repository.
60

61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
### Supported markup languages and extensions

GitLab supports a number of markup languages (sometimes called [lightweight
markup languages](https://en.wikipedia.org/wiki/Lightweight_markup_language))
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](../../markdown.md) | `mdown`, `mkd`, `mkdn`, `md`, `markdown` |
| [reStructuredText](http://docutils.sourceforge.net/rst.html) | `rst` |
76
| [AsciiDoc](../../asciidoc.md) | `adoc`, `ad`, `asciidoc` |
77
| [Textile](https://textile-lang.com/) | `textile` |
78 79 80 81 82
| [rdoc](http://rdoc.sourceforge.net/doc/index.html)  | `rdoc` |
| [Orgmode](https://orgmode.org/) | `org` |
| [creole](http://www.wikicreole.org/) | `creole` |
| [Mediawiki](https://www.mediawiki.org/wiki/MediaWiki) | `wiki`, `mediawiki` |

83 84 85 86 87
### 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.

88 89
They can either be plain text or have an extension of a
[supported markup language](#supported-markup-languages-and-extensions):
90 91 92 93 94 95 96 97 98 99 100

Some things to note about precedence:

1. When both a `README` and an `index` file are present, the `README` will always
   take precedence.
1. 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`.

James Ramsay's avatar
James Ramsay committed
101 102
### Jupyter Notebook files

103
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/2508) in GitLab 9.1
James Ramsay's avatar
James Ramsay committed
104

Marcia Ramos's avatar
Marcia Ramos committed
105
[Jupyter](https://jupyter.org) Notebook (previously IPython Notebook) files are used for
James Ramsay's avatar
James Ramsay committed
106 107 108 109 110 111 112 113 114 115 116
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.

![Jupyter Notebook Rich Output](img/jupyter_notebook.png)

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

117 118
## Branches

119
For details, see [Branches](branches/index.md).
120 121 122 123 124 125 126 127

## Commits

When you [commit your changes](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository),
you are introducing those changes to your branch.
Via command line, you can commit multiple times before pushing.

- **Commit message:**
128 129 130
  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:
131 132 133 134 135
  - **Trigger a GitLab CI/CD pipeline:**
  If you have your project configured with [GitLab CI/CD](../../../ci/README.md),
  you will trigger a pipeline per push, not per commit.
  - **Skip pipelines:**
  You can add to you commit message the keyword
136
  [`[ci skip]`](../../../ci/yaml/README.md#skipping-jobs)
137 138 139 140 141 142 143
  and GitLab CI will skip that pipeline.
  - **Cross-link issues and merge requests:**
  [Cross-linking](../issues/crosslinking_issues.md#from-commit-messages)
  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:**
144 145 146
  In GitLab, you can
  [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-picking-a-commit)
  right from the UI.
147
- **Revert a commit:**
148 149
  Easily [revert a commit](../merge_requests/revert_changes.md#reverting-a-commit)
  from the UI to a selected branch.
150
- **Sign a commit:**
151
  Use GPG to [sign your commits](gpg_signed_commits/index.md).
152

153
## Project and repository size
154

155 156
A project's size is reported on the project's **Details** page. The reported size is
updated every 15 minutes at most, so may not reflect recent activity. The displayed files size includes repository files, artifacts, and LFS.
157

158
The project size may differ slightly from one instance to another due to compression, housekeeping, and other factors.
159

160
[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by admins. GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#repository-size-limit).
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178

## 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:

![contributors to code](img/contributors_graph.png)

## Repository graph

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

![repository Git flow](img/repo_graph.png)

Find it under your project's **Repository > Graph**.

179 180 181
## Repository Languages

For the default branch of each repository, GitLab will determine what programming languages
182 183 184
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.
185

186
![Repository Languages bar](img/repository_languages_v12_2.gif)
187

188
Not all files are detected, among others; documentation,
189 190 191 192 193
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
194

195
## Locked files **(PREMIUM)**
196

197
Use [File Locking](../file_lock.md) to
Marcia Ramos's avatar
Marcia Ramos committed
198
lock your files to prevent any conflicting changes.
199 200 201 202

## Repository's API

You can access your repos via [repository API](../../../api/repositories.md).
James Ramsay's avatar
James Ramsay committed
203

James Ramsay's avatar
James Ramsay committed
204 205
## Clone in Apple Xcode

206
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/45820) in GitLab 11.0
James Ramsay's avatar
James Ramsay committed
207

James Ramsay's avatar
James Ramsay committed
208
Projects that contain a `.xcodeproj` or `.xcworkspace` directory can now be cloned
James Ramsay's avatar
James Ramsay committed
209
in Xcode using the new **Open in Xcode** button, located next to the Git URL
James Ramsay's avatar
James Ramsay committed
210
used for cloning your project. The button is only shown on macOS.
James Ramsay's avatar
James Ramsay committed
211

212 213
## Download Source Code

214
> Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/24704) in GitLab 11.11.
215

Marcia Ramos's avatar
Marcia Ramos committed
216
The source code stored in a repository can be downloaded from the UI.
217 218 219 220
By clicking the download icon, a dropdown will open with links to download the following:

![Download source code](img/download_source_code.png)

Marcia Ramos's avatar
Marcia Ramos committed
221 222 223
- **Source code:**
  allows users to download the source code on branch they're currently
  viewing. Available extensions: `zip`, `tar`, `tar.gz`, and `tar.bz2`.
224
- **Directory:**
Marcia Ramos's avatar
Marcia Ramos committed
225 226 227
  only shows up when viewing a sub-directory. This allows users to download
  the specific directory they're currently viewing. Also available in `zip`,
  `tar`, `tar.gz`, and `tar.bz2`.
228
- **Artifacts:**
Marcia Ramos's avatar
Marcia Ramos committed
229
  allows users to download the artifacts of the latest CI build.
230 231 232 233 234 235 236 237 238 239 240 241

<!-- ## Troubleshooting

Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.

Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->