Merge branch 'docs-aqualls-create-6' into 'master'

More word and line revisions in Create docset

See merge request gitlab-org/gitlab!52754

doc/administration/file_hooks.md

@@ -19,19 +19,20 @@ directly to the GitLab source code and contribute back upstream. This way we can
 ensure functionality is preserved across versions and covered by tests.
 
 NOTE:
-File hooks must be configured on the filesystem of the GitLab server. Only GitLab
-server administrators will be able to complete these tasks. Explore
-[system hooks](../system_hooks/system_hooks.md) or [webhooks](../user/project/integrations/webhooks.md) as an option if you do not have filesystem access.
-
-A file hook will run on each event so it's up to you to filter events or projects
-within a file hook code. You can have as many file hooks as you want. Each file hook will
-be triggered by GitLab asynchronously in case of an event. For a list of events
+File hooks must be configured on the file system of the GitLab server. Only GitLab
+server administrators can complete these tasks. Explore
+[system hooks](../system_hooks/system_hooks.md) or [webhooks](../user/project/integrations/webhooks.md)
+as an option if you do not have file system access.
+
+A file hook runs on each event. You can filter events or projects
+in a file hook's code, and create many file hooks as you need. Each file hook is
+triggered by GitLab asynchronously in case of an event. For a list of events
 see the [system hooks](../system_hooks/system_hooks.md) documentation.
 
 ## Setup
 
 The file hooks must be placed directly into the `file_hooks` directory, subdirectories
