Skip to content

Directory description file

Description

The Project details and Repository files pages show a list of directories, together with the latest commit that made changes to the respective directory.

I find those last commits useful only occasionally, and of those cases where I find them useful, most of the time it's only because the commit message reminds me of what the directory contains.

I think it would be more useful to show a description for each directory directly. For example, the home page of the GitLab project it self currently looks like this:

2017-08-28_1155

Now imagine it would look like this:

2017-08-28_1245

I think this would not only make it easier for regular developers to find the file they are looking for but it would also help a lot for onboarding new developers.

If GitLab implements it, I would hope that eventually it gets picked up by GitHub and IDEs as well.

Proposal

A file is placed in the root of the repository. In this file there is a mapping from path to attributes, something like this (the format is just a rough idea and should be discussed):

.github/
 description: Templates for GitHub mirror issues
.gitlab/
 description: Templates fro GitLab issues
app/
 description: Main source code for GitLab
app/assets/
 description: Assets for the GitLab web interface
...

This file is then parsed by GitLab (and later other tools) and displayed in the file list.

A number of thoughts:

  • The file should be in the root directory of the repository (i.e. not in each directory) because subdirectories might be exposed by web servers, might have the need to be empty, etc.
  • Actually there is no reason why this scheme cannot be extended to files as well.
  • To keep it flexible instead of being called .descriptions and containing only descriptions, it could be called something like .attributes and have an attribute description like in the example above. This way further attributes could be added, like internal, icon, hidden, etc.

Feature checklist

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