3 releases (stable)

1.1.0 Nov 5, 2024
1.0.0 Dec 20, 2023
0.1.0 Dec 16, 2023

#189 in Web programming

Download history 5/week @ 2024-07-27 5/week @ 2024-09-21 115/week @ 2024-11-02 14/week @ 2024-11-09

129 downloads per month

MIT license

15KB
154 lines

Ghl

Github Linker

This program lets you get all sorts of github links using the information contained in your local repo.

Want to just get the link to your github repo? Just ghl

If you also want to open it in your $BROWSER, add the --web / -w flag.

For this to work, you'll have to export the variable to your preferred browser in your shell. Something like xdg-open isn't used for this to help the program be more cross-platform.

You can specify a path to a certain file / directory in your repo. Relative paths (..) work!

In the middle of the link, you'll see either tree or blob. It's the former if the file you're pointing to is a directory, and the latter if it is not. To figure this out, the path you provide is resolved to the real path. This includes some restrictions:

  1. The path has to exist. You can't refer to a file that used to exist in a certain commit, but doesn't anymore.
  2. Symlinks are resolved to their target. So, you won't be able to make a link to a symlink.

In those situations, you'll have to use the --connector / -c flag to specify tree or blob yourself. Keep in mind though, that at that point the provided path isn't resolved, so it assumes you're specifying a path relative to the repo root.

Another --connector that's available is commit: this (I think) doesn't make any sense to use with a path, and is useful for when you want a link pointing directly at some commit's diff.

The default link goes to the default branch, latest commit, as you would expect. However, you can specify a different branch / commit you want to get a link to with the --branch / -b flag. Something like -b dev or -b 18e5a52.

That flag takes your input literally, however these features are available:

  1. HEAD means current commit (you can also specify head in lowercase). Notice that the difference from the default behavior is that it points to the commit you're currently on, not the latest available commit that will exist in the future.
  2. head^ to mean "commit before the current one"
  3. head~6 to mean "6 commits before the current one"
  4. dev to mean "the current latest commit of branch called dev"
  5. 18e5a52 to expand the short commit hash to the full commit hash

To get these features, use the --parse / -p flag together with the -b flag. This is not the default because:

  1. Specifying a branch name would resolve to its current latest commit, rather than the latest available commit
  2. You wouldn't be able to refer to a branch that doesn't exist locally

If your repository is a fork, by default you'll get a link to your repo, the fork. More precisely, the link to the first remote from the list of git remote is taken. If you want to build a link to your upstream, you can specify the remote name with the --remote / -r flag (usually would be -r upstream).

Did you ever find it annoying how some programs unecessarily print the final newline after its output? No? Just me? Well, you can trim it with the --trim / -t flag.

Other remotes, aside from Github

While this program was made for Github specifically, it can technically work for other remotes too, considering these assumptions:

  1. You're using git / git-compatible VCS
  2. After the repository name in the link, you have tree if you're pointing to a directory (or a branch if you didn't specify a filepath) and blob if you're not.
  3. After tree / blob goes the branch name, or commit hash
  4. The filepath comes after those

Usage

An easier way to construct Github links.

Usage: ghl [OPTIONS] [PATH]

Arguments:
  [PATH]  

Options:
  -b, --branch <BRANCH>   Make a link to a specific branch / commit. Branch is not specified by default, which
                          results in making the link follow the default branch
  -p, --parse             Parse `branch` argument with `git rev-parse`. This allows you to use things like HEAD
                          (or just head), HEAD^, commit~2; short commit hashes become long commit hashes, branch
                          names become their latest commit's hash. Essentially, everything that happens when you
                          use `git rev-parse`. This is not the default because you couldn't specify links to
                          branches that way, and would only be able to specify links to a branch's latest commit
  -r, --remote <REMOTE>   Specify remote name explicitly. By default, takes the first one from `git remote`. If
                          your repo is a fork, this will result in a link to *your* repository, rather than the
                          upstream one. You can specify `upstream` (usually) to mean the upstream repository
  -t, --trim              Trim the final newline of the output link
  -w, --web               Open the resulting link in your $BROWSER
  -c, --connector <WORD>  Assume the provided filepath is literal and is relative to the repo root, and provide
                          the connector type yourself. `tree` if you're pointing to a directory, `blob` if not.
                          Useful when you're trying to point to a symlink, rather than the file it points to, or
                          if you're pointing to a file you know is going to be in the remote but not locally.
                          This is required when you're specifying a file that no longer exists, but did in some
                          commit. `commit` is also available if you just want to point at a commit's diff,
                          rather than a filepath [possible values: blob, tree, commit]
  -h, --help              Print help
  -V, --version           Print version

Examples

$ ghl
https://github.com/Axlefublr/ghl
$ ghl -b main
https://github.com/Axlefublr/ghl/tree/main
$ ghl -b main src/main.rs
https://github.com/Axlefublr/ghl/blob/main/src/main.rs
$ ghl -pb head src/main.rs
https://github.com/Axlefublr/ghl/blob/b9b2d5ae285db97b6de3aa542e29a8987bf9e76a/src/main.rs
$ ghl -pb b9b2~2
https://github.com/Axlefublr/ghl/tree/3c3de7dd17e00fea563bb09598b2671da09ecbd4
$ ghl -wb dev src
https://github.com/Axlefublr/ghl/tree/dev/src
$ ghl -pb head -c commit
https://github.com/Axlefublr/ghl/commit/46974897532f68e1b9e234d4640d485ac6d768c4
$ ghl -pb 3c3de7dd17e0 -c commit
https://github.com/Axlefublr/ghl/commit/3c3de7dd17e00fea563bb09598b2671da09ecbd4

Install

cargo install ghl

cargo-binstall and cargo-quickinstall are also supported.

Uninstall

cargo uninstall ghl

Dependencies

~3–11MB
~141K SLoC