How I Organize my GitHub Repositories

By Andrei Cioara

Does your GitHub Repositories’ Page look like this?

* Some entries in the page have been removed for brevity in illustrating the point. All remaining entries are as seen on the repositories page of this user. ** The user has been picked at random and my intention is not to criticize, but to offer it as an example.

Let’s have another look.

First project is an actively developed, clean, well structured project, written and maintained by the author himself. With over 300 stars, this is the most popular project of this user so far and possibly the one the user wants to showcase when describing his open source contributions.

Then below, we see a forked repository, which looks somewhat related to the first one. However, it is hard to gauge the user’s involvement here without drilling into it. Is he a co-author? Is a top contributor? Is the fork any different from upstream? Hard to tell.

Third, we see another original project, but this time not as popular as the eslint plugin above. That is fine, maybe one day it will receive its fair share of love, the description looks promising.

Fourth, another fork, but this time nothing has been updated for over a year. I guess the user pressed fork by mistake?

Fifth is some experiment of the user. The description says it’s “really bad”, not sure why is it still around and whether it could be of interest to me.

Finally, I am not really sure what the sixth repository contains. I looked inside and there are many C# files, but I cannot tell what they do. The description does not help much either. However it is there, together with all the other repositories.

The issue is that all of these repositories are on the same level. There is no order, no differentiation between them. They just sort of exist on the user profile.

The user is not to blame. GitHub does not provide any easy mechanism to organize your repositories. This has been bothering me since I first joined the site in 2013, but I think I found a nice solution.

Two reasons why I am bringing this issue up:

First — your sanity. I like to keep things organized. While I only have 82 repositories on GitHub, the number of software projects I keep offline is in the 1000s. There is no way I can remember the name of each of them and if I were to only keep them in GitHub, I would have to go through them one by one until I find what I am looking for.

If you think having 1000 GitHub repositories could never happen, just check @sindresorhus. I suspect he actively goes through his forks and deletes them when they are up to date with the upstream.

Yes, you can filter out forks and search by language, but that is everything GitHub provides

Second — recruiters and interviewers. It’s not a secret that your GitHub profile supplements your CV when applying for jobs. Sometimes it is a required field in the application form. Other times it is just a background check done by an interviewer or recruiter.

Given that you usually receive no feedback on the performance of your application, why risk having your GitHub profile in poor shape? Interviewers are mainly looking at your repositories to see one thing: are they clean, readable and well maintained? I would prefer them to only find the best of the best when they look me up, not some Udemy React Course which I did in an afternoon and I still keep around for future reference.

Group repositories together using Organizations!

I only keep the most important projects on my profile page. Projects which I want others users to find and read. Projects which I cleaned up and I am proud of. Projects which I hope others will find useful. Projects where I accept and encourage contributions.

Everything else goes into an Organization. This is how that shows on my profile.

My “folders” disguised as Organizations

What I have here:

  • aicioara-forks — Projects I contributed to. Anything that I pressed “fork” on goes here. Be it a single line of code change or heavy open source contributions. I never have to delete stale projects.
  • aicioara-boilerplate — Very rarely I start a new project from scratch. Instead, I have boilerplate repositories which are setup for various frameworks: react, ink, chrome extension, no-framework, etc. I group them so I can easily find them later, either from my own laptop or from the work computer.
  • aicioara-gh-pages — I own some DNS domains and they all point to some GitHub page or another. I use this organization to keep track of my online presence and find things easier.
  • aicioara-old — Repositories that contain code I may want to refer to later, but I do not really want to be associated with. Maybe it’s a high school or university project with no stars and which no longer reflect the way I code. I don’t have time to update them, I still need to refer to them sometime, but I don’t want them to say “hey, this is how Andrei is coding today”.

GitLab is actually even better. Organizations are called groups here, but you have subgroups as well. As many as you want and as nested as you want, so you can recreate an entire nested folder structure.

Gitlab’s Nested Groups

Bitbucket has the concept of Projects, which is very similar to the GitHub Organizations, but a lot more confusing. You can only use them if you transfer the ownership to a team, but the team handle can be the same as your user handle, so technically it is still yours, except it’s not quite the same. Maybe if I spend more time getting my head around it, I will appreciate the construct.

In their quest to be minimalist and only include the bare minimum of features, GitHub decided not to give developers power to organize their online code portfolio in a sane and meaningful way. Gitlab and Bitbucket followed suit.

One hacky way to add that feature is by abusing the Organizations feature (Groups in GitLab, Projects in Bitbucket), but that comes with the downside of changing the project URL, something you should never do for a project that is already popular.

Hey there, Andrei here. If you enjoyed the article and want to make sure you know about my next one, you can sign up with your email address below. I only send blog-related updates and have a zero-spam policy.

Gain control over your news, do not let the corporation algorithms decide for you!

@bradzacher I hope you don’t mind that I used your repositories as examples. I found you randomly, and your profile helped me illustrate my points. I think picking a real-world example is more powerful than fabricating an image. I hope I did not offend you in any way.