Better READMEs for GitHub Forks

Adam Mckaig

TL;DR

I kept forgetting why I forked, so I came up with a workflow and a little tool to help me remember. Maybe it can help you, too.

GitHub’s pull requests are awesome. I send one whenever I encounter a bug in a library which is major enough that it’s distracting me from real work, but minor enough that I can fix it without shaving a yak. The workflow is simple and well-documented, so I won’t go into it here.

Until my pull request is closed — which sometimes takes a day, other times a year — I can source the library from my fork. Both Bundler and Pip make this easy. But it’s a temporary solution; I have zero interest in maintaining the fork long-term, and it’s yet another thing to keep track of.

For example: my fork of Grit. I created it a year or so ago, and haven’t touched it since. Why does it exist? What did I fix? Did I submit a pull request? Was it merged upstream? I don’t remember. It was a long time ago.

Fortunately, I don’t have to remember. I can easily see what the fork is all about, because the repo home page is actually pretty useful. Instead of an out-of-date copy of the upstream README (as is the norm), it contains links to its pull requests, with icons indicating their status:

Screenshot of my Grit fork's README The README of my Grit fork.

I used to create the README manually, which was predictably tedious. So I wrote ForkReadme to generate it for me, and pullstat.us to serve the status images. Usage is very similar to GitHub Pages:

  1. Install via RubyGems:

    $ gem install forkreadme
  2. Create an orphan branch in your repo:

    $ git checkout --orphan forkreadme
    $ git rm -rf .

    The git rm part is a bit scary, but it’s just clearing the working area.
    Check out git help checkout and search for --orphan for more info.

  3. Generate the README:

    $ forkreadme > README.md
  4. Push it to GitHub:

    $ git add README.md
    $ git commit -m "Add fork notes"
    $ git push origin forkreadme
  5. Change the default branch of your fork on GitHub:

    Screenshot of GitHub's admin buttonClick the Admin button in your fork.
    Screenshot of GitHub's default branch settingChange the default branch dropdown.

And that’s it. Maybe one day, GitHub will display something similar for forks. It’d make my life easier if they did. Until then, I’ll be using ForkReadme.