GitHub has taken a strong stance on not implementing a folder structures to support sorting of repositories. Why is that? They believe that it is unnecessary – and it is. Adding folders would add a layer of confusion that can be solved easily at a more meta level. This holds true whether you're using the community version of GitHub or hosting your own Enterprise version.

How Do I Organize Repos?

GitHub has a meta concept called topics that you can apply to repos. These are just tags with a different name. By applying topics, repositories can be more easily searched. This alleviates the need to use a naming scheme to identify repos (ex. naming your repo something like "myGroup-myTeam-myProject-myService").

Many folks cling to the hierarchical construct of folders. I don't blame them; it's logical and makes sense. It's something we can easily relate to in our physical world. But in this case, you're not going to get that type of organization. Instead, you're stuck with thinking about venn diagrams and unions and intersections based on tags. So you have to think to yourself, "What are the ways that I, or someone else, might search for this in the future?" More on that in the final section of this article.

How Do I Search Repos?

I'm glad you asked! To search for repos with a specific topic, go to the search bar and use this syntax: topic:TOPIC. Here's an example:

Does this really solve the problem?

As of January 1, 2021, GitHub has over 204 million repositories. Let's filter that down by searching for a keyword.

Just using a keyword, we got a 0.03% reduction in results. Let's use a topic instead.

Now, we see far fewer repos in the results. And only repos with that specific topic will be in the results. Let's take it one step further and search on two topics.

That's more like it. We have gone from 204M results to 558 with just two topics.

How You Can Use Topics

If you are looking for a nice way to organize your repositories, use topics to specify things like:

  • Business units
  • Project and/or product names
  • Team names
  • Service names

If you're looking to make your repo discoverable across your business unit and beyond so that others can use or contribute to it, then consider using topics for things like:

  • Language
  • Intended purpose
  • Subject area
  • Community

Don't let yourself be limited by these lists. Apply tags freely and find what makes the most sense for your needs.