The Best Code I’ve Ever Written
I often say the best code I’ve ever written is a little tool called gh. It’s a little shell script that has saved me countless hours over the last couple of years since I wrote it.
Essentially it helps you manage your local github repositories, but it’s so much more than it sounds. Like all great CLI tools, it offers you a new, better workflow just about every time you crack open your terminal.
It’s so useful I can’t believe how few people have started to use it. Friends and coworkers I have paired with have seen me use it and asked what it is. Often they quickly become converts to the blissful world that is gh.
The trouble has always been explaining it without actually sitting down and showing it to someone. People understand it immediately when they see me use it, but I haven’t been able to properly articulate it without the demo. I even tried putting up a little animated gif, but despite the rave reviews it’s been sitting around for 2 years and has only gained 16 github stars. :(
Today I decided enough is enough. The world needs to be introduced to gh. You people are simply wasting too much time and energy and I can help you.
gh is kind of like cd except it’s used to navigate to local github repos. It either enters the project directory by github username and repo name, or if it hasn’t been cloned, it clones it first then enters the directory.
It’s useful for people that navigate between projects frequently. OSS contributors, microservices, Go, and Node developers will see this as the most useful since we often jump from project to project many times during our coding sessions. If this doesn’t apply to you, you may not see as much value.
Here what I’m doing is entering the heroku/heroku-pg-extras repo with gh heroku heroku-pg-extras. I already have it cloned so it’s simply a cd into ~/src/github.com/heroku/heroku-pg-extras. Then I run gh npm npm which I do not have cloned, so gh clones it to ~/src/github.com/npm/npm and cd’s into it.
This means you no longer have a ~/projects directory with a bunch of projects you have to keep a mental map of. Conflicting project names are not a problem because nothing could conflict on github. No more ~/projects/test-proj-22. Or ~/projects/companyapp-jeff-fork. You will always know exactly where your projects are.
More importantly, you no longer have to remember if you’ve cloned a particular project on the box you’re currently on. Where did you put that project on your local machine? A different place than your work box? Gah just check out out again. Then in a few weeks you notice you have 4 of the same project in ~/projects. A directory so large that running ls is so bad you have to start piping it through grep.
With gh, the ls repo pursuit is a relic of ancient software practices.
Now here is the point where people think,
“ugh. I don’t want to have my projects in that super long directory structure. I’m fine with ~/projects kthxbye.” — Fickle Engineer
Allow to explain why you do in fact want this super long hierarchy. First, you won’t care that it’s longer than what you have today because you will rarely ever type out the full path, you’ll just be using gh to navigate around.
On the rare times where are referencing a project from another location, you’ll be glad you know exactly where a project is because you already know the github user and already know the repo name.
Why is it ~/src/github.com/npm/npm and not just ~/src/npm/npm? Well you can make it the shorter version if you want (the code is tiny, you can hack it, believe me), but this works well with Go code that has a lot of opinions about how you structure your projects. Arguably this could prevent against collisions too.
Try it out. There is no setup work aside from installing because the point is you don’t have to recall which projects are cloned and where they are cloned. You just start using gh and use that bit of long-term memory for grander challenges.
And if you’ve got to the end and are really curious if those 18 lines of shell code are what I actually consider the greatest code I’ve written in my nearly 20 years of writing code, the answer is a definite yes. It’s the software that I’ve written I use most and has saved me the most time. Being that most of the code I write is node, I’m constantly jumping around projects.
EDIT: I read some feedback that complained about how my title was misleading/clickbait because this is hardly “great code”. It was not my intention for the title to be misleading, and I think that we as a community have a problem if people see this that way. Is this clever or interesting code? Not at all. But rarely is “clever” an adjective that I would use positively when referring to software. “Clever” code is often complicated and difficult to maintain. Certainly not attributes I want of any of my software. The “best” software is that which helps people the most—that which provides the most value. And at least for me personally, this has helped me quite a bit. That’s why I say it’s the best code I’ve ever written.
