File management

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

The GitLab UI extends the history and tracking capabilities of Git with user-friendly features in your browser. You can:

• Search for files.
• Change file handling.
• Explore the history of an entire file, or a single line.

Understand how file types render in the UI

When you add files of these types to your project, GitLab renders their output to improve readability:

• GeoJSON files display as maps.
• Jupyter Notebook files display as rendered HTML.
• Files in many markup languages are rendered for display.

Supported markup languages

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

README and index files

When a README 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.

• When both a README and an index file are present, the README takes precedence.

• When multiple files with the same name have different extensions, the files are ordered alphabetically. GitLab orders files without an extension last, like this:

  1. README.adoc
  2. README.md
  3. README.rst
  4. README.

Render OpenAPI files

GitLab 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.json
• swagger.yml, swagger.yaml, swagger.json
• OpenAPI.YML, openapi.Yaml, openapi.JSON
• openapi_gitlab.yml, openapi.gitlab.yml
• gitlab_swagger.yml
• gitlab.openapi.yml

To render an OpenAPI file:

1. Search for the OpenAPI file in your repository.
2. Select Display rendered file.
3. To display the operationId in the operations list, add displayOperationId=true to the query string.

NOTE: When displayOperationId is present in the query string and has any value, it evaluates to true. This behavior matches the default behavior of Swagger.

View Git records for a file

Historical information about files in your repository is available in the GitLab UI:

• Git file history: shows the commit history of an entire file.
• Git blame: shows each line of a text-based file, and the most recent commit that changed the line.

Search for a file

• Changed to a dialog in GitLab 16.11.

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 t anywhere in your project, or:

1. On the left sidebar, select Search or go to and find your project.

2. Select Code > Repository.

3. In the upper right, select Find file.

4. On the dialog, start entering the filename:

   

5. Optional. To narrow the search options, press Command + K or select Commands on the lower right corner of the dialog:

   • For Pages or actions, enter >.
   • For Users, enter @.
   • For Projects, enter :.
   • For Files, enter ~.

6. From the dropdown list, select the file to view it in your repository.

To go back to the Files page, press Esc.

This feature uses the fuzzaldrin-plus library.

Change how Git handles a file

To change the default handling of a file or file type, create a .gitattributes file. Use .gitattributes files to:

• Configure file display in diffs, such as syntax highlighting or collapsing generated files.
• Control file storage and protection, such as making files read-only, or storing large files with Git LFS.

Related topics

• Repository files API

Troubleshooting

Repository Languages: excessive CPU use

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:

• Files with the .txt extension.
• XML files with an extension not defined by the gem.

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:

1. Identify the language to specify. The gem contains a configuration file for known data types.

2. To add an entry for text files, for example:

   Text:
     type: prose
     wrap: true
     aliases:
     - fundamental
     - plain text
     extensions:
     - ".txt"

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