docs(koji): update docs for webi users as target audience

koji/README.md

@@ -7,74 +7,102 @@ tagline: |
 
 To update or switch versions, run `webi koji@stable` (or `@v2`, `@beta`, etc).
 
-**Note**: You should install git before installing koji.
+**Note**: You should install [git](/git) before installing koji.
 
-## Files
+## Cheat Sheet
+
+> `koji` is an interactive CLI for creating [conventional commits][cc].
+
+![](https://github.com/its-danny/koji/raw/main/meta/demo.gif)
+
+[cc]: https://conventionalcommits.org/en/v1.0.0/
+
+You can use koji in one of two ways:
+
+1. `koji` instead of `git commit`
+2. `koji --hook` in `./.git/hooks/prepare-commit-msg` \
+   (to be run by `git commit`)
+
+Here's the shortlist of options we've found most useful:
+
+```txt
+-e, --emoji - use emoji for commit type (ex: `✨ feat:`)
+-a, --autocomplete - guess 'scope' based on commit history (slow on large projects)
+--hook - expect to be run from 'git commit', rather than wrap it
+```
+
+### Files
 
 These are the files that are created and/or modified with this installer:
 
-```
+```bash
 ~/.config/envman/PATH.env
 ~/.local/bin/koji
 ~/.local/opt/koji-VERSION/bin/koji
 ```
 
-## Cheat Sheet
+### How to use koji (standalone)
 
-`koji` is an interactive CLI for creating
-[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/), ran in
-place of `git commit`.
-
-### Using koji
+In this case, `koji` acts as a wrapper around `git commit`:
 
 ```bash
-cd dev/work-stuff
-# Do some work
-cd dev/work-stuff
-git add .env.production
+git add example.env
 
-# Create a conventional commit with koji
-# in place of `git commmit`
+# same as `git commit`, but interactive
 koji
 ```
 
-### With emoji
+### How to use koji as a commit hook
 
-Passing `-e` or `--emoji` to `koji` will prepend your commit message with an
-emoji related to the commit type. The default emoji can be seen
-[here](https://github.com/its-danny/koji/blob/main/meta/config/koji-default.toml).
+Just add `koji --hook` to your project's `.git/hooks/prepare-commit-msg`:
 
-You can also use shortcodes (`:pinched_fingers:`) in the scope, summary, or
+```bash
+echo >> ./.git/hooks/prepare-commit-msg << "EOF"
+#!/bin/bash
+koji --hook
+EOF
+
+chmod a+x ./.git/hooks/prepare-commit-msg
+```
+
+```bash
+# will run koji by way of prepare-commit-msg
+git commit
+```
+
+### How to use Emoji
+
+You can use `-e` (or `--emoji`) to prepend your commit message with the relevant
+emoji for the commit type:
+
+```bash
+koji -e
+```
+
+As a git hook:
+
+`.git/hooks/prepare-commit-msg`:
+
+```bash
+#!/bin/bash
+koji --emoji --hook
+```
+
+You can also use _shortcodes_ (`:pinched_fingers:`) in the scope, summary, or
 body.
 
-### Autocomplete
+### How to configure Koji (custom emoji)
 
-Passing `-a` or `--autocomplete` to `koji` will enable autocomplete for the
-scope prompt. This scans your commit history to collect previous scopes, so it
-does slow down the startup a bit.
+You can add custom commit types via a `koji.toml` in the project directory.
 
-For reference, ran inside the [angular](https://github.com/angular/angular) repo
-with 22k commits:
-
-```
-koji      0.00s
-koji -a   0.40s
-```
-
-### As a git hook
-
-If you're using [rusty-hook](https://github.com/swellaby/rusty-hook), set this
-in your `.rusty-hook.toml` file.
+For example:
 
 ```toml
-prepare-commit-msg = "koji --hook"
+[[commit_types]]
+name = "feat"
+emoji = "✨"
+description = "A new feature"
 ```
 
-Similar should work for any hook runner, just make sure you're using it with the
-`prepare-commit-msg` hook as it writes the commit message to `COMMIT_EDITMSG`.
-
-### Use custom commit types
-
-You can add custom commit types via a `koji.toml` file in the working directory.
-Some examples can be found
-[here](https://github.com/its-danny/koji/blob/main/meta/config).
+The default emoji can be seen in
+[koji-default.toml](https://github.com/its-danny/koji/blob/main/meta/config/koji-default.toml).