gh-get

gh-get

gh-get is a GitHub CLI based re-implementation of ghq.

Installing the extension

gh extension install britter/gh-get

Usage

gh get [--fork] OWNER/REPO

This will clone the repository identified by OWNER/REPO into $HOME/github/$OWNER/$REPO.

Example:

gh get britter/gh-get will clone this respository into ~/github/britter/gh-get

[!TIP] gh-get also accepts full GitHub URLs like https://github.com/britter/gh-get as well as URLs pointing to branches, tags, commits, files, pull requests, or issues — anything you can copy from your browser.

Changing into the cloned directory

gh-get prints the clone destination to stdout, which makes it easy to combine with cd:

cd "$(gh get britter/gh-get)"

Since cd doesn't work inside a subshell, you may want to add a wrapper function to your shell config that does this automatically:

bash / zsh

get() {
  local dest
  dest="$(gh get "$@")" && cd "$dest"
}

fish

function get
  set dest (gh get $argv) && cd $dest
end

After adding the function, get britter/gh-get will clone the repository and drop you straight into the directory.

Forking

When you don't have write access to a repository, gh-get will ask whether you want to fork it first. If you answer yes, the fork is created under your account and cloned into $HOME/github/$YOUR_USERNAME/$REPO.

You can also pass --fork to skip the prompt and always fork:

gh get --fork OWNER/REPO

If the repository does not allow forking, the original is cloned and a warning is printed.

Updating an existing clone

If you run gh get for a repository you already cloned, gh-get asks whether to update the existing clone instead of failing. If you agree, it fetches upstream and fast-forwards the current branch (local changes or a diverged branch are left untouched). When the existing clone points at the original but you now ask to fork, the fork is created and — after a confirmation prompt — the remotes are reconfigured (origin → your fork, upstream → the original).

Configuration

There are two environment variables that control the location gh-get clones repositories to:

• GH_GET_FOLDER: The name of the folder inside the user home that repositories are cloned into. The defaults to github which means repositories are cloned into $HOME/github. If you prefer a different folder name or path inside your user home, configure this variable.
• GH_GET_ROOT: The full path to to the folder that repositories are cloned into. This defaults to $HOME/$GH_GET_FOLDER. Change this is you want repositories to be cloned to a location outside your user home.

Building

Using Nix

This project uses the nix package manager to define a development environment that has everything needed to build gh-get. In order to enter the dev shell execute nix develop. Inside the dev shell you can build gh-get by running go build.

Without Nix

Make sure you have a Go toolchain installed in your path that matches the version defined in go.mod. Build gh-get by running go build.

Testing

The project contains two sorts of tests:

• Unit tests written in go testing individual functions. You can execute these by running go test ./...
• Integration tests running inside a docker container. You can execute these by running cd integration-tests && sudo GH_TOKEN=<personal access token> docker compose up --build --abort-on-container-exit.

To get a personal access token, you can either look the one currently used by your GitHub CLI installation up in ~/.config/gh/hosts.yaml or generate a new one in your GitHub settings.

[!IMPORTANT] Before submitting pull requests make sure to run all tests and add new test cases for the functionality you've added.

License

Code is under the Apache Licence v2.