Tatsuhiko Miyagawa's blog

ghq + peco/percol

This has been rocking my Twitter developer community for the past few days, but mostly only in Japanese - here’s an attempt #1 to fix this.

tl;dr ghq allows you to organize git clones via a simple CLI and peco or percol makes cd’ing to these directories on your shell a snap.

GOPATH/src for everything

Go has an interesting directory structure that forces you to adopt when you write your own Go program. All your code, along with third party libraries, will be placed in the src/ subdirectory under the $GOPATH directory with each hostname beneath that. It’s a little weird at first but when you get used to it, it makes a lot of sense.

On a recent episode of Rebuild.fm my guest lestrrat mentioned that he adopted this directory structure to all the code he writes, including non-Go code.

I think this is a good idea. And I now set:

export GOPATH=$HOME

so all the code is under ~/src.

ghq to manage repos

Now we’re going to manage these github repositories under ~/src, but doing so manually is a pain because you have to make subdirectories (like github.com/) for each. ghq makes that easy.

By default ghq clones the repo under ~/.ghq but i prefer it to be the same value as the one we specified earlier:

git config --global ghq.root ~/src

Now you can clone repo from github easily, i.e.

ghq get plack/Plack
ghq get git://mygithost.example.com/project.git

and it will be cloned into ~/src/github.com/plack/Plack etc.

cd to these repos

Now we got plenty of repos under ~/src, and when you want to cd into one of these directories, that’d be a pain, because of the deeply nested directory structure.

peco to the rescue.

• ghq list -p will print out all the repos in full path
• peco gives an interactive UI to incrementally filter the directories

Combining the two, all you need to do is:

> cd $(ghq list -p | peco)

and type some query to match the repo you want, then hit enter.

That command is annoying to type - here’s my zsh setup so that I can hit Ctrl-] on my shell to bring up that UI to cd to.

function peco-src () {
    local selected_dir=$(ghq list --full-path | peco --query "$LBUFFER")
    if [ -n "$selected_dir" ]; then
        BUFFER="cd ${selected_dir}"
        zle accept-line
    fi
    zle clear-screen
}
zle -N peco-src
bindkey '^]' peco-src

Importing CPAN/Rubygem libraries

You can clone git repo with ghq if you know the github URL etc. But what if you have a CPAN/Rubygem that you want to fix and don’t know which repo? There are tools for that.

cpan-ghq allows you to pass git repos (in META.json) to ghq, and gem-src provides a gem plugin to run ghq for each install of Gems.