Organize project-directories

July 5, 2020

As a developer, I always have to deal with various projects. Many of them differ significantly from each other, others are very similar or related to each other. However, what unites them is the fact that I had organized them poorly in the past. Later I started to think about the folder structure and to organize it better. In this article I would like to explain this organization to you and describe how I got there.

Background

As already mentioned, this text is a direct result of my experience. In the past, my documents, folders, and projects were scattered across the entire file system. After a while it became very hard for me to find them again and sometimes I even wasn’t able to find them again. I first addressed this problem when I started programming.

At that time I started to collect all my projects in one folder. I just had a folder called web somewhere. This folder in turn contained folders that each represented a website I was working on. That was easy and served its purpose, but the disadvantages of this structure quickly became apparent:

How do I organize a website that consists of several individual projects?
How do I keep different tasks apart?
What do I do in the event of a name conflict?
Is this actually a web project?

Over the years, new ideas, technologies and questions kept coming up. Accordingly, I kept adjusting my strategy and that’s how I got my current setup. I would like to introduce this setup here and create a better understanding of how to organize your projects. So, even if the process never finishes, this Model may help someone, maybe even you.

The structure

To get an overview of my setup, I visualize the setup here once and explain it afterwards.

$HOME
└── Development (1)
    ├── acme-company (2)
    │   ├── github.com
    │   │   └── acme
    │   │       └── open-source-project (3)
    │   ├── gitlab.example.com
    │   │   ├── Project-A
    │   │   │   ├── service-a
    │   │   │   └── service-b
    │   │   └── Project-B
    │   │       ├── service-a
    │   │       ├── […]
    │   │       └── service-n
    │   └── svn.example.com
    │       └── legacy-project
    └── nemoinho (2)
        ├── gitea.nehrke.info
        │   └── nemoinho
        │       └── nehrke.info
        └── github.com
            └── nemoinho
                └── GreasemonkeyHeaderPlugin

At first glance, this structure may look huge and complex, but it follows some simple rules. It only consists of the following elements:

1	A folder as a starting point
2	One or more organizational units
3	The URL to the project

The starting point

I use the Development folder as a basis, which perfectly complements the structure of xdg-user-dirs. The folder clearly identifies the purpose of managing development-projects by its name.

xdg-user-dirs is a program from freedesktop.org that manages a number of standard folders to better organize data.

The organizational units

Within the basic folder, I maintain a separate folder for each organizational unit. This allows me to determine the exact context of a project and know exactly what it is about. For my private projects, for example, I simply use my internet synonym as an organization. For companies or other organizations, I usually just name these directories after their names. It is important to me to stay consistent, so I always write the folders in lower case and with a minus sign as a word separator. In general, however, it is important to briefly think about the naming and to choose a meaningful name.

The project URL

Finally, there is a URL to the actual project. There I attempt to map the URL to the remote code repository, even if it may not yet exist.

Example URL: https://git.org.example.com/Org/Repos/Project.git

The protocol is ignored
The domain is a folder, e.g. git.org.example.com
Each level of the URL before the project becomes a folder
The project is cloned

The commands that are necessary for this are simple (I work a lot in the terminal and mainly use bash for something like this):

mkdir -p ~/Development/examples/git.org.example.com/Org/Repos
cd $_
git clone https://git.org.example.com/Org/Repos/Project.git

The result looks like this:

$HOME
└── Development
    └── examples
        └── git.org.example.com
            └── Org
                └── Repos
                    └── Project

More tips

It happens from time to time that a project cannot be clearly assigned to an organizational structure. In this case I like to use the possibility of symlinks in the file system. To do this, I determine which organizational unit the project should be assigned to and save it here accordingly. Then I create a similar symlink in the alternative organizational unit.

mkdir -p ~/Development/examples/git.example.com/Repos
cd $_
git clone https://git.example.com/Repos/Project.git
mkdir ~/Development/alt-organisation/git.example.com/Repos
ln -s ~/Development/examples/git.example.com/Repos/Project $_

The result is a clear structure that fits well into the other projects:

$HOME
└── Development
    ├── examples
    │   └── git.example.com
    │       └── Repos
    │           └── Project
    └── alt-organisation
        └── git.example.com
            └── Repos
                └── Project → ~/Development/examples/git.example.com/Repos/Project

This procedure can also be used sensibly if you want to rename a project. Sometimes there are still old references in the system, but we don’t get to cleaning everything up at once. In this case, I simply rename the project and create a symlink that points from the old location to the new location.

Conclusion

The system offers a number of advantages. In particular, this approach enables me to assign meta information. But it also offers applications that are less obvious. With this strategy, for example, development with Go is very easy since the requirements for the GOPATH have already been met. The complex structure may be a disadvantage. Overall, however, I think that the disadvantages are more than offset by the advantages. It only takes a little while in order to fully exploit the advantages.