diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 13:34:06 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 13:34:06 +0300 |
| commit | 859a6fb938bb9ee2a317c46dfa4fcc1af49608f0 (patch) | |
| tree | d7f2700abe6b4ffcb2dcfc80631b2d87d0609239 /doc/topics | |
| parent | 446d496a6d000c73a304be52587cd9bbc7493136 (diff) | |
Add latest changes from gitlab-org/gitlab@13-9-stable-eev13.9.0-rc42
Diffstat (limited to 'doc/topics')
27 files changed, 275 insertions, 251 deletions
diff --git a/doc/topics/airgap/index.md b/doc/topics/airgap/index.md deleted file mode 100644 index 3866ec50253..00000000000 --- a/doc/topics/airgap/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_to: '../offline/index.md' ---- diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 0e51042193c..1988e3e2890 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -33,8 +33,8 @@ This page gathers all the resources for the topic **Authentication** within GitL - [Atlassian Crowd OmniAuth Provider](../../administration/auth/crowd.md) - [CAS OmniAuth Provider](../../integration/cas.md) - [SAML OmniAuth Provider](../../integration/saml.md) - - [SAML for GitLab.com Groups](../../user/group/saml_sso/index.md) **(SILVER ONLY)** - - [SCIM user provisioning for GitLab.com Groups](../../user/group/saml_sso/scim_setup.md) **(SILVER ONLY)** + - [SAML for GitLab.com Groups](../../user/group/saml_sso/index.md) **(PREMIUM SAAS)** + - [SCIM user provisioning for GitLab.com Groups](../../user/group/saml_sso/scim_setup.md) **(PREMIUM SAAS)** - [Okta SSO provider](../../administration/auth/okta.md) - [Kerberos integration (GitLab EE)](../../integration/kerberos.md) **(STARTER)** @@ -42,12 +42,16 @@ This page gathers all the resources for the topic **Authentication** within GitL - [OAuth 2 Tokens](../../api/README.md#oauth2-tokens) - [Personal access tokens](../../api/README.md#personalproject-access-tokens) -- [Project access tokens](../../api/README.md#personalproject-access-tokens) **(CORE ONLY)** +- [Project access tokens](../../api/README.md#personalproject-access-tokens) **(FREE SELF)** - [Impersonation tokens](../../api/README.md#impersonation-tokens) - [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth2-provider) ## Third-party resources +<!-- vale gitlab.Spelling = NO --> + - [Kanboard Plugin GitLab Authentication](https://github.com/kanboard/plugin-gitlab-auth) - [Jenkins GitLab OAuth Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+OAuth+Plugin) - [OKD - Configuring Authentication and User Agent](https://docs.okd.io/3.11/install_config/configuring_authentication.html#GitLab) + +<!-- vale gitlab.Spelling = YES -->
\ No newline at end of file diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 0d4f86f1284..b7f2a0768ef 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -4,7 +4,7 @@ group: Configure 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 --- -# Customizing Auto DevOps +# Customizing Auto DevOps **(FREE)** While [Auto DevOps](index.md) provides great defaults to get you started, you can customize almost everything to fit your needs. Auto DevOps offers everything from custom @@ -136,7 +136,7 @@ repository or by specifying a project variable: file in it, Auto DevOps detects the chart and uses it instead of the [default chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app), enabling you to control exactly how your application is deployed. -- **Project variable** - Create a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables) +- **Project variable** - Create a [project CI/CD variable](../../ci/variables/README.md) `AUTO_DEVOPS_CHART` with the URL of a custom chart to use, or create two project variables: `AUTO_DEVOPS_CHART_REPOSITORY` with the URL of a custom chart repository, and `AUTO_DEVOPS_CHART` with the path to the chart. @@ -163,7 +163,7 @@ to override the default chart values by setting `HELM_UPGRADE_EXTRA_ARGS` to `-- You can customize the `helm upgrade` command used in the [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) by passing options to the command with the `HELM_UPGRADE_EXTRA_ARGS` variable. For example, set the value of `HELM_UPGRADE_EXTRA_ARGS` to `--no-hooks` to disable -pre and post upgrade hooks when the command is executed. +pre-upgrade and post-upgrade hooks when the command is executed. See [the official documentation](https://helm.sh/docs/helm/helm_upgrade/) for the full list of options. @@ -171,7 +171,7 @@ list of options. ## Custom Helm chart per environment You can specify the use of a custom Helm chart per environment by scoping the environment variable -to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables). +to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables). ## Customizing `.gitlab-ci.yml` @@ -357,7 +357,7 @@ applications. NOTE: After you set up your replica variables using a -[project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables), +[project CI/CD variable](../../ci/variables/README.md), you can scale your application by redeploying it. WARNING: @@ -376,7 +376,7 @@ The following table lists variables related to the database. | `POSTGRES_ENABLED` | Whether PostgreSQL is enabled. Defaults to `true`. Set to `false` to disable the automatic deployment of PostgreSQL. | | `POSTGRES_USER` | The PostgreSQL user. Defaults to `user`. Set it to use a custom username. | | `POSTGRES_PASSWORD` | The PostgreSQL password. Defaults to `testing-password`. Set it to use a custom password. | -| `POSTGRES_DB` | The PostgreSQL database name. Defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-environment-variables). Set it to use a custom database name. | +| `POSTGRES_DB` | The PostgreSQL database name. Defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-cicd-variables). Set it to use a custom database name. | | `POSTGRES_VERSION` | Tag for the [`postgres` Docker image](https://hub.docker.com/_/postgres) to use. Defaults to `9.6.16` for tests and deployments as of GitLab 13.0 (previously `9.6.2`). If `AUTO_DEVOPS_POSTGRES_CHANNEL` is set to `1`, deployments uses the default version `9.6.2`. | ### Disable jobs diff --git a/doc/topics/autodevops/img/alexj_autodevops_min_v13_8.png b/doc/topics/autodevops/img/alexj_autodevops_min_v13_8.png Binary files differnew file mode 100644 index 00000000000..7dc37737835 --- /dev/null +++ b/doc/topics/autodevops/img/alexj_autodevops_min_v13_8.png diff --git a/doc/topics/autodevops/img/kai_autodevops_min_v13_8.png b/doc/topics/autodevops/img/kai_autodevops_min_v13_8.png Binary files differnew file mode 100644 index 00000000000..fa3ab4c1820 --- /dev/null +++ b/doc/topics/autodevops/img/kai_autodevops_min_v13_8.png diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 78be67a5196..d95e5568e0b 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -4,7 +4,7 @@ group: Configure 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 --- -# Auto DevOps +# Auto DevOps **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37115) in GitLab 10.0. > - Generally available on GitLab 11.0. @@ -37,6 +37,19 @@ For requirements, read [Requirements for Auto DevOps](requirements.md) for more For a developer's guide, read [Auto DevOps development guide](../../development/auto_devops.md). +### Share your feedback + +As Auto DevOps continues to gain popularity, and lowers the barrier to entry for +getting started with DevOps and CI/CD, see what our wider community is saying: + +From [AlexJonesax](https://twitter.com/AlexJonesax) and [KaiPMDH](https://twitter.com/KaiPMDH) on Twitter: + + + + + +We welcome everyone to [share your experience by tagging GitLab on Twitter](https://twitter.com/gitlab). + ## Enabled by default > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41729) in GitLab 11.3. @@ -153,20 +166,10 @@ any of the following places: **Continuous Integration and Delivery** section The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence -as other environment [variables](../../ci/variables/README.md#priority-of-environment-variables). +as other environment [variables](../../ci/variables/README.md#priority-of-cicd-variables). If the CI/CD variable is not set and the cluster setting is left blank, the instance-wide **Auto DevOps domain** setting is used if set. -NOTE: -If you use the [GitLab managed app for Ingress](../../user/clusters/applications.md#ingress), -the URL endpoint should be automatically configured for you. All you must do -is use its value for the `KUBE_INGRESS_BASE_DOMAIN` variable. - -NOTE: -`AUTO_DEVOPS_DOMAIN` was [deprecated in GitLab 11.8](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52363) -and replaced with `KUBE_INGRESS_BASE_DOMAIN`, and removed in -[GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56959). - Auto DevOps requires a wildcard DNS A record matching the base domain(s). For a base domain of `example.com`, you'd need a DNS entry like: @@ -283,7 +286,7 @@ used by Auto DevOps currently defines 3 environment names: Those environments are tied to jobs using [Auto Deploy](stages.md#auto-deploy), so except for the environment scope, they must have a different deployment domain. You must define a separate `KUBE_INGRESS_BASE_DOMAIN` variable for each of the above -[based on the environment](../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables). +[based on the environment](../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables). The following table is an example of how to configure the three different clusters: diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index effdb4d7b75..cd951e53bd1 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -4,7 +4,7 @@ group: Configure 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 --- -# Getting started with Auto DevOps +# Getting started with Auto DevOps **(FREE)** This step-by-step guide helps you use [Auto DevOps](index.md) to deploy a project hosted on GitLab.com to Google Kubernetes Engine. @@ -51,7 +51,7 @@ those projects provide a bare-bones application built on some well-known framewo 1. Give your project a name, optionally a description, and make it public so that you can take advantage of the features available in the - [GitLab Gold plan](https://about.gitlab.com/pricing/#gitlab-com). + [GitLab Ultimate plan](https://about.gitlab.com/pricing/).  @@ -177,7 +177,7 @@ The jobs are separated into stages: - The `test` job runs unit and integration tests by detecting the language and framework ([Auto Test](stages.md#auto-test)) - The `code_quality` job checks the code quality and is allowed to fail - ([Auto Code Quality](stages.md#auto-code-quality)) **(STARTER)** + ([Auto Code Quality](stages.md#auto-code-quality)) - The `container_scanning` job checks the Docker container if it has any vulnerabilities and is allowed to fail ([Auto Container Scanning](stages.md#auto-container-scanning)) - The `dependency_scanning` job checks if the application has any dependencies diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index 824874ed4d4..930938b7571 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -4,7 +4,7 @@ group: Configure 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 --- -# Requirements for Auto DevOps +# Requirements for Auto DevOps **(FREE)** You can set up Auto DevOps for [Kubernetes](#auto-devops-requirements-for-kubernetes), [Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs), @@ -46,12 +46,9 @@ To make full use of Auto DevOps with Kubernetes, you need: - **Base domain** (for [Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring)) - You need a domain configured with wildcard DNS, which all of your Auto DevOps - applications use. If you're using the - [GitLab-managed app for Ingress](../../user/clusters/applications.md#ingress), - the URL endpoint is automatically configured for you. - - You must also [specify the Auto DevOps base domain](index.md#auto-devops-base-domain). + You must [specify the Auto DevOps base domain](index.md#auto-devops-base-domain), + which all of your Auto DevOps applications use. This domain must be configured + with wildcard DNS. - **GitLab Runner** (for all stages) diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 23ba6ad3356..f1244a1ad1b 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -4,7 +4,7 @@ group: Configure 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 --- -# Stages of Auto DevOps +# Stages of Auto DevOps **(FREE)** The following sections describe the stages of [Auto DevOps](index.md). Read them carefully to understand how each one works. @@ -135,7 +135,7 @@ might want to use a [custom buildpack](customize.md#custom-buildpacks). ## Auto Code Quality -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab](https://about.gitlab.com/pricing/) 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in GitLab 13.2. Auto Code Quality uses the @@ -378,6 +378,12 @@ deploys with Auto DevOps can undo your changes. Also, if you change something and want to undo it by deploying again, Helm may not detect that anything changed in the first place, and thus not realize that it needs to re-apply the old configuration. +WARNING: +GitLab 14.0 [renews the Auto Deploy template](https://gitlab.com/gitlab-org/gitlab/-/issues/232788). +This might cause an unexpected failure on your Auto DevOps project due to the breaking changes on +the v2 `auto-deploy-image`. Follow [the upgrade guide](upgrading_auto_deploy_dependencies.md#upgrade-guide) +to upgrade your environments before upgrading to GitLab 14.0. + ### GitLab deploy tokens > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19507) in GitLab 11.0. diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 663060bf59d..5f8dfcdfc05 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -153,7 +153,7 @@ steps to upgrade to v2: ### Use a specific version of Auto Deploy dependencies -To use a specifc version of Auto Deploy dependencies, specify the previous Auto Deploy +To use a specific version of Auto Deploy dependencies, specify the previous Auto Deploy stable template that contains the [desired version of `auto-deploy-image` and `auto-deploy-app`](#verify-dependency-versions). For example, if the template is bundled in GitLab v13.3, change your `.gitlab-ci.yml` to: @@ -181,7 +181,7 @@ the latest Auto Deploy template into your `.gitlab-ci.yml`: ```yaml include: - template: Auto-DevOps.gitlab-ci.yml - - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Jobs/Deploy.latest.gitlab-ci.yml + - template: Jobs/Deploy.latest.gitlab-ci.yml ``` WARNING: diff --git a/doc/topics/autodevops/upgrading_chart.md b/doc/topics/autodevops/upgrading_chart.md deleted file mode 100644 index 2162969b53e..00000000000 --- a/doc/topics/autodevops/upgrading_chart.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'upgrading_auto_deploy_dependencies.md' ---- - -This document was moved to [another location](upgrading_auto_deploy_dependencies.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index 55432ad61fa..a0c4a41f90d 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -4,7 +4,7 @@ group: Configure 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 --- -# Upgrading PostgreSQL for Auto DevOps +# Upgrading PostgreSQL for Auto DevOps **(FREE)** Auto DevOps provides an [in-cluster PostgreSQL database](customize.md#postgresql-database-support) for your application. diff --git a/doc/topics/cron/index.md b/doc/topics/cron/index.md index 5abcc5e1eb1..88f8bd1858f 100644 --- a/doc/topics/cron/index.md +++ b/doc/topics/cron/index.md @@ -64,6 +64,6 @@ More examples of how to write a cron schedule can be found at ## How GitLab parses cron syntax strings -GitLab uses [fugit](https://github.com/floraison/fugit) to parse cron syntax +GitLab uses [`fugit`](https://github.com/floraison/fugit) to parse cron syntax strings on the server and [cron-validate](https://github.com/Airfooox/cron-validate) to validate cron syntax in the browser. diff --git a/doc/topics/git/feature_branch_development.md b/doc/topics/git/feature_branch_development.md index c9fb81600d4..842c39f0bfd 100644 --- a/doc/topics/git/feature_branch_development.md +++ b/doc/topics/git/feature_branch_development.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: how-tos --- -# Develop on a feature branch +# Develop on a feature branch **(FREE)** GitLab values encourage the use of [Minimal Viable Change (MVC)](https://about.gitlab.com/handbook/values/#minimal-viable-change-mvc). However, viable changes are not always small. In such cases, it can help to set up a dedicated feature branch. diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index 6a4608223b4..bf77ba3272c 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -6,7 +6,7 @@ type: concepts, howto description: "Introduction to Git rebase, force-push, and resolving merge conflicts through the command line." --- -# Introduction to Git rebase, force-push, and merge conflicts +# Introduction to Git rebase, force-push, and merge conflicts **(FREE)** This guide helps you to get started with rebasing, force-pushing, and fixing merge conflicts locally. @@ -69,7 +69,7 @@ changes by resetting `my-feature-branch` against `my-feature-branch-backup`: ``` Note that if you added changes to `my-feature-branch` after creating the backup branch, -you will lose them when resetting. +you lose them when resetting. ### Regular rebase @@ -116,7 +116,7 @@ example, `release-10-3`. You can also replace `origin` with other remote repositories, for example, `upstream`. To check what remotes you have linked to your local repository, you can run `git remote -v`. -If there are [merge conflicts](#merge-conflicts), Git will prompt you to fix +If there are [merge conflicts](#merge-conflicts), Git prompts you to fix them before continuing the rebase. To learn more, check Git's documentation on [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) @@ -126,13 +126,13 @@ and [rebasing strategies](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) You can use interactive rebase to modify commits. For example, amend a commit message, squash (join multiple commits into one), edit, or delete -commits. It is handy for changing past commit messages, -as well as for organizing the commit history of your branch to keep it clean. +commits. Use a rebase for changing past commit messages, +and organizing the commit history of your branch to keep it clean. NOTE: If you want to keep the default branch commit history clean, you don't need to -manually squash all your commits before merging every merge request; -with [Squash and Merge](../../user/project/merge_requests/squash_and_merge.md) +manually squash all your commits before merging every merge request. +With [Squash and Merge](../../user/project/merge_requests/squash_and_merge.md), GitLab does it automatically. When you want to change anything in recent commits, use interactive @@ -155,16 +155,17 @@ For example, if you're using [Vim](https://www.vim.org/) as the text editor in a macOS's `ZSH` shell, and you want to **squash** all the three commits (join them into one): -1. Press <kbd>i</kbd> on your keyboard to switch to Vim's editing mode. +1. Press <!-- vale gitlab.FirstPerson = NO --> <kbd>i</kbd> <!-- vale gitlab.FirstPerson = YES --> + on your keyboard to switch to Vim's editing mode. 1. Navigate with your keyboard arrows to edit the **second** commit keyword from `pick` to `squash` (or `s`). Do the same to the **third** commit. The first commit should be left **unchanged** (`pick`) as we want to squash the second and third into the first. -1. Press <kbd>Esc</kbd> to leave the editing mode. +1. Press <kbd>Escape</kbd> to leave the editing mode. 1. Type `:wq` to "write" (save) and "quit". 1. Git outputs the commit message so you have a chance to edit it: - - All lines starting with `#` will be ignored and not included in the commit - message. Everything else will be included. + - All lines starting with `#` are ignored and not included in the commit + message. Everything else is included. - To leave it as it is, type `:wq`. To edit the commit message: switch to the editing mode, edit the commit message, and save it as you just did. 1. If you haven't pushed your commits to the remote branch before rebasing, @@ -180,8 +181,8 @@ for a deeper look into interactive rebase. ## Force-push When you perform more complex operations, for example, squash commits, reset or -rebase your branch, you'll have to _force_ an update to the remote branch, -since these operations imply rewriting the commit history of the branch. +rebase your branch, you must _force_ an update to the remote branch. +These operations imply rewriting the commit history of the branch. To force an update, pass the flag `--force` or `-f` to the `push` command. For example: @@ -267,6 +268,6 @@ To fix conflicts locally, you can use the following method: Up to this point, you can run `git rebase --abort` to stop the process. Git aborts the rebase and rolls back the branch to the state you had before running `git rebase`. - Once you run `git rebase --continue` the rebase **cannot** be aborted. + After you run `git rebase --continue` the rebase **cannot** be aborted. 1. [Force-push](#force-push) to your remote branch. diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index 5979cad1c0e..17c5f31705f 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -6,7 +6,7 @@ description: 'This article describes how to install Git on macOS, Ubuntu Linux a type: howto --- -# Installing Git +# Installing Git **(FREE)** To begin contributing to GitLab projects, you will need to install the Git client on your computer. diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index cc4e546a244..52e8a42de76 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: index --- -# Git +# Git **(FREE)** Git is a [free and open source](https://git-scm.com/about/free-and-open-source) distributed version control system designed to handle everything from small to diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 6179175b4cd..14bb28d2477 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -6,7 +6,7 @@ type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs/index.html' --- -# Git Large File Storage (LFS) +# Git Large File Storage (LFS) **(FREE)** Managing large files such as audio, video and graphics files has always been one of the shortcomings of Git. The general recommendation is to not have Git repositories @@ -14,13 +14,13 @@ larger than 1GB to preserve performance.  -An LFS icon is shown on files tracked by Git LFS to denote if a file is stored -as a blob or as an LFS pointer. +Files tracked by Git LFS display an icon to indicate if the file is stored as a +blob or an LFS pointer. ## How it works Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication -to authorize client requests. Once the request is authorized, Git LFS client receives +to authorize client requests. After the request is authorized, Git LFS client receives instructions from where to fetch or where to push the large file. ## GitLab server configuration @@ -35,18 +35,18 @@ Documentation for GitLab instance administrators is under [LFS administration do ## Known limitations -- Git LFS v1 original API is not supported since it was deprecated early in LFS - development -- When SSH is set as a remote, Git LFS objects still go through HTTPS -- Any Git LFS request will ask for HTTPS credentials to be provided so a good Git - credentials store is recommended -- Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have - to add the URL to Git configuration manually (see [troubleshooting](#troubleshooting)) +- Git LFS v1 original API is not supported, because it was deprecated early in LFS + development. +- When SSH is set as a remote, Git LFS objects still go through HTTPS. +- Any Git LFS request asks for HTTPS credentials to be provided so a good Git + credentials store is recommended. +- Git LFS always assumes HTTPS so if you have GitLab server on HTTP you must + [add the URL to Git configuration manually](#troubleshooting). NOTE: With 8.12 GitLab added LFS support to SSH. The Git LFS communication still goes over HTTP, but now the SSH client passes the correct credentials -to the Git LFS client, so no action is required by the user. +to the Git LFS client. No action is required by the user. ## Using Git LFS @@ -60,8 +60,8 @@ git lfs install # initialize the Git LFS project git lfs track "*.iso" # select the file extensions that you want to treat as large files ``` -Once a certain file extension is marked for tracking as a LFS object you can use -Git as usual without having to redo the command to track a file with the same extension: +After you mark a file extension for tracking as a LFS object you can use +Git as usual without redoing the command to track a file with the same extension: ```shell cp ~/tmp/debian.iso ./ # copy a large file into the current directory @@ -71,7 +71,7 @@ git push origin master # sync the git repo and large file to the ``` **Make sure** that `.gitattributes` is tracked by Git. Otherwise Git -LFS will not be working properly for people cloning the project: +LFS doesn't work properly for people cloning the project: ```shell git add .gitattributes @@ -93,8 +93,8 @@ that are on the remote repository, such as for a branch from origin: git lfs fetch origin master ``` -Make sure your files aren't listed in `.gitignore`, otherwise, they will be ignored by Git thus will not -be pushed to the remote repository. +Make sure your files aren't listed in `.gitignore`, otherwise, they are ignored by Git +and are not pushed to the remote repository. ### Migrate an existing repository to Git LFS @@ -178,7 +178,7 @@ available to the project anymore. Probably the object was removed from the serve ### Invalid status for `<url>` : 501 -Git LFS will log the failures into a log file. +Git LFS logs the failures into a log file. To view this log file, while in project directory: ```shell @@ -201,12 +201,19 @@ If the status `error 501` is shown, it is because: remove the line and try to update your Git LFS client. Only version 1.0.1 and newer are supported. +<!-- vale gitlab.Spelling = NO --> + ### getsockopt: connection refused -If you push a LFS object to a project and you receive an error similar to: -`Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused`, +<!-- vale gitlab.Spelling = YES --> + +If you push an LFS object to a project and receive an error like this, the LFS client is trying to reach GitLab through HTTPS. However, your GitLab -instance is being served on HTTP. +instance is being served on HTTP: + +```plaintext +Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused +``` This behavior is caused by Git LFS using HTTPS connections by default when a `lfsurl` is not set in the Git configuration. @@ -222,10 +229,10 @@ git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs" NOTE: With 8.12 GitLab added LFS support to SSH. The Git LFS communication still goes over HTTP, but now the SSH client passes the correct credentials -to the Git LFS client, so no action is required by the user. +to the Git LFS client. No action is required by the user. -Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing -the LFS object on every push for every object, user HTTPS credentials are required. +Git LFS authenticates the user with HTTP Basic Authentication on every push for +every object, so user HTTPS credentials are required. By default, Git has support for remembering the credentials for each repository you use. This is described in [Git credentials man pages](https://git-scm.com/docs/gitcredentials). @@ -237,7 +244,7 @@ which you expect to push the objects: git config --global credential.helper 'cache --timeout=3600' ``` -This will remember the credentials for an hour after which Git operations will +This remembers the credentials for an hour, after which Git operations require re-authentication. If you are using OS X you can use `osxkeychain` to store and encrypt your credentials. @@ -258,7 +265,7 @@ If you are storing LFS files outside of GitLab you can disable LFS on the projec It is possible to host LFS objects externally by setting a custom LFS URL with `git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs`. -You might choose to do this if you are using an appliance like a Sonatype Nexus to store LFS data. If you choose to use an external LFS store, -GitLab will not be able to verify LFS objects which means that pushes will fail if you have GitLab LFS support enabled. +You might choose to do this if you are using an appliance like a <!-- vale gitlab.Spelling = NO --> Sonatype Nexus <!-- vale gitlab.Spelling = YES --> to store LFS data. If you choose to use an external LFS store, +GitLab can't verify LFS objects. Pushes then fail if you have GitLab LFS support enabled. -To stop push failure, LFS support can be disabled in the [Project settings](../../../user/project/settings/index.md). This means you will lose GitLab LFS value-adds (Verifying LFS objects, UI integration for LFS). +To stop push failure, LFS support can be disabled in the [Project settings](../../../user/project/settings/index.md), which also disables GitLab LFS value-adds (Verifying LFS objects, UI integration for LFS). diff --git a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md b/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md index 3bd754aabfb..3b3f1c0b46f 100644 --- a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Migration guide from Git Annex to Git LFS +# Migration guide from Git Annex to Git LFS **(FREE)** WARNING: Git Annex support [has been removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1648) in GitLab Enterprise @@ -37,9 +37,9 @@ ones that GitLab developed. ## Migration steps -Since Git Annex files are stored in a sub-directory of the normal repositories -(`.git/annex/objects`) and LFS files are stored outside of the repositories, -they are not compatible as they are using a different scheme. Therefore, the +Git Annex files are stored in a sub-directory of the normal repositories +(`.git/annex/objects`) and LFS files are stored outside of the repositories. +The two aren't compatible as they are using a different scheme. Therefore, the migration has to be done manually per repository. There are basically two steps you need to take in order to migrate from Git @@ -74,17 +74,17 @@ Fire up a terminal, navigate to your Git repository and: ### Disabling Git Annex in your repository Before changing anything, make sure you have a backup of your repository first. -There are a couple of ways to do that, but you can simply clone it to another +There are a couple of ways to do that, but you can clone it to another local path and maybe push it to GitLab if you want a remote backup as well. -Here you'll find a guide on -[how to back up a **git-annex** repository to an external hard drive](https://www.thomas-krenn.com/en/wiki/Git-annex_Repository_on_an_External_Hard_Drive). +A guide on +[how to back up a **git-annex** repository to an external hard drive](https://www.thomas-krenn.com/en/wiki/Git-annex_Repository_on_an_External_Hard_Drive) is also available. -Since Annex files are stored as objects with symlinks and cannot be directly +Because Annex files are stored as objects with symlinks and cannot be directly modified, we need to first remove those symlinks. NOTE: Make sure the you read about the [`direct` mode](https://git-annex.branchable.com/direct_mode/) as it contains -useful information that may fit in your use case. Note that `annex direct` is +information that may fit in your use case. The `annex direct` command is deprecated in Git Annex version 6, so you may need to upgrade your repository if the server also has Git Annex 6 installed. Read more in the [Git Annex troubleshooting tips](../../../administration/git_annex.md#troubleshooting-tips) section. @@ -133,7 +133,7 @@ if the server also has Git Annex 6 installed. Read more in the Deleted branch git-annex (was 2534d2c). ``` - This will `unannex` every file in the repository, leaving the original files. + This command runs `unannex` on every file in the repository, leaving the original files. 1. Switch back to `indirect` mode: @@ -161,7 +161,7 @@ if the server also has Git Annex 6 installed. Read more in the --- At this point, you have two options. Either add, commit and push the files -directly back to GitLab or switch to Git LFS. We will tackle the LFS switch in +directly back to GitLab or switch to Git LFS. The LFS switch is described in the next section. ### Enabling Git LFS in your repository @@ -194,7 +194,7 @@ GitLab.com), therefore, you don't need to do anything server-side. git lfs track images/ # per directory ``` - Once you do that, run `git status` and you'll see `.gitattributes` added + After this, run `git status` to see the `.gitattributes` added to your repository. It collects all file patterns that you chose to track via `git-lfs`. @@ -206,7 +206,7 @@ GitLab.com), therefore, you don't need to do anything server-side. git push ``` - If your remote is set up with HTTP, you will be asked to enter your login + If your remote is set up with HTTP, you are asked to enter your login credentials. If you have [2FA enabled](../../../user/profile/account/two_factor_authentication.md), make sure to use a [personal access token](../../../user/profile/account/two_factor_authentication.md#personal-access-tokens) instead of your password. @@ -244,5 +244,5 @@ git annex uninit - (Blog Post) [Getting Started with Git FLS](https://about.gitlab.com/blog/2017/01/30/getting-started-with-git-lfs-tutorial/) - (Blog Post) [Announcing LFS Support in GitLab](https://about.gitlab.com/blog/2015/11/23/announcing-git-lfs-support-in-gitlab/) - (Blog Post) [GitLab Annex Solves the Problem of Versioning Large Binaries with Git](https://about.gitlab.com/blog/2015/02/17/gitlab-annex-solves-the-problem-of-versioning-large-binaries-with-git/) -- (GitLab Docs) [Git Annex](../../../administration/git_annex.md) -- (GitLab Docs) [Git LFS](index.md) +- [Git Annex](../../../administration/git_annex.md) +- [Git LFS](index.md) diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index ef2675db6d4..98c7e59154e 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.md @@ -115,7 +115,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- so that we can force-push the rewritten repository: 1. Navigate to your project's **Settings > Repository** and - expand **Protected Branches**. + expand **Protected branches**. 1. Scroll down to locate the protected branches and click **Unprotect** the default branch. @@ -153,7 +153,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- 1. [Re-protect the default branch](../../../user/project/protected_branches.md): 1. Navigate to your project's **Settings > Repository** and - expand **Protected Branches**. + expand **Protected branches**. 1. Select the default branch from the **Branch** dropdown menu, and set up the **Allowed to push** and **Allowed to merge** rules. diff --git a/doc/topics/git/migrate_to_git_lfs/index.md b/doc/topics/git/migrate_to_git_lfs/index.md deleted file mode 100644 index c530fa1dcb1..00000000000 --- a/doc/topics/git/migrate_to_git_lfs/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../lfs/migrate_to_git_lfs.md' ---- - -This document was moved to [another location](../lfs/migrate_to_git_lfs.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/index.md b/doc/topics/git/numerous_undo_possibilities_in_git/index.md index f6571c7b277..c263609125f 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -5,23 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Numerous undo possibilities in Git +# Numerous undo possibilities in Git **(FREE)** -In this tutorial, we will show you different ways of undoing your work in Git, for which -we will assume you have a basic working knowledge of. Check the GitLab +This tutorial shows you different ways of undoing your work in Git. +We assume you have a basic working knowledge of Git. Check the GitLab [Git documentation](../index.md) for reference. -Also, we will only provide some general information of the commands, which is enough -to get you started for the easy cases/examples, but for anything more advanced -please refer to the [Git book](https://git-scm.com/book/en/v2). +We only provide some general information about the commands to get you started. +For more advanced examples, refer to the [Git book](https://git-scm.com/book/en/v2). -We will explain a few different techniques to undo your changes based on the stage -of the change in your current development. Also, keep in mind that [nothing in -Git is really deleted](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery). - -This means that until Git automatically cleans detached commits (which cannot be -accessed by branch or tag) it will be possible to view them with `git reflog` command -and access them with direct commit ID. Read more about _[redoing the undo](#redoing-the-undo)_ in the section below. +A few different techniques exist to undo your changes, based on the stage +of the change in your current development. Remember that +[nothing in Git is really deleted](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery). +Until Git cleans detached commits - commits that cannot be accessed by branch or tag - +you can view them with `git reflog` command, and access them with direct commit ID. +Read more about [redoing the undo](#redoing-the-undo) in the section below. > For more information about working with Git and GitLab: > @@ -30,13 +28,16 @@ and access them with direct commit ID. Read more about _[redoing the undo](#redo ## Introduction -This guide is organized depending on the [stage of development](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository) -where you want to undo your changes from and if they were shared with other developers -or not. Because Git is tracking changes a created or edited file is in the unstaged state +This guide is organized depending on the [stage of development](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository): + +- Where do you want to undo your changes from? +- Were they shared with other developers? + +Because Git tracks changes, a created or edited file is in the unstaged state (if created it is untracked by Git). After you add it to a repository (`git add`) you put a file into the **staged** state, which is then committed (`git commit`) to your local repository. After that, file can be shared with other developers (`git push`). -Here's what we'll cover in this tutorial: +This tutorial covers: - [Undo local changes](#undo-local-changes) which were not pushed to a remote repository: @@ -54,38 +55,38 @@ Here's what we'll cover in this tutorial: ### Branching strategy -[Git](https://git-scm.com/) is a de-centralized version control system, which means that beside regular +[Git](https://git-scm.com/) is a de-centralized version control system. Beside regular versioning of the whole repository, it has possibilities to exchange changes with other repositories. To avoid chaos with [multiple sources of truth](https://git-scm.com/about/distributed), various -development workflows have to be followed, and it depends on your internal +development workflows have to be followed. It depends on your internal workflow how certain changes or commits can be undone or changed. [GitLab Flow](https://about.gitlab.com/blog/2014/09/29/gitlab-flow/) provides a good balance between developers clashing with each other while -developing the same feature and cooperating seamlessly, but it does not enable +developing the same feature and cooperating seamlessly. However, it does not enable joined development of the same feature by multiple developers by default. When multiple developers develop the same feature on the same branch, clashing -with every synchronization is unavoidable, but a proper or chosen Git Workflow will -prevent that anything is lost or out of sync when the feature is complete. +with every synchronization is unavoidable. However, a proper or chosen Git Workflow +prevents lost or out-of-sync data when the feature is complete. You can also read through this blog post on [Git Tips & Tricks](https://about.gitlab.com/blog/2016/12/08/git-tips-and-tricks/) -to learn how to easily **do** things in Git. +to learn how to do things in Git. ## Undo local changes -Until you push your changes to any remote repository, they will only affect you. +Until you push your changes to any remote repository, they only affect you. That broadens your options on how to handle undoing them. Still, local changes can be on various stages and each stage has a different approach on how to tackle them. ### Unstaged local changes (before you commit) -When a change is made, but it is not added to the staged tree, Git itself -proposes a solution to discard changes to a certain file. +When a change is made, but not added to the staged tree, Git +proposes a solution to discard changes to the file. Suppose you edited a file to change the content using your favorite editor: @@ -93,7 +94,7 @@ Suppose you edited a file to change the content using your favorite editor: vim <file> ``` -Since you did not `git add <file>` to staging, it should be under unstaged files (or +Because you did not `git add <file>` to staging, it should be under unstaged files (or untracked if file was created). You can confirm that with: ```shell @@ -136,32 +137,37 @@ you would like to apply them at some later time. You can read more about it in ### Quickly save local changes -You are working on a feature when a boss drops by with an urgent task. Since your +You are working on a feature when a boss drops by with an urgent task. Because your feature is not complete, but you need to swap to another branch, you can use -`git stash` to save what you had done, swap to another branch, commit, push, -test, then get back to previous feature branch, do `git stash pop` and continue -where you left. +`git stash` to: + +- Save what you have done. +- Swap to another branch. +- Commit, push, and test. +- Return to the feature branch. +- Run `git stash pop`. +- Resume your work. -The example above shows that discarding all changes is not always a preferred option, -but Git provides a way to save them for later, while resetting the repository to state without +The example above shows that discarding all changes is not always a preferred option. +However, Git provides a way to save them for later, while resetting the repository to state without them. This is achieved by Git stashing command `git stash`, which in fact saves your current work and runs `git reset --hard`, but it also has various additional options like: -- `git stash save`, which enables including temporary commit message, which will help you identify changes, among with other options +- `git stash save`, which enables including temporary commit message, which helps you identify changes, among with other options - `git stash list`, which lists all previously stashed commits (yes, there can be more) that were not `pop`ed - `git stash pop`, which redoes previously stashed changes and removes them from stashed list - `git stash apply`, which redoes previously stashed changes, but keeps them on stashed list ### Staged local changes (before you commit) -Let's say you have added some files to staging, but you want to remove them from the -current commit, yet you want to retain those changes - just move them outside -of the staging tree. You also have an option to discard all changes with +If you add some files to staging, but you want to remove them from the +current commit while retaining those changes, move them outside +of the staging tree. You can also discard all changes with `git reset --hard` or think about `git stash` [as described earlier.](#quickly-save-local-changes) -Lets start the example by editing a file, with your favorite editor, to change the -content and add it to staging +Lets start the example by editing a file with your favorite editor to change the +content and add it to staging: ```shell vim <file> @@ -208,17 +214,17 @@ Now you have 4 options to undo your changes: ## Committed local changes -Once you commit, your changes are recorded by the version control system. +After you commit, your changes are recorded by the version control system. Because you haven't pushed to your remote repository yet, your changes are still not public (or shared with other developers). At this point, undoing -things is a lot easier, we have quite some workaround options. Once you push -your code, you'll have less options to troubleshoot your work. +things is a lot easier, we have quite some workaround options. After you push +your code, you have fewer options to troubleshoot your work. ### Without modifying history Through the development process some of the previously committed changes do not -fit anymore in the end solution, or are source of the bugs. Once you find the -commit which triggered bug, or once you have a faulty commit, you can simply +fit anymore in the end solution, or are source of the bugs. After you find the +commit which triggered bug, or identify a faulty commit, you can revert it with `git revert commit-id`. This command inverts (swaps) the additions and @@ -226,19 +232,19 @@ deletions in that commit, so that it does not modify history. Retaining history can be helpful in future to notice that some changes have been tried unsuccessfully in the past. -In our example we will assume there are commits `A`,`B`,`C`,`D`,`E` committed in this order: `A-B-C-D-E`, +In our example we assume there are commits `A`,`B`,`C`,`D`,`E` committed in this order: `A-B-C-D-E`, and `B` is the commit you want to undo. There are many different ways to identify commit -`B` as bad, one of them is to pass a range to `git bisect` command. The provided range includes -last known good commit (we assume `A`) and first known bad commit (where bug was detected - we will assume `E`). +`B` as bad. One of them is to pass a range to `git bisect` command. The provided range includes +last known good commit (we assume `A`) and first known bad commit where the bug was detected (we assume `E`). ```shell git bisect A..E ``` -Bisect will provide us with commit ID of the middle commit to test, and then guide us -through simple bisection process. You can read more about it [in official Git Tools](https://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git) -In our example we will end up with commit `B`, that introduced the bug/error. We have -4 options on how to remove it (or part of it) from our repository. +Bisect provides us with commit ID of the middle commit to test, and then guide us +through the bisection process. You can read more about it [in official Git Tools](https://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git) +Our example results in commit `B`, which introduced the bug/error. We have +these options to remove all or part of it from our repository: - Undo (swap additions and deletions) changes introduced by commit `B`: @@ -260,13 +266,13 @@ In our example we will end up with commit `B`, that introduced the bug/error. We - There is one command we also must not forget: **creating a new branch** from the point where changes are not applicable or where the development has hit a - dead end. For example you have done commits `A-B-C-D` on your feature-branch + dead end. For example you have done commits `A-B-C-D` on your feature branch and then you figure `C` and `D` are wrong. At this point you either reset to `B` - and do commit `F` (which will cause problems with pushing and if forced pushed also with other developers) - since branch now looks `A-B-F`, which clashes with what other developers have locally (you will - [change history](#with-history-modification)), or you simply checkout commit `B` create + and do commit `F` (which causes problems with pushing and if forced pushed also with other developers) + because the branch now looks `A-B-F`, which clashes with what other developers have locally (you will + [change history](#with-history-modification)), or you checkout commit `B` create a new branch and do commit `F`. In the last case, everyone else can still do their work while you have your new way to get it right and merge it back in later. Alternatively, with GitLab, you can [cherry-pick](../../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) @@ -291,7 +297,7 @@ provides interactive mode (`-i` flag) which enables you to: - **edit** the commit content (changes introduced by commit) and message. - **squash** multiple commits into a single one, and have a custom or aggregated commit message. -- **drop** commits - simply delete them. +- **drop** commits - delete them. - and few more options. Let us check few examples. Again there are commits `A-B-C-D` where you want to @@ -326,8 +332,8 @@ In case you want to modify something introduced in commit `B`. git commit -a ``` -You can find some more examples in [below section where we explain how to modify -history](#how-modifying-history-is-done) +You can find some more examples in the section explaining +[how to modify history](#how-modifying-history-is-done). ### Redoing the Undo @@ -391,12 +397,12 @@ git checkout -b new-path-of-feature ## Undo remote changes with modifying history This is useful when you want to *hide* certain things - like secret keys, -passwords, SSH keys, etc. It is and should not be used to hide mistakes, as -it will make it harder to debug in case there are some other bugs. The main -reason for this is that you loose the real development progress. **Also keep in +passwords, and SSH keys. It is and should not be used to hide mistakes, as +it makes it harder to debug in case there are some other bugs. The main +reason for this is that you loose the real development progress. Keep in mind that, even with modified history, commits are just detached and can still be -accessed through commit ID** - at least until all repositories perform -the cleanup of detached commits (happens automatically). +accessed through commit ID - at least until all repositories perform +the automated cleanup of detached commits.  @@ -404,16 +410,16 @@ the cleanup of detached commits (happens automatically). Modified history breaks the development chain of other developers, as changed history does not have matching commit IDs. For that reason it should not be -used on any public branch or on branch that *might* be used by other developers. +used on any public branch or on branch that might be used by other developers. When contributing to big open source repositories (for example, [GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/CONTRIBUTING.md#contribution-acceptance-criteria) -itself), it is acceptable to *squash* commits into a single one, to present a +itself), it is acceptable to squash commits into a single one, to present a nicer history of your contribution. Keep in mind that this also removes the comments attached to certain commits in merge requests, so if you need to retain traceability in GitLab, then modifying history is not acceptable. -A feature-branch of a merge request is a public branch and might be used by +A feature branch of a merge request is a public branch and might be used by other developers, but project process and rules might allow or require you to use `git rebase` (command that changes history) to reduce number of displayed commits on target branch after reviews are done (for example @@ -427,7 +433,7 @@ Never modify the commit history of `master` or shared branch. ### How modifying history is done After you know what you want to modify (how far in history or how which range of -old commits), use `git rebase -i commit-id`. This command will then display all the commits from +old commits), use `git rebase -i commit-id`. This command displays all the commits from current version to chosen commit ID and allow modification, squashing, deletion of that commits. @@ -458,12 +464,12 @@ pick <commit3-id> <commit3-commit-message> ``` NOTE: -It is important to notice that comment from the output clearly states that, if -you decide to abort, then do not just close your editor (as that will in-fact -modify history), but remove all uncommented lines and save. +The comment from the output clearly states that, if +you decide to abort, don't just close your editor (as that +modifies history), but remove all uncommented lines and save. -That is one of the reasons why `git rebase` should be used carefully on -shared and remote branches. But don't worry, there will be nothing broken until +Use `git rebase` carefully on +shared and remote branches, but rest assured: nothing is broken until you push back to the remote repository (so you can freely explore the different outcomes locally). @@ -486,7 +492,7 @@ file from history altogether use: git filter-branch --tree-filter 'rm filename' HEAD ``` -Since `git filter-branch` command might be slow on big repositories, there are +Because `git filter-branch` command might be slow on big repositories, there are tools that can use some of Git specifics to enable faster execution of common tasks (which is exactly what removing sensitive information file is about). An alternative is the open source community-maintained tool [BFG](https://rtyley.github.io/bfg-repo-cleaner/). @@ -497,8 +503,8 @@ Refer [Reduce repository size](../../../user/project/repository/reducing_the_rep ## Conclusion -There are various options of undoing your work with any version control system, but -because of de-centralized nature of Git, these options are multiplied (or limited) +Various options exist for undoing your work with any version control system, but +because of the de-centralized nature of Git, these options are multiplied (or limited) depending on the stage of your process. Git also enables rewriting history, but that should be avoided as it might cause problems when multiple developers are contributing to the same codebase. diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md index fa42cfd6e5b..d9c239486f5 100644 --- a/doc/topics/git/partial_clone.md +++ b/doc/topics/git/partial_clone.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Partial Clone +# Partial Clone **(FREE)** As Git repositories grow in size, they can become cumbersome to work with because of the large amount of history that must be downloaded, and the large diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index aace979004f..528a9a4ba00 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: howto --- -# Troubleshooting Git +# Troubleshooting Git **(FREE)** Sometimes things don't work the way they should or as you might expect when you're using Git. Here are some tips on troubleshooting and resolving issues @@ -14,7 +14,7 @@ with Git. ## Broken pipe errors on `git push` 'Broken pipe' errors can occur when attempting to push to a remote repository. -When pushing you will usually see: +When pushing you usually see: ```plaintext Write failed: Broken pipe @@ -45,14 +45,13 @@ set to 50MB. The default is 1MB. **If pushing over SSH**, first check your SSH configuration as 'Broken pipe' errors can sometimes be caused by underlying issues with SSH (such as authentication). Make sure that SSH is correctly configured by following the -instructions in the [SSH troubleshooting](../../ssh/README.md#troubleshooting) docs. +instructions in the [SSH troubleshooting](../../ssh/README.md#troubleshooting) documentation. -There's another option where you can prevent session timeouts by configuring -SSH 'keep alive' either on the client or on the server (if you are a GitLab -admin and have access to the server). +If you're a GitLab administrator and have access to the server, you can also prevent +session timeouts by configuring SSH `keep alive` either on the client or on the server. NOTE: -Configuring *both* the client and the server is unnecessary. +Configuring both the client and the server is unnecessary. **To configure SSH on the client side**: @@ -67,7 +66,7 @@ Configuring *both* the client and the server is unnecessary. - On Windows, if you are using PuTTY, go to your session properties, then navigate to "Connection" and under "Sending of null packets to keep - session active", set "Seconds between keepalives (0 to turn off)" to `60`. + session active", set `Seconds between keepalives (0 to turn off)` to `60`. **To configure SSH on the server side**, edit `/etc/ssh/sshd_config` and add: @@ -125,7 +124,7 @@ MaxStartups 100:30:200 ``` `100:30:200` means up to 100 SSH sessions are allowed without restriction, -after which 30% of connections will be dropped until reaching an absolute maximum of 200. +after which 30% of connections are dropped until reaching an absolute maximum of 200. Once configured, restart the SSH daemon for the change to take effect. @@ -140,7 +139,7 @@ sudo service sshd restart ## Timeout during `git push` / `git pull` If pulling/pushing from/to your repository ends up taking more than 50 seconds, -a timeout will be issued with a log of the number of operations performed +a timeout is issued. It contains a log of the number of operations performed and their respective timings, like the example below: ```plaintext @@ -154,7 +153,7 @@ and provide GitLab with more information on how to improve the service. ## `git clone` over HTTP fails with `transfer closed with outstanding read data remaining` error -If the buffer size is lower than what is allowed in the request, the action will fail with an error similar to the one below: +If the buffer size is lower than what is allowed in the request, the action fails with an error similar to the one below: ```plaintext error: RPC failed; curl 18 transfer closed with outstanding read data remaining @@ -163,7 +162,7 @@ fatal: early EOF fatal: index-pack failed ``` -This can be fixed by increasing the existing `http.postBuffer` value to one greater than the repository size. For example, if `git clone` fails when cloning a 500M repository, the solution will be to set `http.postBuffer` to `524288000` so that the request only starts buffering after the first 524288000 bytes. +This can be fixed by increasing the existing `http.postBuffer` value to one greater than the repository size. For example, if `git clone` fails when cloning a 500M repository, you should set `http.postBuffer` to `524288000`. That setting ensures the request only starts buffering after the first 524288000 bytes. NOTE: The default value of `http.postBuffer`, 1 MiB, is applied if the setting is not configured. diff --git a/doc/topics/git/useful_git_commands.md b/doc/topics/git/useful_git_commands.md index 6b4d1e06c2c..94279e521b6 100644 --- a/doc/topics/git/useful_git_commands.md +++ b/doc/topics/git/useful_git_commands.md @@ -5,10 +5,10 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Useful Git commands +# Useful Git commands **(FREE)** -Here are some useful Git commands collected by the GitLab support team. You may not -need to use often, but they can come in handy when needed. +The GitLab support team has collected these commands to help you. You may not +need to use them often. ## Remotes @@ -182,7 +182,7 @@ Git includes a complete set of [traces for debugging Git commands](https://git-s ### Rebase your branch onto master -The -i flag stands for 'interactive': +The `-i` flag stands for 'interactive': ```shell git rebase -i master diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index 87d8129dc7f..d02573a0e06 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated disqus_identifier: 'https://docs.gitlab.com/ee/workflow/gitlab_flow.html' --- -# Introduction to GitLab Flow +# Introduction to GitLab Flow **(FREE)**  @@ -16,7 +16,7 @@ It combines [feature-driven development](https://en.wikipedia.org/wiki/Feature-d Organizations coming to Git from other version control systems frequently find it hard to develop a productive workflow. This article describes GitLab flow, which integrates the Git workflow with an issue tracking system. -It offers a simple, transparent, and effective way to work with Git. +It offers a transparent and effective way to work with Git.  @@ -28,7 +28,7 @@ After getting used to these three steps, the next challenge is the branching mod  -Since many organizations new to Git have no conventions for how to work with it, their repositories can quickly become messy. +Because many organizations new to Git have no conventions for how to work with it, their repositories can quickly become messy. The biggest problem is that many long-running branches emerge that all contain part of the changes. People have a hard time figuring out which branch has the latest code, or which branch to deploy to production. Frequently, the reaction to this problem is to adopt a standardized pattern such as [Git flow](https://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html). @@ -38,8 +38,12 @@ For a video introduction of how this works in GitLab, see [GitLab Flow](https:// ## Git flow and its problems +<!-- vale gitlab.Spelling = NO --> +  +<!-- vale gitlab.Spelling = YES --> + Git flow was one of the first proposals to use Git branches, and it has received a lot of attention. It suggests a `master` branch and a separate `develop` branch, as well as supporting branches for features, releases, and hotfixes. The development happens on the `develop` branch, moves to a release branch, and is finally merged into the `master` branch. @@ -47,7 +51,7 @@ The development happens on the `develop` branch, moves to a release branch, and Git flow is a well-defined standard, but its complexity introduces two problems. The first problem is that developers must use the `develop` branch and not `master`. `master` is reserved for code that is released to production. It is a convention to call your default branch `master` and to mostly branch from and merge to this. -Since most tools automatically use the `master` branch as the default, it is annoying to have to switch to another branch. +Because most tools automatically use the `master` branch as the default, it is annoying to have to switch to another branch. The second problem of Git flow is the complexity introduced by the hotfix and release branches. These branches can be a good idea for some organizations but are overkill for the vast majority of them. @@ -61,28 +65,32 @@ For example, many projects do releases but don't need to do hotfixes. ## GitHub flow as a simpler alternative - + In reaction to Git flow, GitHub created a simpler alternative. [GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `master` branch. This flow is clean and straightforward, and many organizations have adopted it with great success. Atlassian recommends [a similar strategy](https://www.atlassian.com/blog/git/simple-git-workflow-is-simple), although they rebase feature branches. -Merging everything into the `master` branch and frequently deploying means you minimize the amount of unreleased code, which is in line with lean and continuous delivery best practices. +Merging everything into the `master` branch and frequently deploying means you minimize the amount of unreleased code. This approach is in line with lean and continuous delivery best practices. However, this flow still leaves a lot of questions unanswered regarding deployments, environments, releases, and integrations with issues. With GitLab flow, we offer additional guidance for these questions. ## Production branch with GitLab flow - + GitHub flow assumes you can deploy to production every time you merge a feature branch. -While this is possible in some cases, such as SaaS applications, there are many cases where this is not possible. -One case is where you don't control the timing of a release, for example, an iOS application that is released when it passes App Store validation. -Another case is when you have deployment windows — for example, workdays from 10 AM to 4 PM when the operations team is at full capacity — but you also merge code at other times. +While this is possible in some cases, such as SaaS applications, there are some cases where this is not possible, such as: + +- You don't control the timing of a release. For example, an iOS application that + is released when it passes App Store validation. +- You have deployment windows - for example, workdays from 10 AM to 4 PM when the + operations team is at full capacity - but you also merge code at other times. + In these cases, you can make a production branch that reflects the deployed code. You can deploy a new version by merging `master` into the production branch. -If you need to know what code is in production, you can just checkout the production branch to see. -The approximate time of deployment is easily visible as the merge commit in the version control system. +If you need to know what code is in production, you can check out the production branch to see. +The approximate time of deployment is visible as the merge commit in the version control system. This time is pretty accurate if you automatically deploy your production branch. If you need a more exact time, you can have your deployment script create a tag on each deployment. This flow prevents the overhead of releasing, tagging, and merging that happens with Git flow. @@ -105,10 +113,10 @@ If this is not possible because more manual testing is required, you can send me ## Release branches with GitLab flow - + You only need to work with release branches if you need to release software to the outside world. -In this case, each branch contains a minor version, for example, 2-3-stable, 2-4-stable, etc. +In this case, each branch contains a minor version, such as `2-3-stable` or `2-4-stable`. Create stable branches using `master` as a starting point, and branch as late as possible. By doing this, you minimize the length of time during which you have to apply bug fixes to multiple branches. After announcing a release branch, only add serious bug fixes to the branch. @@ -124,11 +132,11 @@ In this flow, it is not common to have a production branch (or Git flow `master`  Merge or pull requests are created in a Git management application. They ask an assigned person to merge two branches. -Tools such as GitHub and Bitbucket choose the name "pull request" since the first manual action is to pull the feature branch. -Tools such as GitLab and others choose the name "merge request" since the final action is to merge the feature branch. -In this article, we'll refer to them as merge requests. +Tools such as GitHub and Bitbucket choose the name "pull request", because the first manual action is to pull the feature branch. +Tools such as GitLab and others choose the name "merge request", because the final action is to merge the feature branch. +This article refers to them as merge requests. -If you work on a feature branch for more than a few hours, it is good to share the intermediate result with the rest of the team. +If you work on a feature branch for more than a few hours, share the intermediate result with the rest of your team. To do this, create a merge request without assigning it to anyone. Instead, mention people in the description or a comment, for example, "/cc @mark @susan." This indicates that the merge request is not ready to be merged yet, but feedback is welcome. @@ -143,7 +151,7 @@ Also, mention any other people from whom you would like feedback. After the assigned person feels comfortable with the result, they can merge the branch. If the assigned person does not feel comfortable, they can request more changes or close the merge request without merging. -In GitLab, it is common to protect the long-lived branches, e.g., the `master` branch, so that [most developers can't modify them](../user/permissions.md). +In GitLab, it is common to protect the long-lived branches, such as the `master` branch, so [most developers can't modify them](../user/permissions.md). So, if you want to merge into a protected branch, assign your merge request to someone with maintainer permissions. After you merge a feature branch, you should remove it from the source control software. @@ -165,10 +173,10 @@ GitLab flow is a way to make the relation between the code and the issue tracker Any significant change to the code should start with an issue that describes the goal. Having a reason for every code change helps to inform the rest of the team and to keep the scope of a feature branch small. In GitLab, each change to the codebase starts with an issue in the issue tracking system. -If there is no issue yet, create the issue, as long as the change will take a significant amount of work, i.e., more than 1 hour. +If there is no issue yet, create the issue if the change requires more than an hour's work. In many organizations, raising an issue is part of the development process because they are used in sprint planning. The issue title should describe the desired state of the system. -For example, the issue title "As an administrator, I want to remove users without receiving an error" is better than "Admin can't remove users." +For example, the issue title "As an administrator, I want to remove users without receiving an error" is better than "Administrators can't remove users." When you are ready to code, create a branch for the issue from the `master` branch. This branch is the place for any work related to this change. @@ -185,20 +193,20 @@ Start the title of the merge request with `[Draft]`, `Draft:` or `(Draft)` to pr When you think the code is ready, assign the merge request to a reviewer. The reviewer can merge the changes when they think the code is ready for inclusion in the `master` branch. -When they press the merge button, GitLab merges the code and creates a merge commit that makes this event easily visible later on. +When they press the merge button, GitLab merges the code and creates a merge commit that makes this event visible later on. Merge requests always create a merge commit, even when the branch could be merged without one. This merge strategy is called "no fast-forward" in Git. -After the merge, delete the feature branch since it is no longer needed. +After the merge, delete the feature branch, because it is no longer needed. In GitLab, this deletion is an option when merging. Suppose that a branch is merged but a problem occurs and the issue is reopened. -In this case, it is no problem to reuse the same branch name since the first branch was deleted when it was merged. +In this case, it is no problem to reuse the same branch name, because the first branch was deleted when it was merged. At any time, there is at most one branch for every issue. It is possible that one feature branch solves more than one issue. ## Linking and closing issues from merge requests - + Link to issues by mentioning them in commit messages or the description of a merge request, for example, "Fixes #16" or "Duck typing is preferred. See #12." GitLab then creates links to the mentioned issues and creates comments in the issues linking back to the merge request. @@ -212,12 +220,12 @@ If you have an issue that spans across multiple repositories, create an issue fo  With Git, you can use an interactive rebase (`rebase -i`) to squash multiple commits into one or reorder them. -This functionality is useful if you want to replace a couple of small commits with a single commit, or if you want to make the order more logical. +This feature helps you replace a couple of small commits with a single commit, or if you want to make the order more logical. However, you should avoid rebasing commits you have pushed to a remote server if you have other active contributors in the same branch. -Since rebasing creates new commits for all your changes, it can cause confusion because the same change would have multiple identifiers. +Because rebasing creates new commits for all your changes, it can cause confusion because the same change would have multiple identifiers. It would cause merge errors for anyone working on the same branch because their history would not match with yours. It can be really troublesome for the author or other contributors. -Also, if someone has already reviewed your code, rebasing makes it hard to tell what changed since the last review. +Also, if someone has already reviewed your code, rebasing makes it hard to tell what changed after the last review. You should never rebase commits authored by other people unless you've agreed otherwise. Not only does this rewrite history, but it also loses authorship information. @@ -225,7 +233,7 @@ Rebasing prevents the other authors from being attributed and sharing part of th If a merge involves many commits, it may seem more difficult to undo. You might consider solving this by squashing all the changes into one commit just before merging by using the GitLab [Squash-and-Merge](../user/project/merge_requests/squash_and_merge.md) feature. -Fortunately, there is an easy way to undo a merge with all its commits. +Fortunately, you can undo a merge with all its commits. The way to do this is by reverting the merge commit. Preserving this ability to revert a merge is a good reason to always use the "no fast-forward" (`--no-ff`) strategy when you merge manually. @@ -243,8 +251,8 @@ Often, people avoid merge commits by just using rebase to reorder their commits Using rebase prevents a merge commit when merging `master` into your feature branch, and it creates a neat linear history. However, as discussed in [the section about rebasing](#squashing-commits-with-rebase), you should avoid rebasing commits in a feature branch that you're sharing with others. -Rebasing could create more work, since every time you rebase, you may need to resolve the same conflicts. -Sometimes you can reuse recorded resolutions (`rerere`), but merging is better since you only have to resolve conflicts once. +Rebasing could create more work, as every time you rebase, you may need to resolve the same conflicts. +Sometimes you can reuse recorded resolutions (`rerere`), but merging is better, because you only have to resolve conflicts once. Atlassian has a more thorough explanation of the tradeoffs between merging and rebasing [on their blog](https://www.atlassian.com/blog/git/git-team-workflows-merge-or-rebase). A good way to prevent creating many merge commits is to not frequently merge `master` into the feature branch. @@ -270,8 +278,8 @@ You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggl NOTE: Don't confuse automatic branch testing with continuous integration. -Martin Fowler makes this distinction in [his article about feature branches](https://martinfowler.com/bliki/FeatureBranch.html): -"I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. +Martin Fowler makes this distinction in [an article about feature branches](https://martinfowler.com/bliki/FeatureBranch.html): +"\[People\] say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. That's continuous building, and a Good Thing, but there's no *integration*, so it's not CI." In conclusion, you should try to prevent merge commits, but not eliminate them. @@ -285,24 +293,36 @@ If you rebase code, the history is incorrect, and there is no way for tools to r Another way to make your development work easier is to commit often. Every time you have a working set of tests and code, you should make a commit. Splitting up work into individual commits provides context for developers looking at your code later. -Smaller commits make it clear how a feature was developed, and they make it easy to roll back to a specific good point in time or to revert one code change without reverting several unrelated changes. +Smaller commits make it clear how a feature was developed. They help you roll back to a specific good point in time, or to revert one code change without reverting several unrelated changes. -Committing often also makes it easy to share your work, which is important so that everyone is aware of what you are working on. +Committing often also helps you share your work, which is important so that everyone is aware of what you are working on. You should push your feature branch frequently, even when it is not yet ready for review. By sharing your work in a feature branch or [a merge request](#mergepull-requests-with-gitlab-flow), you prevent your team members from duplicating work. -Sharing your work before it's complete also allows for discussion and feedback about the changes, which can help improve the code before it gets to review. +Sharing your work before it's complete also allows for discussion and feedback about the changes. This feedback can help improve the code before it gets to review. ## How to write a good commit message  A commit message should reflect your intention, not just the contents of the commit. -It is easy to see the changes in a commit, so the commit message should explain why you made those changes. +You can see the changes in a commit, so the commit message should explain why you made those changes. An example of a good commit message is: "Combine templates to reduce duplicate code in the user views." The words "change," "improve," "fix," and "refactor" don't add much information to a commit message. For example, "Improve XML generation" could be better written as "Properly escape special characters in XML generation." For more information about formatting commit messages, please see this excellent [blog post by Tim Pope](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). +To add more context to a commit message, consider adding information regarding the +origin of the change. For example, the URL of a GitLab issue, or a Jira issue number, +containing more information for users who need in-depth context about the change. + +For example: + +```plaintext +Properly escape special characters in XML generation. + +Issue: gitlab.com/gitlab-org/gitlab/-/issues/1 +``` + ## Testing before merging  @@ -311,12 +331,12 @@ In old workflows, the continuous integration (CI) server commonly ran tests on t Developers had to ensure their code did not break the `master` branch. When using GitLab flow, developers create their branches from this `master` branch, so it is essential that it never breaks. Therefore, each merge request must be tested before it is accepted. -CI software like Travis CI and GitLab CI/CD show the build results right in the merge request itself to make this easy. +CI software like Travis CI and GitLab CI/CD show the build results right in the merge request itself to simplify the process. There is one drawback to testing merge requests: the CI server only tests the feature branch itself, not the merged result. Ideally, the server could also test the `master` branch after each change. However, retesting on every commit to `master` is computationally expensive and means you are more frequently waiting for test results. -Since feature branches should be short-lived, testing just the branch is an acceptable risk. +Because feature branches should be short-lived, testing just the branch is an acceptable risk. If new commits in `master` cause merge conflicts with the feature branch, merge `master` back into the branch to make the CI server re-run the tests. As said before, if you often have feature branches that last for more than a few days, you should make your issues smaller. diff --git a/doc/topics/index.md b/doc/topics/index.md index 276cb07c250..565b436c0b0 100644 --- a/doc/topics/index.md +++ b/doc/topics/index.md @@ -19,6 +19,6 @@ tutorials, technical overviews, blog posts) and videos. - [Cron](cron/index.md) - [Git](git/index.md) - [GitLab Flow](gitlab_flow.md) -- [GitLab Installation](../install/README.md) +- [GitLab Installation](../install/index.md) - [GitLab Pages](../user/project/pages/index.md) - [Offline GitLab](offline/index.md) |
