Skip to content
Daniel Gietmann
← Blog
Coding

Cleaning up forgotten GitHub repos without blindly trusting the matches

gitsorted shows all your GitHub repos with creation and push date, finds possible duplicates and forgotten repos and lets you archive or delete several at once. Which rules it sorts by, where the duplicate search gets it wrong and what the app gets from you in return.

Spend a few years on GitHub and you accumulate repos: experiments from a single afternoon, copies with -old or -v2 in the name, forks nobody ever worked on. In GitHub's repo list you only see names and the date of the last change. What can go, you have to piece together yourself.

That is what I built gitsorted for. You sign in with GitHub and get all repos that belong to you or that you see through an organization in one table: when they were created and last pushed, size and stars, plus a badge showing whether the repo is private or public. Next to that, the app shows possible duplicates and cleanup candidates, and you can archive or delete several at once. The hosted version runs at gitsorted.eu, the code is on GitHub under the MIT license.

What counts as a candidate

The rules are in src/lib/cleanup.ts and are fairly simple:

  • Empty: GitHub reports a size of 0 KB.
  • Almost empty: at most 10 KB and no detected programming language, so usually just a README or a license.
  • Uploaded once: The last push was less than ten minutes after creation, and the repo is older than 90 days.
  • Untouched fork: The last push was less than one minute after creation.
  • Quiet for a long time: The last push was more than 730 days ago. Archived repos are excluded here.

These are hints, not a verdict. A small repo with a single configuration file or a fork you only want to keep as a bookmark ends up on the list just like real junk.

How the duplicate search compares names

For duplicates, gitsorted turns every name into a comparison key. Capitalization and separators are dropped, along with typical copy markers at the end such as copy, old, backup, test, v2 or appended digits, and at the beginning my, old, new, test or tmp. Generated IDs such as app-03912df4c6de and timestamps are cut off as well. If two repos have the same key, or if the keys, from a length of six characters, differ by exactly one letter, they end up in one group. That is how the app finds weather-app and wheather-app. As a second path, repos with the same description count, if it is at least twelve characters long.

These rules also kick in where there is no copy at all. A few examples that follow directly from the code:

  • web1, web2 and web3 all become web and form one group, even if they are three different projects.
  • project-2024 and project-2025 both become project. If you create a separate repo per year, you get them shown as duplicates.
  • contest loses the test at the end and becomes con. If there is a repo con next to it, the two are linked.
  • docker-pg-backup becomes dockerpg, because backup counts as a copy marker.

So always look at a group before you delete anything from it. The app sorts the members by last push, the newest is at the top. It does not tell you which of them is the original.

Archive or delete

For both, you select the repos in the table. Archiving makes a repo read-only, but it is kept in full, and you can unarchive it again later. When deleting, you have to type the word löschen into the dialog. The app works through the repos one after another, because GitHub answers many write calls in a short time with limits, and reports for each repo whether it worked.

Deleted is not immediately final on GitHub. According to the GitHub documentation, a deleted repo can be restored for 90 days, but not if it was part of a fork network that still contains other repos. You cannot get anything back through gitsorted itself, that only works in the GitHub settings. If you are not sure about a repo, archive it first.

With organizations there is one more catch. gitsorted queries the repos with affiliation=owner,organization_member. According to the GitHub API, that includes every repo you have access to through an organization, so also repos you only collaborate on. Archiving or deleting only works there with admin rights. If they are missing, the action fails for that repo with a message, and the others carry on.

What the app gets from you

To sign in, gitsorted requests the GitHub permissions repo and delete_repo. Without repo the app sees no private repos and cannot archive anything, without delete_repo it cannot delete anything. That is a lot of access, and you should know that you are giving it. You can revoke it at any time under GitHub → Settings → Applications.

There is no user database. The session and the GitHub token sit encrypted in HTTP-only cookies in your browser, and the session is set to seven days. The app fetches repo data from GitHub on demand and does not store it. If a MongoDB is connected, it only counts anonymous totals for the landing page: deleted and archived repos, freed storage and the number of accounts. For the accounts, an HMAC of the GitHub user ID is stored, no names and no repo names.

Running it yourself

If you do not want to give your token to someone else's instance, you run gitsorted yourself. You need a GitHub OAuth App with the callback address https://deine-domain/api/auth/callback/github. Leave the option "Expire user access tokens" switched off there, otherwise the app cannot write renewed tokens back into the cookie. Then you set the environment variables and start the image:

docker build -t gitsorted .
docker run -p 3000:3000 --env-file .env gitsorted

Required are BETTER_AUTH_SECRET (at least 32 characters, for example from openssl rand -base64 32), BETTER_AUTH_URL, GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET. MONGODB_URL is optional and only switches on the numbers on the landing page. According to the README, MongoDB 8 does not start on Linux kernels from 6.19 onward, there you use mongo:7. With LEGAL_NAME, LEGAL_ADDRESS and LEGAL_EMAIL your instance gets a legal notice and a privacy page. The image is a Next.js server on port 3000 and runs like that on Coolify too.

The candidates and duplicate groups follow fixed rules, and those also catch repos you want to keep. Go through the list, archive when in doubt and only delete once you are sure.

Common questions

How do I find forgotten GitHub repos?
gitsorted marks repos as cleanup candidates when they are empty or almost empty, were only uploaded once, are an untouched fork, or when the last push was more than 730 days ago. These are hints, not a verdict. A repo you want to keep can end up on the list too.
How does gitsorted detect duplicate repos?
gitsorted turns every repo name into a comparison key without capitalization, separators and copy markers such as copy, old, backup or v2. Repos with the same key, with a key that differs by exactly one letter, or with the same description end up in one group. That also hits repos like project-2024 and project-2025, which are not copies.
Can I restore a deleted GitHub repo?
According to the GitHub documentation, a deleted repo can be restored for 90 days, but not if it was part of a fork network that still contains other repos. That only works in the GitHub settings, not through gitsorted. If you are not sure, archive the repo first.
Which permissions does gitsorted need and what does the app store?
gitsorted requests the GitHub permissions repo and delete_repo. There is no user database: the session and the GitHub token sit encrypted in HTTP-only cookies in your browser, and the app does not store repo data. You can revoke the access at any time in the GitHub settings under Applications.