August 23, 2021

ghqのセットアップから使い方まで

ghq¹ は、ソースコードリポジトリの取得・管理を助けてくれるツールです。

個人でたくさんのリポジトリをローカルで管理しようとすると乱雑になってしまいますが、ghq を使うことで解決できます。

ghq は、go get に似たディレクトリ構造でリポジトリを管理してくれます。 また、git や svn などの複数の VCS に対応していて、それらを意識せずに統一的に扱うことができます。

このブログでは 簡単な ghq の使い方から、fzf を用いて簡単に任意のリポジトリに cd したり、エディタで開いたりする応用までまとめます。

環境

PC は mac で、シェルには zsh を使っています。

ghq のセットアップ

まず、brew でインストールします。

% brew install ghq

.gitconfig に以下のように追記します。

ここで root を変更するとデフォルトの管理フォルダを変更できます。 user には git の username を設定してください。

[ghq]
	root = ~/src
	user = your_username

ghq の使い方

ghq getでgit cloneと同じようにでリポジトリを取得できます。

また、ghq get -pのように -p オプションを付けると ssh で clone できます。

# 通常の使い方
% ghq get https://github.com/x-motemen/ghq

# "https://"はいつでも省略できる
% ghq get github.com/x-motemen/ghq

# github.com のリポジトリの場合"github.com"を省略できる
% ghq get x-motemen/ghq

# gitconfig に設定されているuserのリポジトリの場合、"user名"も省略できる
% ghq get ghq

ghq get したリポジトリはこんな感じで階層的に管理されます。

このままではリポジトリのディレクトリに移動したりするのが面倒くさいので、 fzf を導入して簡単に移動できるようにします。

fzf で応用する

fzf² は曖昧検索した結果を標準出力するコマンドです。このコマンドをつかって、ghq で取得したリポジトリ群を検索します。

まず、brew でインストールします。

% brew install fzf

以下は設定しなくてもいいのですが、.zshrcに以下のように追記すると検索時の画面が僕好みになります。 具体的には、fzf の検索窓を上下逆にしたり、枠をつけています。

export FZF_DEFAULT_OPTS='--height 100% --reverse --border'

任意のリポジトリに cd できるようにする

fzf を使って、検索して、そのリポジトリの配下のディレクトリに cd できるようにします。

準公式ドキュメント³の例を参考に 処理を書き出すと以下のようになります。この内容を.zshrcに追記してください。

エイリアスにしたい場合

gcd にエイリアスを貼っています。

alias gcd='cd $(ghq root)/$(ghq list | fzf)'

キーバインドにしたい場合

zsh 利用時にキーctrl + ] を押すと、登録したキーバインドが呼び出されます。

function ghq_cd() {
  local repo="$(ghq list | fzf)"
  if [ -n "$repo" ]; then
    BUFFER="cd $(ghq root)/${repo}"
    zle accept-line
  fi
  zle clear-screen
}
zle -N ghq_cd
bindkey '^]' ghq_cd

その他コードレシピ

僕が使っているレシピを共有します。

fzf での検索時に各リポジトリの README をプレビューし、リポジトリを vscode で開く動作になっています。 また、bat を使うことでカラーでプレビューしています。

code を開く際に exit してシェルを閉じていますが、mac の zsh はデフォルトではできないようになっているので自動でシェルを閉じたい人は zsh の設定からできるように変えておいてください。

エイリアスにしたい場合

alias gcode='code $(ghq root)/$(ghq list | fzf --preview "bat --color=always --style=numbers --line-range=:100 $(ghq root)/{}/README.*") && exit'

キーバインドにしたい場合

# ghqの管理フォルダをfzfで簡単にcodeで開けるようにする
function ghq_code() {
  local repo="$(ghq list | fzf --preview "bat --color=always --style=numbers --line-range=:100 $(ghq root)/{}/README.*")"
  if [ -n "$repo" ]; then
    BUFFER="code $(ghq root)/${repo} && exit"
    zle accept-line
  fi
  zle clear-screen
}
zle -N ghq_code
bindkey '^]' ghq_code

以下のようにプレビューしながら検索できます。

まとめ

ghq + fzf で快適なリポジトリ管理が実現できました。