Skip to content

G
gitlab-ce
Commit 511eab8d authored by Amy Qualls's avatar Amy Qualls
Browse files
Options

Merge branch 'docs-selhorn-ctrt-repository' into 'master' 

Reorganized and edited Repository topic for CTRT

See merge request gitlab-org/gitlab!62346
parents 2ced40d7 23c407ee
Show whitespace changes
Inline Side-by-side
Showing with 187 additions and 247 deletions
doc/api/commits.md
View file @ 511eab8d
......@@ -7,7 +7,7 @@ type: reference, api
# Commits API **(FREE)**
This API operates on [repository commits](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository). Read more about [GitLab-specific information](../user/project/repository/index.md#commits) for commits.
This API operates on [repository commits](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository). Read more about [GitLab-specific information](../user/project/repository/index.md#commit-changes-to-a-repository) for commits.
## List repository commits
......
doc/user/group/index.md
View file @ 511eab8d
......@@ -351,7 +351,7 @@ You can transfer groups in the following ways:
When transferring groups, note:
- Changing a group's parent can have unintended side effects. See [Redirects when changing repository paths](../project/repository/index.md#redirects-when-changing-repository-paths).
- Changing a group's parent can have unintended side effects. See [what happens when a repository path changes](../project/repository/index.md#what-happens-when-a-repository-path-changes).
- You can only transfer groups to groups you manage.
- You must update your local repositories to point to the new location.
- If the immediate parent group's visibility is lower than the group's current visibility, visibility levels for subgroups and projects change to match the new parent group's visibility.
......@@ -361,7 +361,7 @@ When transferring groups, note:
## Change a group's path
Changing a group's path (group URL) can have unintended side effects. Read
[how redirects behave](../project/repository/index.md#redirects-when-changing-repository-paths)
[how redirects behave](../project/repository/index.md#what-happens-when-a-repository-path-changes)
before you proceed.
If you are changing the path so it can be claimed by another group or user,
......
doc/user/profile/index.md
View file @ 511eab8d
......@@ -42,7 +42,7 @@ If you don't know your current password, select the **I forgot my password** lin
Your username has a unique [namespace](../group/index.md#namespaces),
which is updated when you change your username. Before you change your username, read about
[how redirects behave](../project/repository/index.md#redirects-when-changing-repository-paths).
[how redirects behave](../project/repository/index.md#what-happens-when-a-repository-path-changes).
If you do not want to update the namespace, you can create a new user or group and transfer projects to it instead.
Prerequisites:
......
doc/user/project/repository/index.md
View file @ 511eab8d
......@@ -8,75 +8,142 @@ type: concepts, howto
# Repository **(FREE)**
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.
A repository is part of a [project](../index.md), which has a lot of other features.
is where you store your code and make changes to it. Your changes are tracked with version control.
Each [project](../index.md) contains a repository.
## Create a repository
To create a new repository, all you need to do is
[create a new project](../../../user/project/working_with_projects.md#create-a-project) or
[fork an existing project](forking_workflow.md).
To create a repository, you can:
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
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.
- [Create a project](../../../user/project/working_with_projects.md#create-a-project) or
- [Fork an existing project](forking_workflow.md).
> **Important:**
For security reasons, when using the command line, we strongly recommend
that you [connect with GitLab via SSH](../../../ssh/README.md).
## Add files to a repository
## Files
You can add files to a repository:
Use a repository to store your files in GitLab. In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33806),
an icon identifying the extension is shown next to the filename:
- When you create a project.
- After you create a project:
- By using [the web editor](web_editor.md).
- [From the command line](../../../gitlab-basics/command-line-commands.md).
![Repository file icons](img/file_ext_icons_repo_v12_10.png)
## Commit changes to a repository
### Create and edit files
You can [commit your changes](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository),
to a branch in the repository. When you use the command line, you can commit multiple times before you push.
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).
- **Commit message:**
A commit message identities 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](../../../ci/README.md),
you trigger a pipeline per push, not per commit.
- **Skip pipelines:**
Add the [`ci skip`](../../../ci/yaml/README.md#skip-pipeline) keyword to
your commit message to make GitLab CI/CD skip the pipeline.
- **Cross-link issues and merge requests:**
Use [cross-linking](../issues/crosslinking_issues.md#from-commit-messages)
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](../merge_requests/cherry_pick_changes.md#cherry-picking-a-commit)
from the UI.
- **Revert a commit:**
[Revert a commit](../merge_requests/revert_changes.md#reverting-a-commit)
from the UI to a selected branch.
- **Sign a commit:**
Use GPG to [sign your commits](gpg_signed_commits/index.md).
To configure [GitLab CI/CD](../../../ci/README.md) to build, test, and deploy
your code, add a file called [`.gitlab-ci.yml`](../../../ci/quick_start/index.md)
to your repository's root.
## Clone a repository
**From the user interface:**
You can [clone a repository by using the command line](../../../gitlab-basics/start-using-git.md#clone-a-repository).
The GitLab 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):
Alternatively, you can clone directly into a code editor.
- [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)
- [Find file history](git_history.md)
- [Identify changes by line (Git blame)](git_blame.md)
### Clone and open in Apple Xcode
**From the command line:**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0.
Projects that contain a `.xcodeproj` or `.xcworkspace` directory can be cloned
into Xcode on macOS.
To get started with the command line, please read through the
[command line basics documentation](../../../gitlab-basics/command-line-commands.md).
1. From the GitLab UI, go to the project's overview page.
1. Select **Clone**.
1. Select **Xcode**.
### Find files
The project is cloned onto your computer and you are
prompted to open XCode.
Use the GitLab [file finder](file_finder.md) to search for files in a repository.
### Clone and open in Visual Studio Code
### Supported markup languages and extensions
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.10.
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.
All projects can be cloned into Visual Studio Code.
Just pick the right extension for your files and GitLab renders them
according to the markup language.
1. From the GitLab UI, go to the project's overview page.
1. Select **Clone**.
1. Select **Visual Studio Code**.
1. Select a folder to clone the project into.
When VS Code has successfully cloned your project, it opens the folder.
## Download the code in a repository
> - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11.
> - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5.
You can download the source code that's stored in a repository.
1. Above the file list, select the download icon (**{download}**).
1. 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.
## 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.
![Repository Languages bar](img/repository_languages_v12_2.gif)
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`.
1. Add a line that tells GitLab to include files of this type. For example,
to enable `.proto` files, add the following code:
```plaintext
*.proto linguist-detectable=true
```
View a list of
[supported data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
This feature can use excessive CPU.
For more information, see the [troubleshooting section](#repository-languages-excessive-cpu-use).
### Supported markup languages
If your file has one of the following file extensions, GitLab renders the
contents of the file's [markup language](https://en.wikipedia.org/wiki/Lightweight_markup_language) in the UI.
| Markup language | Extensions |
| --------------- | ---------- |
......@@ -90,38 +157,25 @@ according to the markup language.
| [creole](http://www.wikicreole.org/) | `creole` |
| [MediaWiki](https://www.mediawiki.org/wiki/MediaWiki) | `wiki`, `mediawiki` |
### Repository README and index files
When a `README` or `index` file is present in a repository, its contents are
automatically pre-rendered by GitLab without opening it.
### README and index files
They can either be plain text or have an extension of a
[supported markup language](#supported-markup-languages-and-extensions):
When a `README` or `index` file is present in a repository, GitLab renders its contents.
These files can either be plain text or have the extension of a
[supported markup language](#supported-markup-languages).
Some things to note about precedence:
1. When both a `README` and an `index` file are present, the `README` always
- When both a `README` and an `index` file are present, the `README` always
takes 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 is always last in precedence. For example, `README.adoc` takes
precedence over `README.md`, and `README.rst` takes precedence over
`README`.
### Jupyter Notebook files
[Jupyter](https://jupyter.org/) 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.
[Read how to use Jupyter notebooks with GitLab.](jupyter_notebooks/index.md)
- When multiple files have the same name but a different extension, the files are
ordered alphabetically. Any file without an extension is ordered last.
For example, `README.adoc` takes precedence over `README.md`, and `README.rst`
takes precedence over `README`.
### OpenAPI viewer
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19515) in GitLab 12.6.
GitLab can render OpenAPI specification files with its file viewer, provided
their filenames include `openapi` or `swagger` and their extension is `yaml`,
GitLab can render OpenAPI specification files. The filename
must include `openapi` or `swagger` and the extension must be `yaml`,
`yml`, or `json`. The following examples are all correct:
- `openapi.yml`
......@@ -138,200 +192,73 @@ their filenames include `openapi` or `swagger` and their extension is `yaml`,
- `openapi.gitlab.yml`
- `gitlab.openapi.yml`
Then, to render them:
1. Navigate to the OpenAPI file in your repository in the GitLab UI.
1. Click the "Display OpenAPI" button which is located between the "Display source"
and "Edit" buttons (when an OpenAPI file is found, it replaces the
"Display rendered file" button).
## Branches
For details, see [Branches](branches/index.md).
## 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.
To render an OpenAPI file:
- **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 performs 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 trigger a pipeline per push, not per commit.
- **Skip pipelines:**
You can add to your commit message the keyword
[`[ci skip]`](../../../ci/yaml/README.md#skip-pipeline),
and GitLab CI/CD skips 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 are 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.
- **Sign a commit:**
Use GPG to [sign your commits](gpg_signed_commits/index.md).
1. Go to the OpenAPI file in your repository.
1. Between the **Display source** and **Edit** buttons, select **Display OpenAPI**. When an OpenAPI file is found, it replaces the
**Display rendered file** button.
## Project and repository size
## Repository size
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.
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 project size may differ slightly from one instance to another due to compression, housekeeping, and other factors.
The size can differ slightly from one instance to another due to compression, housekeeping, and other factors.
[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by administrators.
GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#account-and-limit-settings).
Administrators can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md).
[GitLab sets the size limits for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings).
## Contributors
## Repository contributor graph
All the contributors to your codebase are displayed under your project's **Settings > Contributors**.
All code contributors are displayed under your project's **Repository > Contributors**.
They are ordered from the collaborator with the greatest number
of commits to the fewest, and displayed on a nice graph:
The graph shows the contributor with the most commits to the fewest.
![contributors to code](img/contributors_graph.png)
## Repository graph
The repository graph displays the history of the repository network visually, including branches and merges. This can help you visualize the Git flow strategy used in the repository:
![repository Git flow](img/repo_graph.png)
Find it under your project's **Repository > Graph**.
## Repository languages
For the default branch of each repository, GitLab determines what programming languages
were used and displays this on the project's pages. If this information is missing, it's
added after updating the default branch for the project. This process can take up to five
minutes.
![Repository Languages bar](img/repository_languages_v12_2.gif)
Not all files are detected, among others; documentation,
vendored code, and most markup languages are excluded. This behavior 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.
```plaintext
*.proto linguist-detectable=true
```
Sometimes this feature can use excessive CPU.
[Read about troubleshooting this](#repository-languages-excessive-cpu-use)
and also more about customizing this feature using `.gitattributes`.
## Locked files **(PREMIUM)**
Use [File Locking](../file_lock.md) to
lock your files to prevent any conflicting changes.
## Repository's API
You can access your repositories via [repository API](../../../api/repositories.md).
## Clone a repository
## Repository history graph
Learn how to [clone a repository through the command line](../../../gitlab-basics/start-using-git.md#clone-a-repository).
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.
Alternatively, clone directly into a code editor as documented below.
Go to your project's **Repository > Graph**.
### Clone and open in Apple Xcode
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0.
Projects that contain a `.xcodeproj` or `.xcworkspace` directory can now be cloned
into Xcode on macOS. To do that:
1. From the GitLab UI, go to the project's overview page.
1. Click **Clone**.
1. Select **Xcode**.
The project is cloned onto your computer in a folder of your choice and you are
prompted to open XCode.
### Clone and open in Visual Studio Code
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.10.
All projects can be cloned into Visual Studio Code. To do that:
1. From the GitLab UI, go to the project's overview page.
1. Click **Clone**.
1. Select **VS Code**.
1. Select a folder to clone the project into.
When VS Code has successfully cloned your project, it opens the folder.
## Download source code
> - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11.
> - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5.
The source code stored in a repository can be downloaded from the UI.
By clicking the download icon, a dropdown opens with links to download the following:
![Download source code](img/download_source_code.png)
- **Source code:**
allows users to download the source code on branch they're currently
viewing. Available extensions: `zip`, `tar`, `tar.gz`, and `tar.bz2`.
- **Directory:**
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`.
- **Artifacts:**
allows users to download the artifacts of the latest CI build.
## Redirects when changing repository paths
![repository Git flow](img/repo_graph.png)
When a repository path changes, it is essential to smoothly transition from the
old location to the new one. GitLab provides two kinds of redirects: the web UI
and Git push/pull redirects.
## What happens when a repository path changes
Depending on the situation, different things apply.
When a repository path changes, GitLab handles the transition from the
old location to the new one with a redirect.
When [renaming a user](../../profile/index.md#change-your-username),
[changing a group path](../../group/index.md#change-a-groups-path) or [renaming a repository](../settings/index.md#renaming-a-repository):
When you [rename a user](../../profile/index.md#change-your-username),
[change a group path](../../group/index.md#change-a-groups-path), or [rename a repository](../settings/index.md#renaming-a-repository):
- Existing web URLs for the namespace and anything under it (such as projects) will
redirect to the new URLs.
- Starting with GitLab 10.3, existing Git remote URLs for projects under the
namespace redirect to the new remote URL. Every time you push/pull to a
repository that has changed its location, a warning message to update
your remote is displayed instead of rejecting your action.
This means that any automation scripts, or Git clients continue to
work after a rename, making any transition a lot smoother.
- 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.
another group, user, or project.
## Troubleshooting
### Repository Languages: excessive CPU use
GitLab uses a Ruby gem to scan all the files in the repository to determine what languages are used.
[Sometimes this can use excessive CPU](https://gitlab.com/gitlab-org/gitaly/-/issues/1565) if
a file type needs to be parsed by the gem to determine what sort of file it is.
To determine which languages are in a repository's files, GitLab uses a Ruby gem.
When the gem parses a file to determine which type it is, [the process can use excessive CPU](https://gitlab.com/gitlab-org/gitaly/-/issues/1565).
The gem contains a [heuristics configuration file](https://github.com/github/linguist/blob/master/lib/linguist/heuristics.yml)
that defines what file extensions need to be parsed.
that defines which file extensions must be parsed.
Excessive CPU use has been reported for files with the extension `.txt` and XML files with
a file extension that is not defined by the gem.
Files with the `.txt` extension and XML files with an extension not defined by the gem can take excessive CPU.
The workaround is to specify what language to assign to specific file extensions.
The workaround is to specify the language to assign to specific file extensions.
The same approach should also allow misidentified file types to be fixed.
1. Identify which language to specify. The gem contains a [configuration file for known data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
The entry for `Text` files, for example:
1. Identify the language to specify. The gem contains a [configuration file for known data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
To add an entry for text files, for example:
```yaml
Text:
......@@ -350,4 +277,17 @@ The same approach should also allow misidentified file types to be fixed.
*.txt linguist-language=Text
```
`*.txt` files have an entry in the heuristics file. The example above prevents parsing of these files.
`*.txt` files have an entry in the heuristics file. This example prevents parsing of these files.
## Related topics
- To lock files and prevent change conflicts, use [file locking](../file_lock.md).
- [Repository API](../../../api/repositories.md).
- [Find files](file_finder.md) in a repository.
- [Branches](branches/index.md).
- [File templates](web_editor.md#template-dropdowns).
- [Create a directory](web_editor.md#create-a-directory).
- [Start a merge request](web_editor.md#tips).
- [Find file history](git_history.md).
- [Identify changes by line (Git blame)](git_blame.md).
- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md).
doc/user/project/settings/index.md
View file @ 511eab8d
......@@ -273,7 +273,7 @@ To rename a repository:
Remember that this can have unintended side effects since everyone with the
old URL can't push or pull. Read more about what happens with the
[redirects when renaming repositories](../repository/index.md#redirects-when-changing-repository-paths).
[redirects when renaming repositories](../repository/index.md#what-happens-when-a-repository-path-changes).
#### Transferring an existing project into another namespace
......@@ -297,7 +297,7 @@ To transfer a project:
Once done, you are redirected to the new project's namespace. At this point,
read what happens with the
[redirects from the old project to the new one](../repository/index.md#redirects-when-changing-repository-paths).
[redirects from the old project to the new one](../repository/index.md#what-happens-when-a-repository-path-changes).
NOTE:
GitLab administrators can use the administration interface to move any project to any
......
doc/user/project/working_with_projects.md
View file @ 511eab8d
......@@ -333,7 +333,7 @@ For public projects, and to members of internal and private projects
with [permissions to view the project's code](../permissions.md#project-members-permissions):
- The content of a
[`README` or an index file](repository/#repository-readme-and-index-files)
[`README` or an index file](repository/index.md#readme-and-index-files)
is displayed (if any), followed by the list of directories in the
project's repository.
- If the project doesn't contain either of these files, the
......
doc/user/shortcuts.md
View file @ 511eab8d
......@@ -126,7 +126,7 @@ These shortcuts are available when editing a file with the [Web IDE](project/web
### Repository graph
These shortcuts are available when viewing the project [repository graph](project/repository/index.md#repository-graph)
These shortcuts are available when viewing the project [repository graph](project/repository/index.md#repository-history-graph)
page (navigate to **Repository > Graph**):
| Keyboard shortcut | Description |
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7