README.md

Github Directory (ghd)

Utility to manage cloning and cd'ing to Github repos.

The idea behind this tool is to give an easy to access, centralized location for local clones of Github repositories.

Dependencies

• For ghd and ghd <ambiguous term>, you'll want fzf in your PATH.
• To get repo lists from github, you'll want the Github CLI. Make sure to run gh auth login to set it up.

If you want to help with development, grab:

• bats-core for testing
• kcov for coverage

Installation

Put ghd somewhere in your PATH, then add:

alias ghd=". ghd"

to your bashrc. (Sourcing the script allows it to change directory.)

Usage

ghd <repo_name or repo url (with https://github.com or [email protected]:)>
ghd <already cloned user, org, or repo name>?!+*
ghd /
ghd

For example, to clone and cd to this repo:

ghd okkays/ghd

To then git pull --all updates from and cd to that same repo:

ghd okkays/ghd!
# or
ghd ghd!
# or
ghd gh!<Enter>

To checkout a branch, commit, etc for a repo:

ghd okkays/ghd@main
# or, to pull first:
ghd ghd@main!
# or, from a url:
ghd [email protected]:okkays/ghd@main
# or, if you're already in a repo, as a shortcut:
ghd @main

You can also ask ghd to go to a new branch using a ?:

ghd @main?

To go to the root of your ghd-cloned repos:

ghd /

To use fzf to search through your ghd-cloned repos:

ghd

If you want to create a new repo, you can use:

ghd okkays/my_new_repo+

• The created repo will be private by default.
• This will fail if your repo already exists.

If you've already checked out some of a user's repos, you can switch to that user's directory:

ghd okkays/

(After installing the Github CLI and running gh auth login)

You can list a user/organization's repositories using +:

ghd okkays+

Or, you can just pull/clone them all using *:

ghd okkays*

or

ghd okkays*!

Finally, to switch to the root of all of your cloned repos:

ghd

There, you can use directory-based tools like find, ag, etc to figure out where a piece of code is.

If you just want to use the location of the command (rather than switching directories) you can add a ?, for example:

ls `ghd okkays/ghd?`

Configuration

Github CLI Integration

ghd can work with Github CLI! Install the cli separately, and then run gh auth login. Remote results should start appearing in the ghd lists, and you can type ghd repo instead of your_username/repo to clone things!

Config Variables

ghd reads the following environment variables:

• GHD_LOCATION: The directory in which to store repos (/tmp/ghd by default).
• GHD_USE_SSH: Whether to clone via ssh (uses https by default).
• PAGER: The pager to use for showing fzf preview results.

To configure them, add (for example):

export GHD_LOCATION="$HOME/.ghd"
export GHD_USE_SSH=1

to ~/.bashrc

Running tests

Just run:

bats ./test.bats

I recommend using entr for this:

ls | entr bats ./test.bats

To get coverage results, run:

kcov --include-path=. coverage bats ./test.bats

This will create a coverage folder with test coverage results.