Skip navigation and jump to content

Felix Nehrke

I write about software development and software architecture.

deutsch

Organize project-directories

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. Later I started to think about the folder structure and, as the name suggests, to organize it. In this article I would like to bring this organization closer and explain 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. Over time it became more and more difficult for me to find them again and sometimes I was amazed at the location where I found folders. I first addressed the problem when I started programming.

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

Over the years, new ideas, technologies and questions came up again and again, which is why I have repeatedly adapted my strategy so that I have come to my current structure. Although the process is still ongoing, think that this post will help you gain a better understanding of the organization.

The structure

To get an overview of my setup, I visualize it here once and then explain how it comes about.

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

At first glance, this structure may look huge, complex or exaggerated, but it follows some simple rules. It generally 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

The Development folder serves as the basis. This folder perfectly complements the structure of xdg-user-dirs and clearly identifies the folder in which I put my development projects.

xdg-user-dirs is a program that manages a number of standard folders to better organize data. It is developed by freedesktop.org, an organization that develops standards around graphic computer systems. These standards are taken into account by various programs in the Linux world and can usually also be applied to macos and Windows without any problems.

The organizational units

I maintain a separate folder for each organizational unit within the base folder. This enables me to determine exactly whether it is a private project, a company project, a customer project or an open source project. It is advisable to think about naming the organizational unit. For my private projects, I simply use my internet synonym. For companies or other organizations, I usually simply name these directories after their name in small letters and with a minus sign as a word breaker.

The project URL

Finally there is a URL to the actual project. The attempt is made to map the URL to the remote code repository, even if it does not yet exist.

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

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

The commands that are necessary for this are clear (I 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 soft link in the alternative organizational unit.

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

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

$HOME
└── Development
    ├── examples
    │   └── git.org.example.com
    │       └── Org
    │           └── Repos
    │               └── Project
    └── alternative-organisation
        └── git.org.example.com
            └── Org
                └── Repos
                    └── Project → ~/Development/examples/git.org.example.com/Org/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 procedure enables meta information to be assigned. 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, but I think that this fact is negligible and that it only takes some getting used to to enjoy the benefits afterwards.