siketyan / ghr

🚀 Yet another repository management with auto-attaching profiles.

🚀 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://[email protected]/<owner>/<repo>.git
ghr clone [email protected]:<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 = "[email protected]"

[profiles.company]
user.name = "Your Name (ACME Inc.)"
user.email = "[email protected]"

[[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

ghr's Issues

Listing candidates to clone from GitHub (with authn)

Clone fork in the original owner's directory (via option?)

Currently clone --fork will clone the forked repository as it is, but making clone --fork clone the fork into the original owner's directory might be more useful.

current: ~/.ghr/github.com/yu-ichiro/ghr
proposal: ~/.ghr/github.com/siketyan/ghr (cloned from yu-ichiro/ghr)

This has some advantages such as:

• being able to distinguish the forked repository by its original owner
• ghr browse will open the original repo (which IMO used more often)

Btw adding upstream to remotes after cloning a fork will be very useful and I was thinking it might be good to release these features together

Support additional patterns other than org/repo

Open repository in the associated application by default

ghr open, ghr init --open, and ghr clone --open requires specifying what application to open currently. When opening the repo in the associated application (i.e. Finder on macOS), we need to specify them as ghr open <repo> open or ghr clone <repo> --open open. It's a little complicated and not easy to understand.

So we need to open repository in the associated app by default, without specifying what app to open. i.e. ghr open <repo> opens the repo in the app.

Execute a command to initialise some stuff

ghr clone siketyan/test --init npm

will run npm i in the repository directory after cloning.
It requires configuration before using the feature.

[initializers.npm]
cd = { cmd = "npm", args = ["i"] }
default = { cmd = "npm", args = ["ci"] }

With the configuration above, ghr will execute npm i after ghr cd, otherwise npm ci.

Listing all managed repositories

Before implementing #7, we need to know what repositories are managed under the ghr root.
We need to walk directories in the root and find all directories matching <host>/<owner>/<repo>.

Bug report: list command does not work

Thanks for a nice tool!

I have a trouble that ghr list command does not work. I'd love to know if you have any solution.

❯ ghr list
error: The subcommand 'list' wasn't recognized

Usage: ghr <COMMAND>

For more information try '--help'

Other commands, such as ghr cd, ghr clone or ghr delete is working as expected.

My environment

OS: macOS Monterey
shell: fish
version:

❯ ghr version
ghr v0.2.2 built with rustc 1.65.0 (897e37553 2022-11-02) at 2022-11-29 03:20:54Z

Bulk apply profiles onto existing repos

Open in not configured application by using `--open` or `ghr open`

We need to configure apps in TOML file before using --open or ghr open, but it would be nice if we can just invoke --open code to run code [path].

Replace lazy_static with std::sync::OnceLock

OnceLock has been stabilised in the std library so we can replace lazy_static with it.

Deleting multiple repos at once

subcommand 'list' does not appear in bash completion

Because list is missing in __ghr_complete(), the list subcommand does not appear as a completion after ghr.

Integrate Kimari DSL

https://github.com/siketyan/kimari

Drop support of config.toml

Follow-up of #31

[feature request] Register unmanaged, existing git repository to ghr

Thanks very much for this great tool! I came up with a idea during using this tool:

Abstract explanation for the requesting feature

Moving repository directories cloned by other methods rather than ghr clone to inside of ghr path by automatically inferring the destination path, and attach profile as same as ghr clone.

# Proposal behavior of the feature

$ git clone https://github.com/owner/repo --depth 1
# snip
$ cd repo
$ pwd
/path/to/random/location/to/repo
$ ghr add . --cd
 INFO This will move this directory to `/home/user/.ghr/owner/repo`.
CHECK Sure you want to add this repository to ghr management? yes
 INFO This directory has been moved an ghr is now managing.
 INFO    -> Attached profile [foo] successfully.
$ pwd
/home/user/.ghr/owner/repo

Motivation for this feature request

Supporting every flags from git by ghr is not practical as mentioned in #36. So instead of / in the mean time of supporting every flags by ghr, it would be more healthy for the both of implementation and UX to delegate cloning job to git and let ghr focus to repository management.

Although user can achieve this feature's behavior by just using mv or specify the destination path when git clone-ing, I think it would be handy if ghr can move the repository without letting user to type repository's remote path/address. And also we can attach profile when this feature is used.

$ git clone https://github.com/owner/repo && mv repo $(ghr path)/github.com/owner/repo
# or 
$ git clone https://github.com/owner/repo && ghr add repo  # this also might be able to apply desired profiles

Implementation consideration

I'm believing ghr can determine the destination where the repository is going to be moved by referring remote's origin (like git remote get-url origin), but this method runs into trouble when there are multiple remotes or the remote's name is not origin. When this occurred user might have to manually type host/owner/repo or select from some candidate generated by ghr (which might kill the benefit of this feature.)

Importing and exporting managed repos in portable format

Cannot clone non-github repository

Is ghr supposed to support non-github repositories? I tried to do

ghr clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

But I get the error

ERROR failed to resolve path '/home/martinus/.ghr/git.kernel.org/pub/scm': No such file or directory; class=Os (2); code=NotFound (-3)

Support fallback to non-secure storage for GitHub OAuth tokens

Depends on siketyan/gh-config-rs#39.

Add a way to assume current directory as a repository managed by ghr

Currently you can't run actions assuming current directory as a repo managed by ghr e.g.

$ pwd
/home/john/.ghr/github.com/john/hoge
$ ghr browse
error: the following required arguments were not provided:
  <REPO>
...
$ ghr browse github.com:john/hoge

It would be convenient to have a assuming feature for actions.

It just came up to me now, but maybe we can use profile apply 's method?

[feature request] Allow muitple default owners to be specified

Thanks very much for this great tool!

Feature explanation

With the default owner feature¹ we can omit the owner name, but currently only single default owner can be specified. If multiple default owners is allowed, it would be convenient for the user who often commits to the project with multiple owners (like personal and company projects).

# Proposal behavior of the feature

$ cd ~/.ghr/ghr.toml
[defaults]
owners = ["owner-1", "owner-2"]

$ ghr list
github.com:owner-1/foo
github.com:owner-2/foo
github.com:owner-2/bar

$ ghr path bar
~/.ghr/github.com/owner-2/bar

# There are two repositories with the name "foo" (owner-1's and owner-2's)
$ ghr path foo
 ERR The path is ambiguous. Please specify the owner name

Implementation/UX consideration

• Configuration scheme can change, so there is an issue with backward compatibility.

Footnotes

1. https://github.com/siketyan/ghr#cloning-a-repository ↩

Add `fork` command

Supersedes #132 and deprecates clone --fork

This command will make the fork process more concise.

1. clone foreign repository
2. fork it on the platform
3. one of the following
   a. rename origin as upstream and add forked repo as origin(names can be changed)
   b. clone the forked repository to another file

`cd`: Add direct shell completion to the default owner

Currently, we can still use the defaults.owner option to cd <repo name>, but shell completion always prompts github.com:<owner>/<repo name>.

So it would be more convenient to use the defauts.owner option to cd directly in completion as well.

Support cloning multiple repositories at once

`--fork` does not wait until the fork is actually completed

panic when pressing <C-l> within the terminal

I'm using macOS and fish shell.

Whenever I just hold Ctrl + l in kitty terminal, I get this error

❯ thread 'main' panicked at library/std/src/io/stdio.rs:1118:9:
failed printing to stdout: Broken pipe (os error 32)
stack backtrace:
   0:        0x104e13340 - <std::sys_common::backtrace::_print::DisplayBacktrace as core::fmt::Display>::fmt::h1f3776e0b5c7517d
   1:        0x104e348d8 - core::fmt::write::heedef092c8c0962e
   2:        0x104e10180 - std::io::Write::write_fmt::h7178e8e2ea928914
   3:        0x104e13198 - std::sys_common::backtrace::print::h417292deb95532ed
   4:        0x104e142f4 - std::panicking::default_hook::{{closure}}::h0cb68f1228c4613a
   5:        0x104e13fe8 - std::panicking::default_hook::h24535936bc1f51de
   6:        0x104e14bac - std::panicking::rust_panic_with_hook::h5db4d2345b297bed
   7:        0x104e145dc - std::panicking::begin_panic_handler::{{closure}}::h3fd558f09a0d5492
   8:        0x104e137c8 - std::sys_common::backtrace::__rust_end_short_backtrace::hfc76eebe1ce501b2
   9:        0x104e1434c - _rust_begin_unwind
  10:        0x104e57f54 - core::panicking::panic_fmt::hc2b459a5bd3dce66
  11:        0x104e0eed8 - std::io::stdio::_print::h64cfa4dfe0b98263
  12:        0x104a59230 - ghr::cmd::shell::Cmd::run::hb8f437acdbdcad84
  13:        0x104a0f46c - ghr::cmd::Cli::run::{{closure}}::hb3c5f839659e0c79
  14:        0x104a093b4 - tokio::runtime::park::CachedParkThread::block_on::h80775a4ea28658f5
  15:        0x1049993bc - ghr::main::hf0b9b03fd605d3e1
  16:        0x104a05240 - std::sys_common::backtrace::__rust_begin_short_backtrace::h4a000ba23e4eb156
  17:        0x1049d63b8 - std::rt::lang_start::{{closure}}::h45b22d0143ace0df
  18:        0x104e0850c - std::rt::lang_start_internal::hecc68fef83c8f44d
  ~                                                                      

Weird panic on fuzzy completion

This only occurs with some of the repositories, but when it occurs, it occurs every time.

thread 'main' panicked at $HOME/.local/share/cargo/registry/src/index.crates.io-6f17d22bba15001f/nucleo-matcher-0.3.1/src/fuzzy_optimal.rs:37:13:
should have been caught by prefilter
stack backtrace:
   0:        0x105076488 - <std::sys_common::backtrace::_print::DisplayBacktrace as core::fmt::Display>::fmt::h1f3776e0b5c7517d
   1:        0x105097a20 - core::fmt::write::heedef092c8c0962e
   2:        0x1050732c8 - std::io::Write::write_fmt::h7178e8e2ea928914
   3:        0x1050762e0 - std::sys_common::backtrace::print::h417292deb95532ed
   4:        0x10507743c - std::panicking::default_hook::{{closure}}::h0cb68f1228c4613a
   5:        0x105077130 - std::panicking::default_hook::h24535936bc1f51de
   6:        0x105077cf4 - std::panicking::rust_panic_with_hook::h5db4d2345b297bed
   7:        0x1050776f8 - std::panicking::begin_panic_handler::{{closure}}::h3fd558f09a0d5492
   8:        0x105076910 - std::sys_common::backtrace::__rust_end_short_backtrace::hfc76eebe1ce501b2
   9:        0x105077494 - _rust_begin_unwind
  10:        0x1050baf50 - core::panicking::panic_fmt::hc2b459a5bd3dce66
  11:        0x104e6cf68 - nucleo_matcher::fuzzy_optimal::<impl nucleo_matcher::Matcher>::fuzzy_match_optimal::h3be38bd3490799cc
  12:        0x104e70258 - nucleo_matcher::Matcher::fuzzy_match::hb708cb05de691d6e
  13:        0x104c0c648 - <core::iter::adapters::map::Map<I,F> as core::iter::traits::iterator::Iterator>::try_fold::h7921be659e350fb9
  14:        0x104c702b4 - <alloc::vec::Vec<T> as alloc::vec::spec_from_iter::SpecFromIter<T,I>>::from_iter::h4a7ecd69ecb74d1d
  15:        0x104c71b20 - ghr::cmd::search::Cmd::run::h8a374f23aa7613e5
  16:        0x104cc32d4 - ghr::cmd::Cli::run::{{closure}}::h79f5f4dc417bed55
  17:        0x104cbce04 - tokio::runtime::park::CachedParkThread::block_on::h642812fa4995ab92
  18:        0x104bffce0 - ghr::main::h602b73b0f5a37cc7
  19:        0x104cb8d38 - std::sys_common::backtrace::__rust_begin_short_backtrace::h6d7f20d7d5b44bb6
  20:        0x104c73d48 - std::rt::lang_start::{{closure}}::h2bb9bbcc50df44d5

I'm gussing it's something related to the naming convention of owner/repo.
Mine occured when I had 3 repositories with the same naming convention

github.com:HogeTeam/hogeapp
github.com:HogeTeam/hoge_payment_gateway
github.com:HogeTeam/hoge-schema

↑ I think this can be reproduced by creating these 3 directories and trying to complete the rest after typing the first 2 letters

$ ghr cd github.com:Ho<TAB> !panic

Support GitLab

This will reveal the true power of ghr, and make an example on how to implement support for different platforms

Open application for the repository directory

Support flags and options for cloning

We need support for flags and options on cloning a repository. e.g. Cloning submodule recursively.

TODO:

• -q / --quiet #144
• -v / --verbose #144
• -n / --no-checkout
• --bare
• --sparse
• --mirror
• -o <name> / --origin <name> #146
• -b <name> / --branch <name> #146
• --depth <depth>
• --single-branch #143
• --no-tags
• --recurse-submodules[=<pathspec>] #145
• -j <n> / --jobs <n>

Options ghr won't support:

• -l / --local
• --no-hardlinks
• -s / --shared
• --dissociate
• --progress
• --server-option=<option>
• --reject-shallow
• --filter=<filter-spec>
• -u <upload-pack> / --upload-pack
• --template=<template-directory>
• -c <key>=<value> / --config <key>=<value> (Already supported in profile)
• --shallow-since=<date>
• --shallow-exclude=<revision>
• --shallow-submodules
• --remote-submodules
• --bundle-uri=<uri>

Shell extensions to change directory into a repository

Search repositories in GitHub using ? token on clone

Use clap_complete to auto generate shell completion

Follow-up of #296

ghr path does not work with patterns

ghr path siketyan # works
ghr path siketyan ghr # works
ghr path --host github.com siketyan ghr # works
ghr path siketyan/ghr # doesn't work
ghr path github.com/siketyan/ghr # doesn't work

Completion for fish shell is not placed under the right place, so not working

https://fishshell.com/docs/current/completions.html#where-to-put-completions

Cloning is not working with fish extension and without --cd

Distribute binaries

Support shell completion on ghr cd / path

Automatically add entries to .git/info/exclude by rules

`clone --fork` does not work?

I'm trying to use the clone --fork feature

Here is what I ran

❯ ghr clone github.com:m4xshen/hardtime.nvim --fork
 INFO Forking from 'https://github.com/m4xshen/hardtime.nvim.git'
ERROR I/O error: No such file or directory (os error 2)

I was kinda expecting that it would fork that into my username yujinyuz/hardtime.nvim.git and clone but nothing seems to happen

Delete repos recursively in a org or a host