diff options
Diffstat (limited to 'doc/user/project/repository/index.md')
| -rw-r--r-- | doc/user/project/repository/index.md | 418 |
1 files changed, 179 insertions, 239 deletions
diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index ed5bcc1f85a..7919850b8cc 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -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: + +- [Create a project](../../../user/project/working_with_projects.md#create-a-project) or +- [Fork an existing project](forking_workflow.md). + +## 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](web_editor.md). + - [From the command line](../../../gitlab-basics/command-line-commands.md). + +## Commit changes to a repository + +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. + +- **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). + +## Clone a repository + +You can [clone a repository by using the command line](../../../gitlab-basics/start-using-git.md#clone-a-repository). + +Alternatively, you can clone directly into a code editor. + +### 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 be cloned +into Xcode on macOS. + +1. From the GitLab UI, go to the project's overview page. +1. Select **Clone**. +1. Select **Xcode**. + +The project is cloned onto your computer 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 **Clone with Visual Studio Code** under either HTTPS or SSH method. +1. Select a folder to clone the project into. + +When VS Code has successfully cloned your project, it opens the folder. -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. +## Download the code in a repository -> **Important:** -For security reasons, when using the command line, we strongly recommend -that you [connect with GitLab via SSH](../../../ssh/README.md). +> - 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. -## Files +You can download the source code that's stored in 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: +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. -### Create and edit files +## Repository languages -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). +For the default branch of each repository, GitLab determines which programming languages +are used. This information is displayed on the **Project information** page. -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. + -**From the user interface:** +When new files are added, this information can take up to five minutes to update. -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): +### Add repository languages -- [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) +Not all files are detected and listed on the **Project information** page. Documentation, +vendor code, and most markup languages are excluded. -**From the command line:** +You can change this behavior by overriding the default settings. -To get started with the command line, please read through the -[command line basics documentation](../../../gitlab-basics/command-line-commands.md). +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: -### Find files + ```plaintext + *.proto linguist-detectable=true + ``` -Use the GitLab [file finder](file_finder.md) to search for files in a repository. +View a list of +[supported data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). -### Supported markup languages and extensions +This feature can use excessive CPU. +For more information, see the [troubleshooting section](#repository-languages-excessive-cpu-use). -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. +### Supported markup languages -Just pick the right extension for your files and GitLab renders them -according to the markup language. +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. - -They can either be plain text or have an extension of a -[supported markup language](#supported-markup-languages-and-extensions): - -Some things to note about precedence: +### README and index files -1. 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`. +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). -### 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 both a `README` and an `index` file are present, the `README` always + takes precedence. +- 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: +To render an OpenAPI file: -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). +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. -## Branches +## Repository size -For details, see [Branches](branches/index.md). +The **Project information** 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. -## Commits +The size can differ slightly from one instance to another due to compression, housekeeping, and other factors. -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. +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). -- **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). - -## Project and repository size +## Repository contributor graph -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. +All code contributors are displayed under your project's **Repository > Contributors**. -The project size may 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). - -## 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: +The graph shows the contributor with the most commits to the fewest.  -## 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: - - - -Find it under your project's **Repository > Graph**. +## Repository history 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. - - - -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)** +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. -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 - -Learn how to [clone a repository through the command line](../../../gitlab-basics/start-using-git.md#clone-a-repository). - -Alternatively, clone directly into a code editor as documented below. - -### Clone and open in Apple Xcode +Go to your project's **Repository > Graph**. -> [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: - - - -- **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 + -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). |