Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install ghr

It will make the ghr command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall ghr uninstalls.

Back to the crate overview.

Readme

🚀 ghr

Yet another repository management with auto-attaching profiles.

🔥 Motivation

ghq is the most famous solution to resolve stress of our repository management currently. However, I wanted to customise the git configuration by some rules, such as using my company email in their repositories.

To achieve that, ghq was not enough for me. So I have rewritten them as simple, in Rust, the robust and modern language today.

📦 Installation

macOS / Using Homebrew (easy)

brew install s6n-jp/tap/ghr

To upgrade:

brew upgrade s6n-jp/tap/ghr

Windows / Using scoop (easy)

scoop bucket add siketyan https://github.com/siketyan/scoop-bucket.git
scoop install ghr

To upgrade:

scoop update ghr

Any OS / Using cargo (classic)

If you have not installed Rust environment, follow the instruction of rustup.

cargo install ghr

For upgrading, we recommend to use cargo-update.

cargo install-update ghr

🔧 Installing the shell extension

To extend ghr features to maximum, it is recommended to install the shell extension. Add the line below to your shell configuration script to enable it.

Bash

source <(ghr shell bash)

To enable completions, add the line into ~/.bash_completion.

source <(ghr shell bash --completion)

Fish

ghr shell fish | source

To enable completions, add the line into ~/.config/fish/completions/ghr.fish.

ghr shell fish --completion | source

💚 Usages

Usage: ghr <COMMAND>

Commands:
  cd       Change directory to one of the managed repositories (Shell extension required)
  clone    Clones a Git repository to local
  delete   Deletes a repository from local
  init     Initialises a Git repository in local
  list     Lists all managed repositories
  open     Opens a repository in an application
  browse   Browse a repository on web
  path     Prints the path to root, owner, or a repository
  profile  Manages profiles to use in repositories
  search   Perform a fuzzy search on the repositories list
  shell    Writes a shell script to extend ghr features
  sync     Sync repositories between your devices
  version  Prints the version of this application
  help     Print this message or the help of the given subcommand(s)

Options:
  -q, --quiet    Operates quietly. Errors will be reported even if this option is enabled
  -v, --verbose  Operates verbosely. Traces, debug logs will be reported
  -h, --help     Print help

Cloning a repository

ghr supports many patterns or URLs of the repository to clone:

ghr clone <owner>/<repo>
ghr clone github.com:<owner>/<repo>
ghr clone https://github.com/<owner>/<repo>.git
ghr clone ssh://git@github.com/<owner>/<repo>.git
ghr clone git@github.com:<owner>/<repo>.git

If you have installed the shell extension, you can change directory to the cloned repository:

ghr clone <url_or_pattern> --cd

If you often use repositories of a specific owner, you can set the default owner to be resolved.

[defaults]
owner = "siketyan"

ghr clone <repo>

Changing directory

You can change directory to one of the managed repositories on the shell. It requires installing the shell extension.

ghr cd <url_or_pattern>

Attaching profiles

Create ~/.ghr/ghr.toml and edit as you like:

[profiles.default]
user.name = "Your Name"
user.email = "your_name@personal.example.com"

[profiles.company]
user.name = "Your Name (ACME Inc.)"
user.email = "your_name@company.example.com"

[[rules]]
profile.name = "company"
owner = "acme" # Applies company profiles to all repositories in `acme` org

[[rules]]
profile.name = "default"

Configuring applications to open repos in

Edit ~/.ghr/ghr.toml and add entries as you like:

[applications.vscode]
cmd = "code"
args = ["%p"]

Note

%p will be replaced by the repository path.

Finding path of the repository

ghr path # Root directory
ghr path <owner>/<repo> # Repository directory
ghr path <url> # Repository directory resolved by URL
ghr path github.com/<owner>/<repo> # Repository directory of the specified host
ghr path --owner=<owner> # Owner root
ghr path --host=github.com # Host root
ghr path --host=github.com --owner=<owner> # Owner root of the specified host

Syncing repositories and their state

Warning

This feature is experimental.

ghr supports dumping and restoring the current branch and remotes of managed repositories.

ghr sync dump > repositories.toml
ghr sync restore < repositories.toml

🛠 Customising

You can change the root of repositories managed by ghr by setting environment variable GHR_ROOT in your shell profile.

ghr path # ~/.ghr
GHR_ROOT=/path/to/root ghr path # /path/to/root