index.md 8.86 KB
Newer Older
1 2 3 4
# 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.
5
A repository is part of a [project](../index.md), which has a lot of other features.
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

## Create a repository

To create a new repository, all you need to do is
[create a new project](../../../gitlab-basics/create-project.md).

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
21
that you [connect with GitLab via SSH](../../../ssh/README.md).
22

23 24
## Files

25
### Create and edit files
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51

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
you code, add a file called [.`gitlab-ci.yml`](../../../ci/quick_start/README.md)
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).

52 53 54 55
### Find files

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

56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
### 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:

- Asciidoc: `README.adoc` or `index.adoc`
- Markdown: `README.md` or `index.md`
- reStructuredText: `README.rst` or `index.rst`
- Text: `README.txt` or `index.txt`

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`.

NOTE: **Note:**
`index` files without an extension will not automatically pre-render. You'll
have to explicitly open them to see their contents.

James Ramsay's avatar
James Ramsay committed
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
### Jupyter Notebook files

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2508) in GitLab 9.1

[Jupyter][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.

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

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

98 99
## Branches

100
When you submit changes in a new [branch](branches/index.md), you create a new version
101 102 103 104 105 106 107 108 109 110
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](../merge_requests/index.md), perform
inline code review, and [discuss](../../discussions/index.md)
your implementation with your team.
You can live preview changes submitted to a new branch with
[Review Apps](../../../ci/review_apps/index.md).

111
With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request
112
[approval](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your managers.
113

114
To create, delete, and view [branches](branches/index.md) via GitLab's UI:
115

116
- [Default branches](branches/index.md#default-branch)
117 118 119
- [Create a branch](web_editor.md#create-a-new-branch)
- [Protected branches](../protected_branches.md#protected-branches)
- [Delete merged branches](branches/index.md#delete-merged-branches)
120
- [Branch filter search box](branches/index.md#branch-filter-search-box)
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156

Alternatively, you can use the
[command line](../../../gitlab-basics/start-using-git.md#create-a-branch).

To learn more about branching strategies read through the
[GitLab Flow](../../../university/training/gitlab_flow.md) documentation.

## 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:**
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](../../../ci/README.md),
  you will trigger a pipeline per push, not per commit.
  - **Skip pipelines:**
  You can add to you commit message the keyword
  [`[ci skip]`](../../../ci/yaml/README.html#skipping-jobs)
  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:**
In GitLab, you can
[cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-picking-a-commit)
right from the UI.
- **Revert a commit:**
Easily [revert a commit](../merge_requests/revert_changes.md#reverting-a-commit)
from the UI to a selected branch.
157 158
- **Sign a commit:**
Use GPG to [sign your commits](gpg_signed_commits/index.md).
159 160 161

## Repository size

162 163 164
On GitLab.com, your [repository size limit is 10GB](../../gitlab_com/index.md#repository-size-limit)
(including LFS). For other instances, the repository size is limited by your
system administrators.
165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184

You can also [reduce a repository size using Git](reducing_the_repo_size_using_git.md).

## 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**.

185 186 187
## Repository Languages

For the default branch of each repository, GitLab will determine what programming languages
188 189 190
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.
191 192 193

![Repository Languages bar](img/repository_languages.png)

194
Not all files are detected, among others; documentation,
195 196 197 198 199
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
200

201 202
## Compare

203
Select branches to compare using the [branch filter search box](branches/index.md#branch-filter-search-box), then click the **Compare** button to view the changes inline:
204 205 206 207 208

![compare branches](img/compare_branches.png)

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

Marcia Ramos's avatar
Marcia Ramos committed
209
## Locked files **[PREMIUM]**
210

211
[Lock your files](../file_lock.md) to prevent any conflicting changes.
212 213 214 215

## Repository's API

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

James Ramsay's avatar
James Ramsay committed
217 218 219 220
## Clone in Apple Xcode

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45820) in GitLab 11.0

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

James Ramsay's avatar
James Ramsay committed
225
[jupyter]: https://jupyter.org