ohmyksh/README.org

#+TITLE: ohmyksh

** About
Have your cake and eat it too!

~ohmyksh~ is a framework for expanding OpenBSD's [[https://man.openbsd.org/ksh][ksh]]. It offers:

- completions :: for common things like [[https://man.openbsd.org/man][man]] pages, [[https://man.openbsd.org/ssh][ssh]] ~known_hosts~ and ~git~ (and
 ~got~!) commands. 
- extensions :: to import bulk functionality, including git-prompt, OpenBSD
  specific tooling, disabling color.. etc. 
- prompts :: a decent selection of useful, minimal prompts.
  

** Completions

| Name   | Completes                              |
|--------+----------------------------------------|
| [[file:completions/git.org][git]]    | add, fetch...                          |
| [[file:completions/got.org][got]]    | add, blame...                          |
| [[file:completions/gopass.org][gopass]] | audit, config...                       |
| [[file:completions/man.org][man]]    | man pages                              |
| [[file:completions/mpc.org][mpc]]    | play, load, toggle...                  |
| [[file:completions/rc.org][rc]]     | OpenBSD rc scripts and rc commands     |
| [[file:completions/ssh.org][ssh]]    | ssh known hosts                        |
| [[file:completions/vmd.org][vmd]]    | vmctl commands and VM names            |
| [[file:completions/ogvt.org][ogvt]]   | reminders for ogvt (-pub, -sig, -file) |

** Extensions

| Name       | Description                                                  |
|------------+--------------------------------------------------------------|
| [[file:extensions/fonts.org][fonts]]      | Load fonts from common locations.                            |
| [[file:extensions/fzf.org][fzf]]        | -                                                            |
| [[file:extensions/git-prompt.org][git-prompt]] | A port of git-prompt for KSH.                                |
| [[file:extensions/got.org][got]]        | Adds PS1 support for got, as well as a few helper functions. |
| [[file:extensions/k.org][k]]          | A tool to quickly change directories.                        |
| [[file:extensions/keychain.org][keychain]]   | Wrapper for [[https://www.funtoo.org/Keychain][Funtoo's Keychain]] utility.                       |
| [[file:extensions/nocolor.org][nocolor]]    | Disable terminal color options for many tools.               |
| [[file:extensions/openbsd.org][openbsd]]    | A set of tools for working with the OpenBSD source trees.    |
| [[file:extensions/pkgup.org][pkgup]]      | Utility to speed up OpenBSD' [[https://man.openbsd.org/pkg_add][pkg_add(1)]].                     |


** Prompts

| Name       | Example                       | Extensions used |
|------------+-------------------------------+-----------------|
| [[file:prompts/q.org][q]]          | ~qbit@litr[0]:~$~             | git-prompt, got |
| [[file:prompts/plain.org][plain]]      | ~litr:~/src/ohmyksh/prompts$~ | -               |
| [[file:prompts/og-openbsd.org][og-openbsd]] | ~$~                           | -               |
| [[file:prompts/9.org][9]]          | ~%~                           | -               |

** Example usage

#+begin_src shell
  # ohmyksh needs to know where it lives, so we tell it via this env var:
  OHMYKSH_DIR=${HOME}/src/ohmyksh

  # Now we can load everything up!
  . ${OHMYKSH_DIR}/ohmy.ksh

  # All the paths we use (in order!)
  set -A my_paths -- \
          /usr/ports/infrastructure/bin \
          ~/bin \
          ~/go/bin \
          /usr/local/plan9/bin

  paths "${my_paths[@]}"

  # Load our various extensions
  load_extension fonts
  load_extension k
  load_extension nocolor
  load_extension openbsd

  # Load handy completions for various things
  load_completion ssh
  load_completion vmd
  load_completion rc
  load_completion gopass
  load_completion git

  alias vi=vim

  # the q prompt auto-loads the git-prompt extension
  set_prompt q
#+end_src

** Contributing

Contributions can be sent in via Github PRs or via emailing a patch to
[[~qbit/ohmyksh@lists.sr.ht][~qbit/ohmyksh@lists.sr.ht]].

If you do send in a contribution, please include a .org file which describes the
feature set. The org syntax is available [[https://orgmode.org/quickstart.html][here]], however, one will likely be able
to just copy an existing file and modify it.