[go: up one dir, main page]
Skip to content

Navigate repo with a file tree

Context

A file tree view has been requested quite a number of times ("Especially the file tree view is simply a must-have for navigation" via Reddit) and was even implemented by the community as a browser extension Octotree.

Unfortunately this extension no longer works for GitLab due to design changes, nor did it support private GitLab projects.

Community expectations were also set that Octotree functionality would be integrated into GitLab in https://gitlab.com/gitlab-org/gitlab-ce/issues/13723

A version of this has been partially implemented within https://gitlab.com/gitlab-org/gitlab-ce/issues/31890 (pre-alpha accessible by creating a cookie new_repo with the value true).

Design proposal

Implement a file tree view in the file list to make browsing and reading files in the web interface easier. It should:

  1. allow the sub-directories to be expanded and collapsed as a file tree
  2. show the file tree while viewing a file

The grey background is to just illustrate a placeholder that we would use the same tree component that exists in the MR view.

🎨 Figma

Directory

Collapsed Expanded
1. directory_ collapsed.jpg 1. directory_ expanded.jpg

File

Collapsed Expanded
2. file_ collapsed.jpg 2. file_ expanded.jpg

Will handle the scenario of displaying the tree while editing in a separate issue. The reason for this is that the layout of the edit view is very different than the viewing and we may need to address this at the same time.

Interactions

  • Selected state
    • Use the selected state currently present on the Merge Request > Changes file tree.
  • Filter file bar
    • This bar allows users to filter the tree by extension, or file name. This filter bar currently exists in the Merge Request > Changes file tree, and should follow the same behavior.
    • Note that when users filter, the formatting of the tree changes to list view instead of tree view. This is odd and should be updated in a later iteration if possible (see Out-of-Scope below).
  • Navigation
    • The file tree will dynamically mirror the state of the file list. If a directory is open in the file list, it will also be open in the file tree. See #525169 (comment 2445592460)
    • For example if a user clicks into a directory in the file list:
      • The file list will open that directory (current)
      • The file tree will have that directory selected, and open
  • Keyboard shortcuts
    • Keyboard shortcuts will exist for:
      • Open/close file tree
      • Focus on the filter bar
    • Needs alignment with Code Review. See below.

MR page file filter updates

  • Slight updates will be made to the Merge Request > Changes file filter to improve the file filter field in #535503.

Design decisions pending alignment from Code Review

  • There is an ongoing discussion in !186881 (comment 2433531852) about which shortcuts to use in the Merge Request > Changes tab. This feature should follow whatever the aligned upon shortcuts are there for consistency.

  • In the Merge Request > Changes file filter, there is a ⌘P keyboard shortcut that opens up a larger filter bar. Design is currently discussing whether or not this should be kept in #535503 (comment 2445664166). The result of this discussion should be reflected on both file trees in Source Code and Code Review.

    File tree ⌘P menu (pending discussion) MR ⌘P menu (pending discussion)

    1. directory_ expanded, hover.jpg

    MR changes tab_ short search bar-1.jpg

    MR changes tab_ P menu.jpg

Links / references

Documentation blurb

Overview

A file tree view will makes it easier to browse the contents of a repository, a common task, reducing the need to pull a projects source code locally simply to read it.

This feature will provide a persistent file tree view that allows the repositories contents to be browsed as a tree, and provide an improved navigation experience because the user will not have to switch between the file list and file view, which is disorienting.

Use cases

Thanks @victorwu for enumerating a number of scenarios here: https://gitlab.com/gitlab-org/gitlab-ce/issues/13723#note_24460171

Feature checklist

Make sure these are completed before closing the issue, with a link to the relevant commit.

Out-of-scope

  • Project overview page will not show the file tree at this time due to layout constraints #19530 (comment 2432121108). If we get a signal from users this is desired, that can added in a future iteration.
  • When users type an input into the filter bar in Merge Request > Changes, the formatting changes from Tree view to List view. In a later iteration, the file structure should be preserved so that users filtering the file tree should not face formatting changes.
Edited by Alyssa Trinh