doc/user/project/repository/files/_index.md
{{< details >}}
{{< /details >}}
The GitLab UI extends the history and tracking capabilities of Git with user-friendly features in your browser. You can:
When you add files of these types to your project, GitLab renders their output to improve readability:
If your file has one of the these file extensions, GitLab renders the contents of the file's markup language in the UI.
| Markup language | Extensions |
|---|---|
| Plain text | txt |
| Markdown | mdown, mkd, mkdn, md, markdown |
| reStructuredText | rst |
| AsciiDoc | adoc, ad, asciidoc |
| Textile | textile |
| Rdoc | rdoc |
| Org mode | org |
| creole | creole |
| MediaWiki | wiki, mediawiki |
{{< history >}}
_index.md files was introduced in GitLab 18.5.{{< /history >}}
When a README, index, or _index file is present in a repository, GitLab renders its contents.
These files can either be plain text or have the extension of a
supported markup language.
The priority order for automatic rendering is:
README.md, index.md, _index.md, etc.README, index, _index, etc.The first file found in each category (in alphabetical order) is selected, with previewable files taking precedence over plain text files. For example, if multiple READMEs are available GitLab renders them in the following order:
README.adocREADME.mdREADME.rstREADMEGitLab renders OpenAPI specification files if the filename includes openapi or swagger,
and the extension is yaml, yml, or json. These examples are all correct:
openapi.yml, openapi.yaml, openapi.jsonswagger.yml, swagger.yaml, swagger.jsonOpenAPI.YML, openapi.Yaml, openapi.JSONopenapi_gitlab.yml, openapi.gitlab.ymlgitlab_swagger.ymlgitlab.openapi.ymlTo render an OpenAPI file:
operationId in the operations list, add displayOperationId=true to the query string.[!note] When
displayOperationIdis present in the query string and has any value, it evaluates totrue. This behavior matches the default behavior of Swagger.
Historical information about files in your repository is available in the GitLab UI:
Permalinks are permanent URLs that point to specific files, directories, or sections of code in your repository. They remain valid even when the repository changes, making them ideal for sharing and referencing code in documentation, issues, or merge requests.
To create a permalink:
{{< history >}}
filter_blob_path.filter_blob_path removed.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.
When viewing a repository file, GitLab shows a badge with the number of open merge requests that target the current branch and modify the file. This helps you identify files that have pending changes.
To view the open merge requests for a file:
{{< history >}}
{{< /history >}}
Use the file finder to search directly from the GitLab UI for a file in your repository. The file finder uses fuzzy search and highlights results as you type.
To search for a file, press <kbd>t</kbd> anywhere in your project, or:
In the top bar, select Search or go to and find your project.
In the left sidebar, select Code > Repository.
In the upper right, select Find file.
On the dialog, start entering the filename:
Optional. To narrow the search options, press <kbd>Command</kbd>+<kbd>K</kbd> or select Commands on the lower right corner of the dialog:
From the dropdown list, select the file to view it in your repository.
To go back to the Files page, press <kbd>Esc</kbd>.
This feature uses the fuzzaldrin-plus library.
To change the default handling of a file or file type, create a
.gitattributes file. Use .gitattributes files to:
To determine which languages are in a repository's files, GitLab uses a Ruby gem. When the gem parses a file to determine its file type, the process can use excessive CPU. The gem contains a heuristics configuration file that defines which file extensions to parse. These file types can take excessive CPU:
.txt extension.To fix this problem, edit your .gitattributes file and assign a language to
specific file extensions. You can also use this approach to fix misidentified file types:
Identify the language to specify. The gem contains a configuration file for known data types.
To add an entry for text files, for example:
Text:
type: prose
wrap: true
aliases:
- fundamental
- plain text
extensions:
- ".txt"
Add or edit .gitattributes in the root of your repository:
*.txt linguist-language=Text
*.txt files have an entry in the heuristics file. This example prevents parsing of these files.