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.

Navigating around projects

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.

Let me know how you like it!