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
129 downloads per month
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:
- The path has to exist. You can't refer to a file that used to exist in a certain commit, but doesn't anymore.
- 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:
HEAD
means current commit (you can also specifyhead
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.head^
to mean "commit before the current one"head~6
to mean "6 commits before the current one"dev
to mean "the current latest commit of branch calleddev
"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:
- Specifying a branch name would resolve to its current latest commit, rather than the latest available commit
- 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:
- You're using git / git-compatible VCS
- 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) andblob
if you're not. - After
tree
/blob
goes the branch name, or commit hash - 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