diff --git a/README.md b/README.md index 872f436..af4017f 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,16 @@ should), but you don’t want your devs waiting 15 minutes to see if their commit passed. Instead, you want them to wait a few seconds for all that to run locally, maybe in parallel. +You may argue that all these checks should be done automatically by editors +with on-save hooks. But there are a few reasons that often doesn't happen: + +- not all developers know how or bother +- some types of checks are difficult to run automatically, or editors don't + have packages to run such checks +- some checks may be a bit too slow to run frequently in an editor + +So in this regard, Captain takes the onus off all the developers’ editors. + ### Captain’s key features Specifically, here are some of **Captain's features** you don't want to have @@ -141,7 +151,7 @@ to invent, write, and/or wrap around every tool you run: You can think of Captain as like moving your fancy CI setup into everyone’s local control. The output is reminiscent of Github Actions, but way easier to set up, runs automatically whenever you use git, and delivers the red and -green a kajillion times faster. +green a kajillion times faster (aim for not more than a couple seconds). ## Why Captain instead of another hook manager? @@ -170,10 +180,8 @@ Captain also has most of the features of other managers: ## Installation -### Sneaking it in - It’s worth noting that no one needs to know you’ve enlisted the Captain. You -can do all the following and put `capt` to work for just yourself to start out +can do the following steps to put `capt` to work for just yourself to start out with. You’ll commit a `.capt/` dir with some innocuous tiny files and point your own `git` config to use the Captain’s hooks instead of the pedestrian hooks you may have in `.git/hooks`. @@ -276,6 +284,12 @@ a script (or at least a doc) for getting all the tooling installed. It might be just a bunch of dnf/apt-get/pacman/brew commands, or it could even be an ansible file. +## Usage + +The `capt` CLI has a few built-in commands, such as `help`, `edit` (open +editor on control files), `list` (see active hooks), and more. Use `help` to +see them all and their documentation. + ## Control File Spec Now onto the simple `.capt/share.sh` control file at the root of your repo diff --git a/bin/capt b/bin/capt index f6f2fb6..6db4573 100755 --- a/bin/capt +++ b/bin/capt @@ -68,10 +68,10 @@ typeset -A builtin_helps=( ) typeset -A command_helps=( - help 'show help with descriptions of built-in triggers' - list 'list the active hooks' - edit 'open the share.sh control file' - editlocal 'open the local.sh personal control file' + help 'show help with descriptions of built-in triggers' + list 'list the active hooks' + edit 'open the share.sh (and local.sh if exists) control file' + scripts 'list available scripts' ) if [[ $@[1] == 'help' ]]; then @@ -89,11 +89,45 @@ if [[ $@[1] == 'help' ]]; then # print $builtin_helps # print ${builtin_helps[kondo]} print "\nBuilt-in available triggers:" - for b in ${(k)builtin_helps}; do printf ' %-16s%s\n' $b ${builtin_helps[$b]} ; done + for b in ${(k)builtin_helps}; do printf ' %-26s%s\n' "${bold_color}$b$reset_color" ${builtin_helps[$b]} ; done print '\nCommands:' - print " ${bold_color}list$reset_color list of all active hooks" - print " ${bold_color}edit$reset_color see all active triggers in EDITOR" - print " ${bold_color}setup$reset_color initialize captain files into project (idempotent)" + for b in ${(k)command_helps}; do printf ' %-20s%s\n' "${bold_color}$b$reset_color" ${command_helps[$b]} ; done + # print " ${bold_color}list$reset_color list of all active hooks" + # print " ${bold_color}edit$reset_color see all active triggers in EDITOR" + # print " ${bold_color}scripts$reset_color initialize captain files into project (idempotent)" + # print " ${bold_color}setup$reset_color initialize captain files into project (idempotent)" + exit +fi + +list_available_hooks() { + controller=$1 + for h in $( grep -e '^[a-z_]\+=(' $controller | sed -e 's/_/-/g' -e 's/=(//' ); do + print "## $h" + local gf=$captdir/hooks/$h + if [[ -f $gf ]]; then cat $gf; else print ''; fi + print + done +} +if [[ $@[1] == 'list' ]]; then + aye "Active hooks in $captfile: (CAPT_FILE)" + list_available_hooks $captfile + aye "Active hooks in $captfilelocal: (CAPT_LOCALFILE)" + list_available_hooks $captfilelocal + print -- '----' + print "HINT: To see/edit triggers: ${bold_color}capt edit$reset_color" + print "HINT: To see your scripts: ${bold_color}capt scripts$reset_color" + exit +fi + +if [[ $@[1] == 'edit' ]]; then + aye "Opening EDITOR on $captfile $captfilelocal" + $EDITOR $captfile $captfilelocal & + exit +fi + +if [[ $@[1] == 'scripts' ]]; then + aye "Available scripts in $scriptsdir: (CAPT_SCRIPTSDIR)" + ls -1 $scriptsdir exit fi @@ -403,13 +437,13 @@ run_scripts () { else aye "$fg[red]WARNING: Skippin on yer $print_name; $cmd0 and $script be lost at sea.$reset_color" fi es=$? - [[ -n $CAPT_VERBOSE ]] && print -- "$output" + [[ -n $CAPT_VERBOSE && -n $output ]] && print -- "$output" wait # don't process until background scripts are finished tfinal=$(( $(sdate +%s%3N) - $t0 )) units=ms units_color=white if (( 1000 < $tfinal )); then tfinal=$(( $tfinal / 1000 )); units=s; units_color=red; fi # Bail out on whole run if any script not successful if [[ $es -ne 0 && ! -v failok ]]; then - print + [[ -z $CAPT_VERBOSE ]] && print "\nFAIL: $output" # print "$fg[red] ⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⣤⣤⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀" # print "$fg[red] ⠀⠀⠀⠀⠀⢀⣴⣿⣿⣿⡿⢿⣿⣿⣿⣷⣄⠀⠀⠀⠀⠀" # print "$fg[red] ⠀⣠⣤⣶⣶⣿⣿⣿⣿⣯⠀⠀⣽⣿⣿⣿⣿⣷⣶⣤⣄⠀" @@ -423,7 +457,7 @@ run_scripts () { # print "$fg[red] ⠀⠀⠀⠀⢻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠀⠀⠀⠀Status: $es" # print "$fg[red] ⠀⠀⠀⠀⠈⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀" # print "$fg[red] ⠀⠀⠀⠀⠀⠀⠀⠈⠉⠛⠛⠛⠛⠋⠉⠀⠀⠀⠀⠀⠀⠀" - print "$fg[red] "'\\\\' + print "\n$fg[red] "'\\\\' print "$fg[red] (o> Down to Davey Jones’ locker!" print "$fg[red] ___(()___ Status $es" print "$fg[red] ||"