-will be ignored. There is an
+are ignored. There is an
 [`example` directory inside `file_hooks`](https://gitlab.com/gitlab-org/gitlab/tree/master/file_hooks/examples)
 where you can find some basic examples.
 
@@ -52,23 +53,23 @@ Follow the steps below to set up a custom hook:
    in any language, and ensure the 'shebang' at the top properly reflects the
    language type. For example, if the script is in Ruby the shebang will
    probably be `#!/usr/bin/env ruby`.
-1. The data to the file hook will be provided as JSON on STDIN. It will be exactly
+1. The data to the file hook is provided as JSON on STDIN. It is exactly the
    same as for [system hooks](../system_hooks/system_hooks.md).
 
-That's it! Assuming the file hook code is properly implemented, the hook will fire
+That's it! Assuming the file hook code is properly implemented, the hook fires
 as appropriate. The file hooks file list is updated for each event, there is no
 need to restart GitLab to apply a new file hook.
 
 If a file hook executes with non-zero exit code or GitLab fails to execute it, a
-message will be logged to:
+message is logged to:
 
 - `gitlab-rails/plugin.log` in an Omnibus installation.
 - `log/plugin.log` in a source installation.
 
 ## Creating file hooks
 
-Below is an example that will only response on the event `project_create` and
-will inform the admins from the GitLab instance that a new project has been created.
+This example responds only on the event `project_create`, and
+the GitLab instance informs the administrators that a new project has been created.
 
 ```ruby
 #!/opt/gitlab/embedded/bin/ruby
@@ -97,7 +98,7 @@ end
 Writing your own file hook can be tricky and it's easier if you can check it
 without altering the system. A Rake task is provided so that you can use it
 in a staging environment to test your file hook before using it in production.
-The Rake task will use a sample data and execute each of file hook. The output
+The Rake task uses a sample data and execute each of file hook. The output
 should be enough to determine if the system sees your file hook and if it was
 executed without errors.
 

doc/administration/git_annex.md

@@ -38,7 +38,7 @@ very fast file copying tool.
 
 ## GitLab git-annex Configuration
 
-`git-annex` is disabled by default in GitLab. Below you will find the
+`git-annex` is disabled by default in GitLab. Below are the
 configuration options required to enable it.
 
 ### Requirements
@@ -60,7 +60,7 @@ sudo yum install epel-release && sudo yum install git-annex
 ### Configuration for Omnibus packages
 
 For Omnibus GitLab packages, only one configuration setting is needed.
-The Omnibus package will internally set the correct options in all locations.
+The Omnibus package internally sets the correct options in all locations.
 
 1. In `/etc/gitlab/gitlab.rb` add the following line:
 
@@ -148,15 +148,15 @@ To example.com:group/project.git
 ok
 ```
 
-Your files can be found in the `master` branch, but you'll notice that there
-are more branches created by the `annex sync` command.
+Your files can be found in the `master` branch, but more branches are created
+by the `annex sync` command.
 
-Git Annex will also create a new directory at `.git/annex/` and will record the
+Git Annex creates a new directory at `.git/annex/` and records the
 tracked files in the `.git/config` file. The files you assign to be tracked
-with `git-annex` will not affect the existing `.git/config` records. The files
+with `git-annex` don't affect the existing `.git/config` records. The files
 are turned into symbolic links that point to data in `.git/annex/objects/`.
 
-The `debian.iso` file in the example will contain the symbolic link:
+The `debian.iso` file in the example contain the symbolic link:
 
 ```plaintext
 .git/annex/objects/ZW/1k/SHA256E-s82701--6384039733b5035b559efd5a2e25a493ab6e09aabfd5162cc03f6f0ec238429d.png/SHA256E-s82701--6384039733b5035b559efd5a2e25a493ab6e09aabfd5162cc03f6f0ec238429d.iso
@@ -167,7 +167,7 @@ repository.
 
 ---
 
-Downloading a single large file is also very simple:
+You can download a single large file with these commands:
 
 ```shell
 git clone git@gitlab.example.com:group/project.git
@@ -185,7 +185,7 @@ git annex sync --content  # sync Git branches and download all the large files
 ```
 
 By using `git-annex` without GitLab, anyone that can access the server can also
-access the files of all projects, but GitLab Annex ensures that you can only
+access the files of all projects. GitLab Annex ensures that you can only
 access files of projects you have access to (developer, maintainer, or owner role).
 
 ## How it works

doc/integration/README.md

@@ -65,7 +65,9 @@ Integration with services such as Campfire, Flowdock, HipChat, Pivotal Tracker,
 
 ### SSL certificate errors
 
-When trying to integrate GitLab with services that are using self-signed certificates, it is very likely that SSL certificate errors occur in different parts of the application, most likely Sidekiq.
+When trying to integrate GitLab with services using self-signed certificates,
+SSL certificate errors can occur in different parts of the application. Sidekiq
+is a common culprit.
 
 There are two approaches you can take to solve this:
 

doc/integration/gmail_action_buttons_for_gitlab.md

@@ -15,20 +15,24 @@ If correctly set up, emails that require an action are marked in Gmail.
 To get this functioning, you need to be registered with Google. For instructions, see
 [Register with Google](https://developers.google.com/gmail/markup/registering-with-google).
 
-*This process has a lot of steps so make sure that you fulfill all requirements set by Google to avoid your application being rejected by Google.*
+This process has many steps. Make sure that you fulfill all requirements set by Google to avoid your application being rejected by Google.
 
 In particular, note:
 
+<!-- vale gitlab.InclusionCultural = NO -->
+
 - The email account used by GitLab to send notification emails must:
   - Have a "Consistent history of sending a high volume of mail from your domain
     (order of hundred emails a day minimum to Gmail) for a few weeks at least".
   - Have a very low rate of spam complaints from users.
 - Emails must be authenticated via DKIM or SPF.
-- Before sending the final form ("Gmail Schema Whitelist Request"), you must
+- Before sending the final form (**Gmail Schema Whitelist Request**), you must
   send a real email from your production server. This means that you must find
   a way to send this email from the email address you are registering. You can
   do this by forwarding the real email from the email address you are
   registering. You can also go into the Rails console on the GitLab server and
   trigger sending the email from there.
 
+<!-- vale gitlab.InclusionCultural = YES -->
+
 You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/1517).

doc/integration/jenkins_deprecated.md

@@ -50,7 +50,7 @@ Now navigate to GitLab services page and activate Jenkins
 
 ![screen](img/jenkins_gitlab_service.png)
 
-Done! Now when you push to GitLab - it creates a build for Jenkins, and you can view the merge request build status with a link to the Jenkins build.
+Done! When you push to GitLab, it creates a build for Jenkins. You can view the merge request build status with a link to the Jenkins build.
 
 ### Multi-project Configuration
 

doc/integration/jira_development_panel.md

@@ -62,8 +62,8 @@ self-managed GitLab) set up the integration to simplify administration.
 
 ### Jira DVCS configuration
 
-If you're using GitLab.com and Jira Cloud, we recommend you use the
-[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector.
+If you're using GitLab.com and Jira Cloud, use the
+[GitLab for Jira app](#gitlab-for-jira-app) unless you have a specific need for the DVCS Connector.
 
 When configuring Jira DVCS Connector:
 
@@ -79,13 +79,11 @@ create and use a single-purpose `jira` user in GitLab.
 
 1. In GitLab, create a new application to allow Jira to connect with your GitLab account.
 
-   While signed in to the GitLab account that you want Jira to use to connect to GitLab,
-   click your profile avatar at the top right, and then click **Settings > Applications**.
-   Use the form to create a new application.
-
-   In the **Name** field, enter a descriptive name for the integration, such as `Jira`.
-
-   For the **Redirect URI** field, enter `https://<gitlab.example.com>/login/oauth/callback`,
+1. Sign in to the GitLab account that you want Jira to use to connect to GitLab.
+1. In the top right corner, click your profile avatar.
+1. Click **Settings > Applications** to display the form to create a new application.
+1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`.
+1. In the **Redirect URI** field, enter `https://<gitlab.example.com>/login/oauth/callback`,
    replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com,
    this would be `https://gitlab.com/login/oauth/callback`.
 
@@ -97,15 +95,15 @@ create and use a single-purpose `jira` user in GitLab.
 
    ![GitLab application setup](img/jira_dev_panel_gl_setup_1.png)
 
-   - Check **API** in the Scopes section and uncheck any other checkboxes.
+1. Check **API** in the Scopes section, and uncheck any other checkboxes.
 
 1. Click **Save application**. GitLab displays the generated **Application ID**
    and **Secret** values. Copy these values, which you use in Jira.
 
 #### Jira DVCS Connector setup
 
-If you're using GitLab.com and Jira Cloud, we recommend you use the
-[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector.
+If you're using GitLab.com and Jira Cloud, use the
+[GitLab for Jira app](#gitlab-for-jira-app) unless you have a specific need for the DVCS Connector.
 
 1. Ensure you have completed the [GitLab configuration](#gitlab-account-configuration-for-dvcs).
 1. If you're using Jira Server, go to **Settings (gear) > Applications > DVCS accounts**.
@@ -114,25 +112,27 @@ If you're using GitLab.com and Jira Cloud, we recommend you use the
    (We're pretending to be GitHub in this integration, until there's additional platform support in Jira.)
 1. Complete the form:
 
-   Select **GitHub Enterprise** for the **Host** field.
+1. Select **GitHub Enterprise** for the **Host** field.
+
+1. In the **Team or User Account** field, enter either:
 
-   In the **Team or User Account** field, enter the relative path of a top-level GitLab group that you have access to,
-   or the relative path of your personal namespace.
+   - The relative path of a top-level GitLab group that you have access to.
+   - The relative path of your personal namespace.
 
    ![Creation of Jira DVCS integration](img/jira_dev_panel_jira_setup_2.png)
 
-   In the **Host URL** field, enter `https://<gitlab.example.com>/`,
+1. In the **Host URL** field, enter `https://<gitlab.example.com>/`,
    replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com,
    this would be `https://gitlab.com/`.
 
    NOTE:
    If using a GitLab version earlier than 11.3 the **Host URL** value should be `https://<gitlab.example.com>/-/jira`
 
-   For the **Client ID** field, use the **Application ID** value from the previous section.
+1. For the **Client ID** field, use the **Application ID** value from the previous section.
 
-   For the **Client Secret** field, use the **Secret** value from the previous section.
+1. For the **Client Secret** field, use the **Secret** value from the previous section.
 
-   Ensure that the rest of the checkboxes are checked.
+1. Ensure that the rest of the checkboxes are checked.
 
 1. Click **Add** to complete and create the integration.
 
@@ -252,7 +252,7 @@ resynchronize the information. To do so:
 
 You can integrate GitLab.com and Jira Cloud using the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace.
 
-This method is recommended when using GitLab.com and Jira Cloud because data is synchronized in real-time, while the DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](#jira-dvcs-configuration) method.
+This method is recommended when using GitLab.com and Jira Cloud because data is synchronized in real-time. The DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](#jira-dvcs-configuration) method.
 
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 For a walkthrough of the integration with GitLab for Jira, watch [Configure GitLab Jira Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube.
@@ -285,7 +285,7 @@ For more information, see [Usage](#usage).
 
 #### Troubleshooting GitLab for Jira
 
-The GitLab for Jira App uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies which can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in.
+The GitLab for Jira App uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies. This can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in.
 
 > "You need to sign in or sign up before continuing."
 

doc/integration/omniauth.md

@@ -66,7 +66,7 @@ earlier version, you must explicitly enable it.
 NOTE:
 If you set `block_auto_created_users` to `false`, make sure to only
 define providers under `allow_single_sign_on` that you are able to control, like
-SAML, Shibboleth, Crowd, or Google, or set it to `false` otherwise any user on
+SAML, Shibboleth, Crowd, or Google. Otherwise, set it to `false`, or any user on
 the Internet can successfully sign in to your GitLab without
 administrative approval.
 
@@ -168,8 +168,6 @@ omniauth:
 
 ## Configure OmniAuth Providers as External
 
-> Introduced in GitLab 8.7.
-
 You can define which OmniAuth providers you want to be `external`. Users
 creating accounts, or logging in by using these `external` providers cannot have
 access to internal projects. You must use the full name of the provider,
@@ -215,7 +213,7 @@ from the OmniAuth provider's documentation.
   sudo service gitlab stop
   ```
 
-- Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab/blob/master/Gemfile):
+- Add the gem to your [`Gemfile`](https://gitlab.com/gitlab-org/gitlab/blob/master/Gemfile):
 
   ```shell
   gem "omniauth-your-auth-provider"
@@ -240,25 +238,28 @@ from the OmniAuth provider's documentation.
 If you have successfully set up a provider that is not shipped with GitLab itself,
 please let us know.
 
+Share your experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations).
 You can help others by reporting successful configurations and probably share a
-few insights or provide warnings for common errors or pitfalls by sharing your
-experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations).
+few insights or provide warnings for common errors or pitfalls.
 
 While we can't officially support every possible authentication mechanism out there,
 we'd like to at least help those with specific needs.
 
 ## Enable or disable Sign In with an OmniAuth provider without disabling import sources
 
-> Introduced in GitLab 8.8.
-
-Administrators are able to enable or disable Sign In by using some OmniAuth providers.
+Administrators are able to enable or disable **Sign In** by using some OmniAuth providers.
 
 NOTE:
-By default Sign In is enabled by using all the OAuth Providers that have been configured in `config/gitlab.yml`.
+By default, **Sign In** is enabled by using all the OAuth Providers that have been configured in `config/gitlab.yml`.
+
+To enable/disable an OmniAuth provider:
 
-In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings -> Sign-in Restrictions section -> Enabled OAuth Sign-In sources and select the providers you want to enable or disable.
+1. In the top navigation bar, go to **Admin Area**.
+1. In the left sidebar, go to **Settings**.
+1. Scroll to the **Sign-in Restrictions** section, and click **Expand**.
+1. Next to **Enabled OAuth Sign-In sources**, select the check box for each provider you want to enable or disable.
 
-![Enabled OAuth Sign-In sources](img/enabled-oauth-sign-in-sources.png)
+   ![Enabled OAuth Sign-In sources](img/enabled-oauth-sign-in-sources.png)
 
 ## Disabling OmniAuth
 
@@ -325,7 +326,7 @@ omniauth:
 
 You can add the `auto_sign_in_with_provider` setting to your GitLab
 configuration to redirect login requests to your OmniAuth provider for
-authentication, removing the need to click a button before actually signing in.
+authentication. This removes the need to click a button before actually signing in.
 
 For example, when using the Azure integration, set the following to enable auto
 sign-in:

doc/integration/openid_connect_provider.md

@@ -17,8 +17,7 @@ OAuth 2.0 protocol. It allows clients to:
 - Verify the identity of the end-user based on the authentication performed by GitLab.
 - Obtain basic profile information about the end-user in an interoperable and REST-like manner.
 
-OIDC performs many of the same tasks as OpenID 2.0,
-but does so in a way that is API-friendly and usable by native and
+OIDC performs many of the same tasks as OpenID 2.0, but is API-friendly and usable by native and
 mobile applications.
 
 On the client side, you can use [OmniAuth::OpenIDConnect](https://github.com/jjbohn/omniauth-openid-connect/) for Rails

doc/push_rules/push_rules.md

@@ -10,16 +10,16 @@ type: reference, howto
 Gain additional control over what can and can't be pushed to your repository by using
 regular expressions to reject pushes based on commit contents, branch names or file details.
 
-## Overview
-
 GitLab already offers [protected branches](../user/project/protected_branches.md), but there are
-cases when you need some specific rules like preventing Git tag removal or
+cases when you need some specific rules. Some common scenarios: preventing Git tag removal, or
 enforcing a special format for commit messages.
 
-Push rules are essentially [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) that are easy to
-enable in a user-friendly interface. They are defined globally if you are an
-admin or per project so you can have different rules applied to different
-projects depending on your needs.
+Push rules are [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) you
+can enable in a user-friendly interface. They are defined either:
+
+- Globally if you are an administrator.
+- Per project, so you can have different rules applied to different
+  projects depending on your needs.
 
 ## Use cases
 
@@ -32,24 +32,24 @@ Let's assume you have the following requirements for your workflow:
 - every commit should reference a Jira issue, for example: `Refactored css. Fixes JIRA-123.`
 - users should not be able to remove Git tags with `git push`
 
-All you need to do is write a simple regular expression that requires the mention
+Write a regular expression that requires the mention
 of a Jira issue in the commit message, like `JIRA\-\d+`.
 
-Now when a user tries to push a commit with a message `Bugfix`, their push will
-be declined. Only pushing commits with messages like `Bugfix according to JIRA-123`
-will be accepted.
+Now when a user tries to push a commit with a message `Bugfix`, their push is
+declined. Only pushing commits with messages like `Bugfix according to JIRA-123`
+is accepted.
 
 ### Restrict branch names
 
-Let's assume there's a strict policy for branch names in your company, and
-you want the branches to start with a certain name because you have different
-GitLab CI/CD jobs (`feature`, `hotfix`, `docker`, `android`, etc.) that rely on the
+If your company has a strict policy for branch names, you may want the branches to start
+with a certain name. This approach enables different
+GitLab CI/CD jobs (such as `feature`, `hotfix`, `docker`, `android`) that rely on the
 branch name.
 
-Your developers, however, don't always remember that policy, so they might push to
+Your developers may not remember that policy, so they might push to
 various branches, and CI pipelines might not work as expected. By restricting the
 branch names globally in Push Rules, such mistakes are prevented.
-Any branch name that doesn't match your push rule will get rejected.
+Any branch name that doesn't match your push rule is rejected.
 
 Note that the name of your default branch is always allowed, regardless of the branch naming
 regular expression (regex) specified. GitLab is configured this way
@@ -64,7 +64,7 @@ which already limits users from pushing directly.
 > Introduced in GitLab 12.10.
 
 By default, GitLab restricts certain formats of branch names for security purposes.
-Currently 40-character hexadecimal names, similar to Git commit hashes, are prohibited.
+40-character hexadecimal names, similar to Git commit hashes, are prohibited.
 
 ### Custom Push Rules **(FREE SELF)**
 
@@ -77,7 +77,7 @@ See [server hooks](../administration/server_hooks.md) for more information.
 
 NOTE:
 GitLab administrators can set push rules globally under
-**Admin Area > Push Rules** that all new projects will inherit. You can later
+**Admin Area > Push Rules** that all new projects inherit. You can later
 override them in a project's settings. They can be also set on a [group level](../user/group/index.md#group-push-rules).
 
 1. Navigate to your project's **Settings > Repository** and expand **Push Rules**
@@ -88,11 +88,11 @@ The following options are available:
 
 | Push rule                       | Description |
 |---------------------------------|-------------|
-| Removal of tags with `git push` | Forbid users to remove Git tags with `git push`. Tags will still be able to be deleted through the web UI. |
+| Removal of tags with `git push` | Forbid users to remove Git tags with `git push`. Tags can be deleted through the web UI. |
 | Check whether author is a GitLab user | Restrict commits by author (email) to existing GitLab users. |
-| Committer restriction **(PREMIUM)** | GitLab will reject any commit that was not committed by the current authenticated user. |
+| Committer restriction **(PREMIUM)** | GitLab rejects any commit that was not committed by the current authenticated user. |
 | Check whether commit is signed through GPG **(PREMIUM)** | Reject commit when it is not signed through GPG. Read [signing commits with GPG](../user/project/repository/gpg_signed_commits/index.md). |
-| Prevent committing secrets to Git | GitLab will reject any files that are likely to contain secrets. Read [what files are forbidden](#prevent-pushing-secrets-to-the-repository). |
+| Prevent committing secrets to Git | GitLab rejects any files that are likely to contain secrets. Read [what files are forbidden](#prevent-pushing-secrets-to-the-repository). |
 | Restrict by commit message | Only commit messages that match this regular expression are allowed to be pushed. Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. |
 | Restrict by commit message (negative match) | Only commit messages that do not match this regular expression are allowed to be pushed. Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. |
 | Restrict by branch name | Only branch names that match this regular expression are allowed to be pushed. Leave empty to allow any branch name. |
@@ -108,8 +108,8 @@ GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.12.
 
 Secrets such as credential files, SSH private keys, and other files containing secrets should never be committed to source control.
-GitLab allows you to turn on a predefined denylist of files which won't be allowed to be
-pushed to a repository, stopping those commits from reaching the remote repository.
+GitLab enables you to turn on a predefined denylist of files which can't be
+pushed to a repository. The list stops those commits from reaching the remote repository.
 
 By selecting the checkbox *Prevent committing secrets to Git*, GitLab prevents
 pushes to the repository when a file matches a regular expression as read from
@@ -117,9 +117,9 @@ pushes to the repository when a file matches a regular expression as read from
 as your GitLab version when viewing this file).
 
 NOTE:
-Files already committed won't get restricted by this push rule.
+Files already committed aren't restricted by this push rule.
 
-Below is an example list of what will be rejected by these regular expressions:
+Below is an example list of what GitLab rejects with these regular expressions:
 
 ```shell
 #####################
@@ -204,13 +204,17 @@ Example: prevent a specific configuration file in a known directory from being p
 ^directory-name\/config\.yml$
 ```
 
-Example: prevent the specific file named `install.exe` from being pushed to any location in the repository. Note that the parenthesized expression `(^|\/)` will match either a file following a directory separator or a file in the root directory of the repository:
+Example: prevent the specific file named `install.exe` from being pushed to any
+location in the repository. The parenthesized expression `(^|\/)` matches either
+a file following a directory separator or a file in the root directory of the repository:
 
 ```plaintext
 (^|\/)install\.exe$
 ```
 
-Example: combining all of the above in a single expression. Note that all of the preceding expressions rely on the end of string character `$`, so we can move that part of each expression to the end of the grouped collection of match conditions where it will be appended to all matches:
+Example: combining all of the above in a single expression. The preceding expressions rely
+on the end-of-string character `$`. We can move that part of each expression to the
+end of the grouped collection of match conditions where it is appended to all matches:
 
 ```plaintext
 (\.exe|^config\.yml|^directory-name\/config\.yml|(^|\/)install\.exe)$

doc/topics/git/troubleshooting_git.md

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