Merge branch 'docs-bprescott/20210329-linguist' into 'master'

Work around heavy CPU use by linguist

See merge request gitlab-org/gitlab!57701

doc/user/project/repository/index.md

@@ -226,6 +226,10 @@ detected, add the following to `.gitattributes` in the root of your repository.
 *.proto linguist-detectable=true
 ```
 
+Sometimes this feature can use excessive CPU.
+[Read about troubleshooting this](#repository-languages-excessive-cpu-use)
+and also more about customizing this feature using `.gitattributes`.
+
 ## Locked files **(PREMIUM)**
 
 Use [File Locking](../file_lock.md) to
@@ -310,14 +314,40 @@ When [renaming a user](../../profile/index.md#change-your-username),
 - The redirects are available as long as the original path is not claimed by
   another group, user or project.
 
-<!-- ## Troubleshooting
+## Troubleshooting
+
+### Repository Languages: excessive CPU use
+
+GitLab uses a Ruby gem to scan all the files in the repository to determine what languages are used.
+[Sometimes this can use excessive CPU](https://gitlab.com/gitlab-org/gitaly/-/issues/1565) if
+a file type needs to be parsed by the gem to determine what sort of file it is.
+The gem contains a [heuristics configuration file](https://github.com/github/linguist/blob/master/lib/linguist/heuristics.yml)
+that defines what file extensions need to be parsed.
+
+Excessive CPU use has been reported for files with the extension `.txt` and XML files with
+a file extension that is not defined by the gem.
+
+The workaround is to specify what language to assign to specific file extensions.
+The same approach should also allow misidentified file types to be fixed.
+
+1. Identify which language to specify. The gem contains a [configuration file for known data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
+  The entry for `Text` files, for example:
+
+   ```yaml
+   Text:
+     type: prose
+     wrap: true
+     aliases:
+     - fundamental
+     - plain text
+     extensions:
+     - ".txt"
+   ```
+
+1. Add or modify `.gitattributes` in the root of your repository:
 
-Include any troubleshooting steps that you can foresee. If you know beforehand what issues
-one might have when setting this up, or when something is changed, or on upgrading, it's
-important to describe those, too. Think of things that may go wrong and include them here.
-This is important to minimize requests for support, and to avoid doc comments with
-questions that you know someone might ask.
+   ```plaintext
+   *.txt linguist-language=Text
+   ```
 
-Each scenario can be a third-level heading, e.g. `### Getting error message X`.
-If you have none to add when creating a doc, leave this section in place
-but commented out to help encourage others to add to it in the future. -->
+  `*.txt` files have an entry in the heuristics file. The example above prevents parsing of these files.