diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..45e8793 --- /dev/null +++ b/README.md @@ -0,0 +1,116 @@ +## `qroject` + +a project switcher tool. + +this has both `qroject`, the standalone binary, and [Bash loadable +builtins](https://cgit.git.savannah.gnu.org/cgit/bash.git/tree/examples/loadables/README?h=bash-5.1) +to mildly-better integrate the tool into normal shell use. + +## usage + +no nice packaging story yet, so instead there's a bit of get-out-and-push: + +* clone this repo, build with a nightly Rust like `cargo +nightly build --release -Z build-std`. +* put `libqroject_bash.so` somewhere you want to load a shared object from. +* add the snippets from `q.sh` to your `~/.profile`, `~/.bash_profile`, whichever is appropriate. +* adjust `enable -f ` to include a path to wherever you've stashed `libqroject_bash.so`. + +defaults are such that `libqroject_bash.so` is loaded directly from the +`qroject` build directory. this is not particularly clean or a great idea. + +once that's done, a whirlwind tour: + +``` +iximeow@vitharr:~$ qg rust +iximeow@vitharr:~/code/rust-lang/rust/$ qg yaxpeax-x86 +iximeow@vitharr:~/toy/yaxpeax/arch/x86$ ls $(qd yaxpeax-x86) +build.rs Cargo.toml data fuzz LICENSE perf.data src test +Cargo.lock CHANGELOG ffi goodfile Makefile README.md target TODO +iximeow@vitharr:~/toy/yaxpeax/arch/x86$ cd - +-bash: cd: OLDPWD not set +iximeow@vitharr:~/toy/yaxpeax/arch/x86$ qg rust +iximeow@vitharr:~/code/rust-lang/rust/$ ls $(qd yaxpeax-x86) +iximeow@vitharr:~/code/rust-lang/rust/$ head -n 1 $(qd yaxpeax-x86)/README.md +## yaxpeax-x86 +iximeow@vitharr:~/code/rust-lang/rust/$ q list perf +perf/zen4-zen5-branch-predictor +iximeow@vitharr:~/code/rust-lang/rust/$ q list lin +linux +iximeow@vitharr:~/code/rust-lang/rust/$ q add cgit ~/code/cgit +iximeow@vitharr:~/code/rust-lang/rust/$ qg cgit +iximeow@vitharr:~/code/cgit$ +iximeow@vitharr:~/code/cgit$ qg oxide/images +(root@helios) Password: +root@helios:/rpool/devel/images# +``` + +and from the non-plugin binary: + +``` +Usage: qroject [OPTIONS] <COMMAND> + +Commands: + init initialize a qroject database. you should run this first, and shouldn't need to again + add add a project to the qroject database. projects are unique by their name + forget forget a project of the given name + dir print the directory for the given project + info print information about the given project + upstream print the project's upstream, if any + edit edit `project`'s record + list list all known projects (optionally, with details) + help Print this message or the help of the given subcommand(s) + +Options: + --db <DB> + -h, --help Print help + -V, --version Print version +``` + +## related + +this is something i've had kicking around in my head for years, but at least a +few other similar programs exist: + +* [z.sh](https://github.com/rupa/z) or [`zsh-z`](https://github.com/agkozak/zsh-z) +* [zoxide](https://github.com/ajeetdsouza/zoxide) +* [fzf](https://github.com/junegunn/fzf) kinda sorta + +unlike these tools, qroject is oriented specifically towards a curated set of +working directories and supporting information. this makes it unsuitable for +finding miscellaneous paths in deep mirrors, for example, but perhaps better for +figuring out "where did i put those notes from three years ago" (it is to me!) + +## todo + +project-specific aliases and commands are useful to me, and typically live in +random gitignored directories like `<proj>/.ixi/tools/foo.sh`. at some point, +with sufficient motivation, i want to move these to be tracked as part of a +qroject definition, or at the least load aliases from these files. + +this is either good or bad: activating and deactivating aliases will require +patching the shell's `chdir()` to intercept calls (such as from `q go`!). it +will involve activating alises possibly from repositories cloned from the +internet authored by totally untrusted parties. qroject should not allow such +repos to result in aliases over, say, `git` or `make` to evil ends. + +there will probably be public-key cryptography invovled. sorry. + +## mirrors + +the canonical copy of `qroject` is at +[https://git.iximeow.net/qroject/](https://git.iximeow.net/qroject/). + +`qroject` is also mirrored on Codeberg at +[https://www.codeberg.org/iximeow/qroject](https://www.codeberg.org/iximeow/qroject). + +## shoutouts + +huge thanks to internet user [Ayose C.](https://github.com/ayosec) for +[bash-builtins.rs](https://github.com/ayosec/bash-builtins.rs). this is in fact +how i discovered that bash loadable plugins *even exist*. + +i was initially going to do something moderately less useful as a [multi-call +binary](https://flameeyes.blog/2009/10/19/multicall-binaries/), and started +looking at dynamically patching the `qroject`-caller's shell to change the +caller's `chdir()`. rest assured that `qroject` has not developed any devious +binary-patching nonsense. |