diff options
Diffstat (limited to 'doc/user/project/repository')
24 files changed, 283 insertions, 89 deletions
diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md new file mode 100644 index 00000000000..1363d883e76 --- /dev/null +++ b/doc/user/project/repository/branches/default.md @@ -0,0 +1,180 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: concepts, howto +--- + +# Default branch + +When you create a new [project](../../index.md), GitLab creates a default branch +in the repository. A default branch has special configuration options not shared +by other branches: + +- It's [initially protected](../../protected_branches.md#protected-branches) against + accidental deletion and forced pushes. +- When a merge request uses an + [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically) + to close an issue, the work is merged into this branch. + +The name of your [new project's](../../index.md) default branch depends on any +instance-level or group-level configuration changes made by your GitLab administrator. +GitLab checks first for specific customizations, then checks at a broader level, +using the GitLab default only if no customizations are set: + +1. A [project-specific](#change-the-default-branch-name-for-a-project) custom default branch name. +1. A [subgroup-level](#group-level-custom-initial-branch-name) custom default branch name. +1. A [group-level](#group-level-custom-initial-branch-name) custom default branch name. +1. An [instance-level](#instance-level-custom-initial-branch-name) custom default branch name. **(FREE SELF)** +1. If no custom default branch name is set at any level, GitLab defaults to: + - `main`: Projects created with GitLab 14.0 or later. + - `master`: Projects created before GitLab 14.0. + +In the GitLab UI, you can change the defaults at any level. GitLab also provides +the [Git commands you need](#update-the-default-branch-name-in-your-repository) to update your copy of the repository. + +## Change the default branch name for a project + +To update the default branch name for an individual [project](../../index.md): + +1. Sign in to GitLab as a user with [Administrator](../../../permissions.md) permissions. +1. In the left navigation menu, go to **Settings > Repository**. +1. Expand **Default branch**, and select a new default branch. +1. (Optional) Select the **Auto-close referenced issues on default branch** check box to close + issues when a merge request + [uses a closing pattern](../../issues/managing_issues.md#closing-issues-automatically). +1. Select **Save changes**. + +API users can also use the `default_branch` attribute of the +[Projects API](../../../../api/projects.md) when creating or editing a project. + +## Change the default branch name for an instance or group + +GitLab administrators can configure a new default branch name at the +[instance level](#instance-level-custom-initial-branch-name) or +[group level](#group-level-custom-initial-branch-name). + +### Instance-level custom initial branch name **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2. +> - It's deployed behind a feature flag, enabled by default. +> - It cannot be enabled or disabled per-project. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). + +GitLab [administrators](../../../permissions.md) of self-managed instances can +customize the initial branch for projects hosted on that instance. Individual +groups and subgroups can override this instance-wide setting for their projects. + +1. Go to **Admin Area > Settings > Repository**. +1. Expand **Default initial branch name**. +1. Change the default initial branch to a custom name of your choice. +1. Select **Save changes**. + +Projects created on this instance after you change the setting use the +custom branch name, unless a group-level or subgroup-level configuration +overrides it. + +#### Enable or disable custom initial branch name **(FREE SELF)** + +Setting the default initial branch name is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) +can opt to disable it for your instance. + +To disable it: + +```ruby +Feature.disable(:global_default_branch_name) +``` + +To enable it: + +```ruby +Feature.enable(:global_default_branch_name) +``` + +### Group-level custom initial branch name **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221014) in GitLab 13.6. + +Administrators of groups and subgroups can configure the default branch name for a group: + +1. Go to the group **Settings > Repository**. +1. Expand **Default initial branch name**. +1. Change the default initial branch to a custom name of your choice. +1. Select **Save changes**. + +Projects created in this group after you change the setting use the custom branch name, +unless a subgroup configuration overrides it. + +## Update the default branch name in your repository + +WARNING: +Changing the name of your default branch can potentially break tests, +CI/CD configuration, services, helper utilities, and any integrations your repository +uses. Before you change this branch name, consult with your project owners and maintainers. +Ensure they understand the scope of this change includes references to the old +branch name in related code and scripts. + +When changing the default branch name for an existing repository, you should preserve +the history of your default branch by renaming it, instead of deleting it. This example +renames a Git repository's (`example`) default branch. + +1. On your local command line, navigate to your `example` repository, and ensure + you're on the default branch: + + ```plaintext + cd example + git checkout master + ``` + +1. Rename the existing default branch to the new name (`main`). The argument `-m` + transfers all commit history to the new branch: + + ```plaintext + git branch -m master main + ``` + +1. Push the newly created `main` branch upstream, and set your local branch to track + the remote branch with the same name: + + ```plaintext + git push -u origin main + ``` + +1. If you plan to remove the old default branch, update `HEAD` to point to your new default branch, `main`: + + ```plaintext + git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main + ``` + +1. Sign in to GitLab as an [administrator](../../../permissions.md) and follow + the instructions to + [change the default branch for this project](#change-the-default-branch-name-for-a-project). + Select `main` as your new default branch. +1. Protect your new `main` branch as described in the [protected branches documentation](../../protected_branches.md). +1. (Optional) If you want to delete the old default branch: + 1. Verify that nothing is pointing to it. + 1. Delete the branch on the remote: + + ```plaintext + git push origin --delete master + ``` + + You can delete the branch at a later time, after you confirm the new default branch is working as expected. + +1. Notify your project contributors of this change, because they must also take some steps: + + - Contributors should pull the new default branch to their local copy of the repository. + - Contributors with open merge requests that target the old default branch should manually + re-point the merge requests to use `main` instead. +1. In your repository, update any references to the old branch name in your code. +1. Update references to the old branch name in related code and scripts that reside outside + your repository, such as helper utilities and integrations. + +## Resources + +- [Discussion of default branch renaming](https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/) + on the Git mailing list +- [March 2021 blog post: The new Git default branch name](https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/) diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png Binary files differindex da7d5268b3b..fdda3858c3b 100644 --- a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png +++ b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index d049b2108ee..f2562ef89e3 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -19,12 +19,14 @@ After pushing your changes to a new branch, you can: - [Discuss](../../../discussions/index.md) your implementation with your team - Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md). -With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request -[approval](../../merge_requests/merge_request_approvals.md) from your managers. +You can also request [approval](../../merge_requests/merge_request_approvals.md) +from your managers. For more information on managing branches using the GitLab UI, see: -- [Default branches](#default-branch) +- [Default branches](default.md): When you create a new [project](../../index.md), GitLab creates a + default branch for the repository. You can change this setting at the project, + subgroup, group, or instance level. - [Create a branch](../web_editor.md#create-a-new-branch) - [Protected branches](../../protected_branches.md#protected-branches) - [Delete merged branches](#delete-merged-branches) @@ -41,55 +43,6 @@ See also: - [GitLab Flow](../../../../university/training/gitlab_flow.md) documentation. - [Getting started with Git](../../../../topics/git/index.md) and GitLab. -## Default branch - -When you create a new [project](../../index.md), GitLab sets `master` as the default -branch of the repository. You can choose another branch to be your project's -default under your project's **Settings > Repository**. - -When closing issues directly from merge requests through the [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically), -the target is the project's **default branch**. - -The default branch is also initially [protected](../../protected_branches.md#protected-branches) -against accidental deletion and forced pushes. - -### Custom initial branch name **(FREE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2. -> - It's deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It cannot be enabled or disabled per-project. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). **(FREE SELF)** - -By default, when you create a new project in GitLab, the initial branch is called `master`. -For self-managed instances, a GitLab administrator can customize the initial branch name to something -else. This way, every new project created from then on starts from the custom branch name rather than `master`. To do so: - -1. Go to the **Admin Area > Settings > Repository** and expand **Default initial - branch name**. -1. Change the default initial branch to a custom name of your choice. -1. **Save Changes**. - -#### Enable or disable custom initial branch name **(FREE SELF)** - -Setting the default initial branch name is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) -can opt to disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:global_default_branch_name) -``` - -To enable it: - -```ruby -Feature.enable(:global_default_branch_name) -``` - ## Compare To compare branches in a repository: diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 3af7a5045c4..42b82f2c360 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -7,17 +7,13 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' # File finder **(FREE)** -> [Introduced](https://github.com/gitlabhq/gitlabhq/pull/9889) in GitLab 8.4. - The file finder feature allows you to search for a file in a repository using the -GitLab UI. - -You can find the **Find File** button when in the **Files** section of a -project. +GitLab UI. To use it: - +1. Go to your project's **Repository > Files**. +1. In the upper right corner, select **Find File**. -If you prefer to keep their fingers on the keyboard, use the +If you prefer to keep your fingers on the keyboard, use the [shortcut button](../../shortcuts.md), which you can invoke from anywhere in a project. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index c8922890deb..33ab5f6580d 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -18,26 +18,37 @@ submit them through a merge request to the repository you don't have access to. ## Creating a fork -Forking a project is, in most cases, a two-step process. +To fork an existing project in GitLab: -1. On the project's home page, in the top right, click the **Fork** button. +1. On the project's home page, in the top right, click **{fork}** **Fork**. -  +  -1. Click a namespace to fork to. Only namespaces you have Developer and higher [permissions](../../permissions.md) for are shown. +1. Select the project to fork to: - NOTE: - The project path must be unique within the namespace. + - *(Recommended method)* Below **Select a namespace to fork the project**, identify + the project you want to fork to, and click **Select**. Only namespaces you have + Developer and higher [permissions](../../permissions.md) for are shown. + +  -  + - *(Experimental method)* If your GitLab administrator has + [enabled the experimental fork project form](#enable-or-disable-the-fork-project-form), read + [Create a fork with the fork project form](#create-a-fork-with-the-fork-project-form). + Only namespaces you have Developer and higher + [permissions](../../permissions.md) for are shown. + + NOTE: + The project path must be unique in the namespace. -The fork is created. The permissions you have in the namespace are your permissions in the fork. +GitLab creates your fork, and redirects you to the project page for your new fork. +The permissions you have in the namespace are your permissions in the fork. WARNING: When a public project with the repository feature set to **Members Only** is forked, the repository is public in the fork. The owner -of the fork must manually change the visibility. This is being -fixed in [#36662](https://gitlab.com/gitlab-org/gitlab/-/issues/36662). +of the fork must manually change the visibility. Issue +[#36662](https://gitlab.com/gitlab-org/gitlab/-/issues/36662) exists for this issue. ## Repository mirroring @@ -71,3 +82,44 @@ changes are added to the repository and branch you're merging into. ## Removing a fork relationship You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#removing-a-fork-relationship). + +## Create a fork with the fork project form **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-the-fork-project-form). **(FREE SELF)** + +This experimental version of the fork project form is available only if your GitLab +administrator has [enabled it](#enable-or-disable-the-fork-project-form): + + + +To use it, follow the instructions at [Creating a fork](#creating-a-fork) and provide: + +- The project name. +- The project URL. +- The project slug. +- *(Optional)* The project description. +- The visibility level for your fork. + +### Enable or disable the fork project form **(FREE SELF)** + +The new [fork project form](#create-a-fork-with-the-fork-project-form) is under +development and not ready for production use. It is deployed behind a feature flag +that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:fork_project_form) +``` + +To disable it: + +```ruby +Feature.disable(:fork_project_form) +``` diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 0f49932d0c6..198993e21f3 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -8,17 +8,15 @@ description: "Documentation on Git file blame." # Git file blame **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/commit/39c657930625ddc3ac8a921f01ffc83acadce68f) in GitLab 2.5. - [Git blame](https://git-scm.com/docs/git-blame) provides more information about every line in a file, including the last modified time, author, and -commit hash. - -You can find the **Blame** button with each file in a project. +commit hash. To view it for a file: - +1. Go to your project's **Repository > Files**. +1. Select the file you want to review. +1. In the upper right corner, select **Blame**. -When you select the **Blame** button, this information is shown: +When you select **Blame**, this information is displayed:  diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 1b30a0b0f5f..356f02a4902 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -8,16 +8,13 @@ description: "Documentation on Git file history." # Git file history **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/blob/9ba1224867665844b117fa037e1465bb706b3685/app/controllers/commits_controller.rb) in GitLab 0.8.0 - Git file History provides information about the commit history associated -with a file. - -You can find the **History** button with each file in a project. +with a file. To use it: - +1. Go to your project's **Repository > Files**. +1. In the upper right corner, select **History**. -When you select the **History** button, this information displays: +When you select **History**, this information is displayed:  diff --git a/doc/user/project/repository/img/contributors_graph.png b/doc/user/project/repository/img/contributors_graph.png Binary files differindex c31da7aa1ff..83fdf1fc41f 100644 --- a/doc/user/project/repository/img/contributors_graph.png +++ b/doc/user/project/repository/img/contributors_graph.png diff --git a/doc/user/project/repository/img/download_source_code.png b/doc/user/project/repository/img/download_source_code.png Binary files differindex 56808061980..8d62d19b291 100644 --- a/doc/user/project/repository/img/download_source_code.png +++ b/doc/user/project/repository/img/download_source_code.png diff --git a/doc/user/project/repository/img/file_blame_button_v12_6.png b/doc/user/project/repository/img/file_blame_button_v12_6.png Binary files differdeleted file mode 100644 index e7aa0d1ea3f..00000000000 --- a/doc/user/project/repository/img/file_blame_button_v12_6.png +++ /dev/null diff --git a/doc/user/project/repository/img/file_finder_find_button_v12_10.png b/doc/user/project/repository/img/file_finder_find_button_v12_10.png Binary files differdeleted file mode 100644 index 51545f63fde..00000000000 --- a/doc/user/project/repository/img/file_finder_find_button_v12_10.png +++ /dev/null diff --git a/doc/user/project/repository/img/file_history_button_v12_6.png b/doc/user/project/repository/img/file_history_button_v12_6.png Binary files differdeleted file mode 100644 index e7aa0d1ea3f..00000000000 --- a/doc/user/project/repository/img/file_history_button_v12_6.png +++ /dev/null diff --git a/doc/user/project/repository/img/fork_form_v13_10.png b/doc/user/project/repository/img/fork_form_v13_10.png Binary files differnew file mode 100644 index 00000000000..00c2f89a844 --- /dev/null +++ b/doc/user/project/repository/img/fork_form_v13_10.png diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png Binary files differnew file mode 100644 index 00000000000..74f65cb663d --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png Binary files differindex 4843cc671ae..f48cf176ba1 100644 --- a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png +++ b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png diff --git a/doc/user/project/repository/img/forking_workflow_fork_button.png b/doc/user/project/repository/img/forking_workflow_fork_button.png Binary files differdeleted file mode 100644 index eea62892232..00000000000 --- a/doc/user/project/repository/img/forking_workflow_fork_button.png +++ /dev/null diff --git a/doc/user/project/repository/img/forking_workflow_fork_button_v13_10.png b/doc/user/project/repository/img/forking_workflow_fork_button_v13_10.png Binary files differnew file mode 100644 index 00000000000..376beb803a7 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_fork_button_v13_10.png diff --git a/doc/user/project/repository/img/repo_graph.png b/doc/user/project/repository/img/repo_graph.png Binary files differindex 28da8ad9589..fcccedbc436 100644 --- a/doc/user/project/repository/img/repo_graph.png +++ b/doc/user/project/repository/img/repo_graph.png diff --git a/doc/user/project/repository/img/web_editor_line_link_v13_10.png b/doc/user/project/repository/img/web_editor_line_link_v13_10.png Binary files differnew file mode 100644 index 00000000000..36347afcbe8 --- /dev/null +++ b/doc/user/project/repository/img/web_editor_line_link_v13_10.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index b9145364e3b..70c5ef63dd4 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -257,7 +257,7 @@ prompted to open XCode. ### Clone and open in Visual Studio Code -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.8. +> [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: diff --git a/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook.png b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook.png Binary files differindex 52c5c5aea32..a12fabcdd2a 100644 --- a/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook.png +++ b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook.png diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index e4a3e6d6ef1..4b649bab4d9 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -13,7 +13,7 @@ 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 are -rendered to HTML when viewed. +rendered to HTML when viewed:  @@ -26,4 +26,4 @@ You can deploy [Jupyter Hub as a GitLab managed app](../../../clusters/applicati ## Jupyter Git integration -Find out how to [leverage JupyterLab’s Git extension on your Kubernetes cluster](../../../clusters/applications.md#jupyter-git-integration). +Find out how to [leverage JupyterLab's Git extension on your Kubernetes cluster](../../../clusters/applications.md#jupyter-git-integration). diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 7847930366a..323a2efce76 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -143,10 +143,10 @@ To clean up a repository: 1. Upload a list of objects. For example, a `commit-map` file created by `git filter-repo` which is located in the `filter-repo` directory. - If your `commit-map` file is larger than 10MB, the file can be split and uploaded piece by piece: + If your `commit-map` file is larger than about 250KB or 3000 lines, the file can be split and uploaded piece by piece: ```shell - split -l 100000 filter-repo/commit-map filter-repo/commit-map- + split -l 3000 filter-repo/commit-map filter-repo/commit-map- ``` 1. Click **Start cleanup**. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index efa35c1ceac..b6bde46b26a 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -56,6 +56,24 @@ NOTE: The **Set up CI/CD** button does not appear on an empty repository. For the button to display, add a file to your repository. +## Highlight lines + +Web Editor enables you to highlight a single line by adding specially formatted +hash information to the URL's file path segment. For example, the file path segment +`MY_FILE.js#L3` instructs the Web Editor to highlight line 3. + +The Web Editor also enables you to highlight multiple lines using a similar pattern. In +this case, the file path segment `MY_FILE.js#L3-10` instructs the Web Editor to +highlight lines 3 to 10 of the file. + +You don't need to construct these lines manually. Instead, you can: + +1. Hover over the number of a line you want to be highlighted when sharing. +1. Right-click the number with your mouse. +1. Click **Copy Link Address** in the context menu. + +  + ## Upload a file The ability to create a file is great when the content is text. However, this |
