{"binary":false,"name":"README","content":"\n bar -- BAshRulez the bash rule evaluator\n\nABOUT\n\n Bar is a command runner that determines the order of commands and which ones to run, based\n on rules. It lets the user define rules that dependently and conditionally evaluate shell\n statements. This is similar to other tools such as 'make' or 'just' but adds some\n opinionated differences. There is support for using bar as driver for githooks for\n automating workflows.\n\n The notable differences to other similar tools are:\n\n * First and foremost, bar is *not* a build tool. It is a engine that makes shell scripting\n declarative. Writing rules is much more descriptive than branching in a lot if/else\n statements and it optimizes better as well.\n * Batteries included! bar comes with ready to use modules, they vendor themself on first use.\n * Rule targets and dependencies are commands; not artifacts like files/timestamps.\n * Rules in bar can have multiple clauses.\n * By default rules are conjunctive, when a clause of a rule fails then the rule fails and\n not further evaluated.\n * Rules can be made disjunctive, then a rule succeeds on the first succeeding clause.\n * Clauses can be conditionally skipped.\n * The results of rules are cached. They are evaluated only once, although there is\n a form to define rules that always evaluate.\n * We have a module that can memorize commands persistently and schedule evaluation to the\n background. A later instance can pick up the results from this background evaluation.\n * Deliberately implemented in bash, bar is meant to be vendored into any project using it,\n it has very modest dependencies and should run anywhere you have a unix like userland with\n bash and a few common tools available.\n * Hackable, being veondored into your project means you can modify and edit everything to\n your needs.\n\n When you read this because you have seen 'bar' or '.bar' used in a repository then you may\n look at INITIAL INSTALLATION below.\n\n\nQUICKSTART\n\n When you cloned a project that uses bar then you can:\n\n ./bar # just runs whatever the maintainer decided as default\n ./bar watch # watches the project for changes and runs the default\n ./bar watch fastchk # watches the project for changes and runs fast checks\n ./bar activate # installs githooks and other local prep work\n\n When you want to install and use it in your own projects:\n\n git clone https://seed.pipapo.org/z3WhBdHt1VVNyeQ61zpY66pNzuSrP.git bar\n cd bar\n ./bar init_install ~/.local/\n git pull # to get updates\n\n Then you can initialize it in your projects with:\n\n bar init\n git add Barf Bar.d .gitignore\n git commit -m 'start using bar'\n\n bar init_update # for updating the version stored in the project\n\n The second personality of bar is 'makeitso' eg.:\n\n makeitso wake # sends a wake-on-lan packet to a host\n makeitso suspend # remotely sends a host to suspend-to-ram\n\n Buildin help system:\n\n bar help [topic]\n ./bar help [topic]\n\n A rule file may be written in a syntax close to makefiles and justfiles, see RULE FILE\n PREPROCESSOR below.\n\n\nINVOCATION AND SEMANTICS\n\n bar [rulefile] [--bare] [rule [arguments..]]\n makeitso [rulefile] [--bare] [rule [arguments..]]\n ./bar [rulefile] [--bare] [rule [arguments..]]\n [arguments..]\n\n Starts by loading all initial modules (those which have underscores in their name) and the\n rulefile, which is either \"Barf\", \"barf\", \".Barf\", \".barf\" when called as 'bar' or \"Makeitsof\"\n \"makeitsof\" \".Makeitsof\" \".makeitsof\" \"$HOME/.Makeitsof\" when called as 'makeitso' and when the first\n argument is not a file.\n\n The duality of having 'bar' installed as 'makeitso' is not only for making it more\n polite. This allows for a user to have private '.Makeitsof' defining rules that are for common\n administration tasks distinct from versioned per-project 'Barf' and 'Bar.d' rules.\n\n Note that the rules for looking up the Barf/Makeitsof and the modules are somewhat distinct.\n Nevertheless modules are in either way only loaded from a single directory and are not\n located in different paths. This is a opinionated choice to make the module system\n self-contained and not depend on secondary locations.\n\n That single directory is the closest rule directory ('Bar.d', 'bar.d', '.Bar.d' or '.bar.d')\n in the current directory or, walking upwards, in an ancestor of it. The walk stops at the\n filesystem boundary unless '$BAR_CROSS_FS' is set, and at a git repository which carries no\n rule directory unless '$BAR_CROSS_REPO' is set: such a repository is a project of its own, and\n its rulefile, state and logs belong below it, never to an ancestor. When no rule directory\n exists, the modules installed below '$BAR_PREFIX' are used; at the root of a git repository the\n modules beside the running 'bar' serve instead, so a source tree can initialize a project\n without being installed ('/bar' with '/Bar.d'). '$BAR_TOPLEVEL' stays the\n directory bar was invoked from: it is the directory that holds the rule directory, and the\n rulefile lookup and everything else bar keeps in the project (the memodb state, run logs)\n resolves below it, never below an ancestor or the filesystem root.\n\n Then the given rule (or MAIN) with the supplied arguments becomes evaluated. Finally, if\n a 'CLEANUP' rule exists, it is evaluated.\n\n The exit code of the invocation is the exit code of the main rule.\n\n Just calling 'bar' without any arguments will evaluate the 'MAIN' rule which should be what\n people expect by default. Other useful rules like 'help' for this documentation are defined\n by modules.\n\n When called by a symlink, the standard rulefile is loaded and instead of ‘MAIN’, a rule with\n the same name as the symlink is called with all arguments passed.\n\n\nINITIAL INSTALLATION\n\n Bar can be invoked in different ways:\n\n 1. Installed in $PATH:\n To make this work it is best to clone bar locally and symlink the checked out files\n to your '.local/' tree. This allows easy upgrades via git:\n\n When you have radicle (https://radicle.xyz/) installed you can clone it with:\n\n rad clone rad:z3WhBdHt1VVNyeQ61zpY66pNzuSrP\n\n Otherwise it can be cloned by git with:\n\n git clone https://seed.pipapo.org/z3WhBdHt1VVNyeQ61zpY66pNzuSrP.git bar\n\n Then you can install it in your ~/.local tree with:\n\n cd bar\n ./bar init_install ~/.local/\n\n This creates symlinks to 'bar', 'makeitso', 'Bar.d', 'Barf.default', 'Makeitso.default' in ~/.local\n and symlinks 'Bar.d/*' to '~/.config/makeitso/'. Existing symlinks are left untouched and only\n the ones for modules which are not linked yet are added, so a module which was added to\n 'Bar.d/' later becomes reachable by running 'init_install' again (no manual symlink needed).\n\n Now 'bar' is installed, check it with 'bar help'\n\n 2. The local './bar' initialized from above:\n Since bar is a bash script, it’s easy to version and ship it with other software.\n To initialize it in a current directory use either of:\n\n bar init # creates bar, Barf, Bar.d/\n bar init --hidden # creates .bar, .Barf, .Bar.d/\n\n This installs the modules bar needs at startup and then completes 'Bar.d/' from the installed\n 'Barf' ('bar init_deps'). With 'bar init --no-install-deps' that last step is left out, so\n the 'Barf' can be customized first: 'bar init_deps' afterwards vendors the modules the\n edited 'Barf' names.\n\n After that Barf can be customized, unnecessary modules in Bar.d/ may be deleted ('bar\n modules_prune' deletes the ones which are still unmodified copies of the installed ones and\n completes the tree again). Once that is done these files should be put under version\n control.\n\n When the installed bar from 1. becomes updated then a local version can be updated by:\n\n bar init --update\n\n This only updates 'bar' and any existing modules in 'Bar.d/' but will not touch the\n 'Barf' file since that is meant for local customization.\n\n bar init_update_merge_barf\n\n Will do a merge of the installed 'Barf' file with the local one. This *will* leave 3-way\n conflict markers behind when there are changes. These must be manually resolved!\n\n The updated files should then be committed to version control.\n\n 3. githooks symlinked from './.git/hooks/*' -> '../../bar'\n 'bar' has support to be used as githooks. This needs manual enabling. Individual hooks can be\n enabled or disabled with 'bar githook_enable ' and 'bar githook_disable '.\n For existing projects using 'bar' a maintainer can setup rules to activate all necessary hooks.\n This then can be activated by './bar activate'.\n\n\nGIT HOOK ACTIVATION\n\n Bar will be inert in a project that ships with bar initialized. One can call it manually by\n './bar'. A maintainer of the project may define 'activate' rules that activate\n githooks. These are then activated by './bar activate'. This will create symlinks in the\n '.git/hooks/' directory to the 'bar' script. These hooks will then be executed when the\n respective git hook is triggered. The rules for these hooks are defined in the 'Barf' file\n in the project directory.\n\n\nRULE SEMANTICS\n\n Rules are a named, ordered collection of clauses. They are considered pure with inputs being\n the current directory name and the rule's arguments. Note that the content of files is *not*\n considered and the outcome of the rule should not depend on external variables. Rules are\n evaluated lazily, only once; the result of a rule is cached. This means that rules, esp. the\n actions within the body must have deterministic sematics. For performance reasons this is\n not enforced but one may observe surprising behavior when this requirement is violated.\n\n Rules will be autoloaded on demand from modules in 'Bar.d/' (see below AUTOMATIC MODULE\n LOADING). For rules where this fails a fallback exits that creates an implicit rule for any\n command and shell function defined with a body calling the respective command.\n\n Each clause in a rule has its own set of dependencies. Dependencies are other rules which\n are evaluated in order. When a (normal) dependency fails then rule it is considered to be\n failed as well and no further attempts to evaluate following dependencies and clauses are\n made.\n\n Dependencies can be used as 'checking' dependency which either expects the dependency to\n succeed (suffixed with a '?') or fail (prefixed with a '!'). When such a checking dependency\n fails then the rest of the current clause is skipped. This allows conditional evaluation.\n Further dependencies may be tagged as unconditional by suffix them when a tilde '~', these\n are just evaluated but rules evaluation will proceed unconditionally even if such a\n dependency fails.\n\n Finally every clause can have an optional body. This are shell commands executed when all\n dependencies succeeded. Because of quotiung in shell becomes a but unwieldly there are\n shortcuts to make the body refer to shell functions, this should be preferred.\n\n\nRULE SYNTAX\n\n A rule file, the 'Barf' and every module in 'Bar.d/', may be written in a syntax close to\n the one of makefiles and justfiles. 'bar' runs a preprocessor over it which expands that syntax\n into the 'rule' statements of RULE DEFINITION SYNTAX below and passes every other line through\n unchanged: it never refuses a line, what it does not know is reported by the parser, at the line\n it is on. Both syntaxes may be mixed in one file, and for a rule file you write this is the\n preferred one: 'rule' is the plain form it expands to, for what it cannot express.\n 'bar preprocess ' prints the text which gets sourced.\n\n : .. rule : ..\n [].. attached to the next header\n : [].. .. rule : --.. ..\n : .. ; rule : .. -- \n : an indented block below is the body\n : ( ..) one dependency, quoted, arguments included\n : .. [=].. rule : .. 'clause_local [=]..' ..\n := =\n ?= : \"${:=}\"\n\n * A header is a line which starts at column 0 with a name and a colon. Indented lines,\n heredoc bodies and multi line quoted strings are never touched.\n\n * '[]..' are stacked lines at column 0, each a '--rule-flag' of RULE DEFINITION\n SYNTAX without the dashes. They attach to the next header. They are printed as comments\n ('# [always]'): the flags travel on the rule line, and one line in stays one line out, so a\n parse error names the line of the file.\n\n * '[]..' after the colon are the '--clause-flag' of RULE DEFINITION SYNTAX\n without the dashes, brackets stack.\n\n * '; ' ends the dependencies, everything behind it is the clause body.\n\n * The body of an indented block is the block's text: the indentation of its first line is\n stripped from all its lines, blank lines belong to it, and it ends at the first non blank\n line indented less.\n\n * A run of variable definitions among the dependencies is one dependency 'clause_local' which\n carries the run: '=' makes the variable local to the clause with that value,\n '=' with the empty one, and '=' with the value the outer scope has. Two runs are\n never coalesced, the order is kept, and a run ends at the first word which is no definition.\n\n * '( ..)' is one dependency which carries arguments. Modifiers written outside the\n parentheses are lifted onto it, '!(dep arg)' is the dependency '!dep arg'. Parentheses may\n nest and inner quoting is kept as written.\n\n * 'NAME := value' assigns a variable, 'NAME ?= value' assigns it only when it is unset or\n empty.\n\n * Shellcheck checks a module and a rule file through this preprocessor ('bar_lint'), so the\n make/just syntax is not reported as a syntax error and only genuine shell defects are.\n\n * One filter serves a whole 'bar' invocation and is handed one file at a time: a file expands to\n what it expands to alone, never depending on the files before it.\n\n\n Examples:\n\n # Different ways to define rule bodies\n foo_ok: ; echo inline\n foo_ok:\n echo indented\n\n foo_ok: -- <<<\"echo herestring\"\n foo_ok: -- <:] [--clause-flag].. [[+][!]deps[?|~][??] args..]..\n rule [[--rule-flag].. :] [--clause-flag].. [[+][!]deps[?|~][??] args..].. -\n rule [[--rule-flag].. :] [--clause-flag].. [[+][!]deps[?|~][??] args..].. -- [body..]\n\n * [--rule-flag]\n\n Sets flags for a rule. Flags are additive and affect the rule, not single clauses.\n\n --always\n The result is not cached and the rule will be always evaluated again.\n\n --bare\n When this rule is called as initial rule (bar ) then do not eval SETUP,\n PREPROCESS, POSTPROCESS and CLEANUP.\n\n --reverse\n The clauses of this rule will be evaluated in reverse order\n\n --disjunct\n Makes the clauses of this rule disjunctive. The rule will succeed with the first\n successful clause. Normally clauses are conjunctive and fail with the first failing\n clause.\n\n --meta\n Metarules do not have their own clause local variable. This allow them to modify\n the clause locals of the calling rule. 'clause_local' for example is a metarule.\n User defined rules that want to modify clause locals will need to be meta too.\n See 'try_cargo_toolchain' for an example.\n\n --parallel\n Every clause of this rule is evaluated as if it were marked '--parallel' (see the clause\n flags below), and the dependencies of all its clauses are started at the first of them, so\n the rule costs its slowest dependency rather than their sum. The clause bodies still run\n in the shell of the rule and in declared order: a body works in the directory and may rely\n on what the body before it did. Opt-out: a clause marked '--conclusive' or '--default'\n stays serial. A '--disjunct' rule keeps its clauses in order -- which clause is tried first\n is its meaning -- and inherits the flag per clause instead.\n\n * [:]\n\n A rule can have a optional name (suffixed with a colon). When the name is not given it\n defaults to 'MAIN'. Rules that have only a name but no dependencies and no body create a\n body that calls a bash command or function with the same name as the rule passing rule\n arguments to it.\n\n * [--clause-flag]..\n\n Sets flags affecting this clause only.\n\n --conclusive\n Makes a clause result conclusive, if not skipped no more clauses will be tried.\n\n --default\n Default clauses will be kept at the end of the list of clauses. Using '--default'\n together with 'disjunct' rules allows one to hook up action while maintaining a fallback\n or warning/error when no hooked up rule succeeded.\n\n --parallel\n Every dependency of this clause which is not a conditional one may be started early, as if\n it were prefixed with '+'. Opting out is per clause, so the rule flag '--parallel' sets\n this for every clause but the '--conclusive' and '--default' ones. See the dependency\n rules below.\n\n * [[+][!]deps[?|~][??] args..]..\n\n Dependencies, are a list of other rules that this rule depends on. These will be executed\n in order. If any of the dependencies fails then this rule is considered failed as well, no\n further dependencies, bodies or clauses are executed unless this dependency is a checking\n or unconditional one.\n\n A dependency can be either prefixed with an exclamation mark or suffixed with question\n marks or a tilde. The exclamation mark prefix expects the dependency to fail and will\n continue then, if the dependency succeeds then the remaining dependencies and the rule\n body are skipped. With a question mark as suffix the dependency is expected to succeed,\n when it fails then the rest of the dependencies and the rule body is skipped. With a tilde\n as suffix outcome of the dependencny is ignored and the rest of the dependencies and the\n rule body is executed. The difference here is that these checking dependencies decide if\n a clause should be skipped or succeed while a failure on a normal dependency will fail a\n rule instantly. When a rule is suffixed with two question marks then this behaves like\n \"'rule_exists? dep' dep\". Making this dependency optional. This can be combined with the\n another question mark, a tilde, or explamation mark prefix. This is commonly used to\n define optional rule hooks.\n\n Dependencies can have arguments. When provided then the dependency and its arguments must\n be quoted. These arguments are passed in the 'RULE_ARGS' array to the body of the rule.\n\n A dependency prefixed with '+' is a candidate for starting early: a run of such dependencies\n is started concurrently ('BAR_PARALLEL' bounds how many run at once, 1 starts none early),\n while the verdicts of a run which succeeds are still taken in declared order. A conditional\n dependency ('?', '??', '!') and a dependency without the prefix end the run and are a barrier:\n everything started before them is collected before they run, and so is everything started\n before the body. '~' is not a barrier, it only discards the verdict, so '+dep~' starts early\n like any other and a run continues through it. Whether a rule may be started early is the\n user's claim that its side effects are acceptable; marking a clause '--parallel' (or its rule)\n is the shortcut for the prefix on each of its dependencies which is not a conditional one.\n\n A failure settles the rule wherever it is declared: the clauses which follow are started\n ahead, so one of them failing ends the rule at once instead of after the clause before it has\n been collected -- and what the rule started is killed. Keep-going ('BAR_KEEP_GOING') is the\n mode which runs the remaining clauses anyway, and a disjunct rule tries them in order, so\n neither is settled by a failure behind it.\n\n * -\n\n When there is a single hypen '-' at the end of a rule definition then the rule body is a\n call to a command or function of the same name as the rule with all arguments passed. This\n is used when one wants to add dependencies to a existing command or function.\n\n * -- [body..]\n\n After a double hyphen a optional rule body follows. This are the commands to\n execute for this clause. If these fail then the rule is considered failed. When a name but\n no body and no dependencies are given then the body defaults to the rule name. This makes\n it easy to translate simple parameterless commands and functions to rules. Usually the\n body has to be quoted to prevent shell expansions at definition time. Later when a rule\n becomes evaluated the body is passed to 'eval'.\n\n When the body is omitted, then the rule body is read from stdin. This allows to use\n heredocs or herestrings or read the body from a file.\n\n When a rule overrides an existing command a 'NOTE' will be printed on higher verbosity\n levels. The user is responsible for sensible overiding of commands.\n\n Rules must not have mutually recursive dependencies. When such is detected the\n evaluation aborts.\n\n Examples:\n\n # Add a clause to 'MAIN'\n rule -- echo hello\n\n # Different ways to define rule bodies\n rule foo_ok: -- echo inline\n rule foo_ok: -- '\n echo inline quoted\n '\n rule foo_ok: -- <<<\"echo herestring\"\n rule foo_ok: -- <'), and it is shared in both directions. A bar which a 'make -j'\n starts joins that make's server instead of opening a second budget, so the build stays at make's\n '-j'; a 'make' a body starts finds this run's server in 'MAKEFLAGS' and spends from it, so it\n stays at 'BAR_PARALLEL'. A 'make -j1' has no server to share.\n\n A failure ends the run at the failure. A rule which fails starts no further dependency and no\n further body, and the jobs it has already started are killed: their verdict cannot be used any\n more. A dependency is cancelable, the execution of a body is atomic once it has started, and\n the rule's own bodies have not run -- so nothing of that rule is half-done. The failure is\n taken when it arrives, not in the declared order of the dependencies -- a dependency which fails\n while one declared before it is still running is the rule's verdict, and that one is killed --\n so a run pays the failure and not the work behind it, wherever the failing dependency was\n declared. A rule which stops early on a '--conclusive' clause and *succeeds* collects what it\n started instead: what a body left behind is the point of a run which succeeds.\n\n An interrupt ends the run: '^C' from the terminal, or a 'TERM'/'HUP' sent to it. What the run\n started is killed with it -- the jobs with the process trees below them, and the children a body\n left in the background -- because they are the ones which cannot take the signal: an asynchronous\n command of a non-interactive shell has SIGINT and SIGQUIT ignored, so they would outlive the run\n which pays for them. The exit path still runs, and the status is the signal's (130 for '^C').\n\n A verdict is shared. A rule which two jobs both need is evaluated once and each of them takes\n that result, so a diamond costs its arms one evaluation of what they share; the results live in\n a store of this run, which ends with it, and a rule marked '--always' is never stored.\n\n A run which succeeds takes its verdicts in declared order, so a checking dependency and the\n clause body see the same results, in the same order, at any BAR_PARALLEL; a failure is the\n exception above, and a killed job records no verdict at all. A job's own output is not\n serialized: two bodies writing to the same terminal interleave, and bar's progress lines may\n arrive out of order. A notice is cleared in place rather than ended, so a shell whose line\n another already finished leaves no empty one behind it.\n\n\n Purity Requirements\n\n All rules and functions must be sequentiually pure in their success branch. This means\n side effects must not alter the behavior of subsequent rules when they fail. For rules\n where this may be the case, like rules changing directories they must rather die than\n proceed with a undefined state in case of a failure.\n\n\nRULE ENVIRONMENT\n\n Rules implicitly depend on the arguments passed and the current directory they run in. Any\n other state or environment variable is not considered. When the result of a rule would\n depend on such external state then the rule is impure and may lead to wrong\n results.\n\n\nMODULES\n\n Modules are shell snippets normally located in '$BAR_DIR' ('Bar.d/', 'bar.d/', '.Bar.d/' or\n '.bar.d/') when called as 'bar' or symlink or '~/.config/makeitso' when called as 'makeitso'.\n The 'std_lib' and 'rules_lib' are always loaded at startup. Modules matching '*_rules' are\n also autoloaded at startup. Any other '*_lib' must be manuallly loaded with 'require'.\n Modules with simple alphabetic names without underscores are lazy loaded on demand.\n\n Modules are loaded with the 'require' function. This ensures that they are loaded only once.\n Require will load modules outside of '$BAR_DIR' when a path containing at least one slash\n is given.\n\n The first variant for modules that are initially loaded is used for modules that define\n helper functions that don't have associated rules or rules that are primarly used for\n checking conditions before delegating to the actual rules which do the work.\n\n The second variant is for mudules that define rules which are self-contained and can't\n extend existing rules with new clauses. Here are the rules and functions which do the actual\n work.\n\n The reason for this is that some will add clauses to existing rule which must be done before\n the rules are evaluated while we can improve performance by lazy loading modules that are\n not always needed.\n\n The module loader derives the module name from the rule name by removing any prefixes and\n suffixes. Thus the rules which shall trigger loading must follow the naming schema with the\n module name after the prefixes in the rule name.\n\n Per convention '_rules' is a module that contains the rules (and few functions) that\n that add clauses to other rules to make 'name' accessible. These '*_rules' files are\n autoloaded at startup.\n\n '_lib' are libraries for support functions other modules may use (with 'require\n name_lib').\n\n\nAUTOMATIC MODULE LOADING\n\n Rule names may include underscores, then the word before the first underscore is used to\n determine a module name used for auto-loading rules. They can have special prefixes which\n are removed when auto-loading:\n\n - 'is_', 'has_' and 'try_' are reserved for check rules they don't have any special\n semantic except for being stripped at auto loading.\n\n When a rule is not found then a module name is derived from the rule name by removing the\n 'try_', 'is_', 'has_' prefixes and cutting off anything behind the first\n underscore. Eg. 'try_module_check' results in 'module'. This is then searched as\n 'Bar.d/module', 'bar.d/module', '.Bar.d/module' or '.bar.d/module' (or respective makeitso\n variants) and loaded if present. Thus modules that are automatically loaded must be named by\n single word without underscores.\n\n\nSTATE DUMP\n\n Loading the modules and the rulefile is most of bar's startup cost and only static\n preprocessing. To optimize this bar writes a dummp of that state to '.bar..dump'\n beside the rulefile: 'Barf' gives '.bar.Barf.dump', 'makeitso SomeOtherRules' gives\n '.bar.SomeOtherRules.dump'. Running bar again uses this state file when no rules have\n changed instead of preprocessing all files again. 'bar init' puts the file into\n '.gitignore'. 'BAR_STATE_DUMP' names another file, 'off' in the environment or as a line of\n the rulefile turns this optimization off.\n\n\nHELPER REPERTOIRE\n\n Many recurring questions like filters, retrieval, listing, counting, a state queries, have\n one deterministic answer which would otherwise be re-derived with several commands and a lot of\n context. Such an answer is a 'helper': a rule of a 'helper module' which names itself with a\n '# helper-module:' header in its first lines and registers each of its rules with a\n '# helper:', '# helper-bar:' or '# helper-makeitso:' declaration above it, the three forms\n share their four fields and differ only in which personality ('bar' or 'makeitso') lists the\n helper, and every listed row is prefixed with that personality.\n\n bar helpers # the repertoire of this installation, one line per helper plus its count\n bar helpers --json # the same repertoire as one JSON object, for a wrapper\n bar helpers --check # verify that every helper module is registered (also run by 'lints')\n\n The repertoire is generated by reading the module sources: listing it loads no module and runs\n no helper, and 'makeitso helpers' works from any directory. It even appends the 'bar'\n repertoire of the directory it is run in (a 'bar helpers' there), again without dedup. See\n 'Bar.d/helpers_rules' for the naming rules (a helper rule loads its module by its own first\n word), the registration format, the output conventions and the elision and exit code\n requirements every helper has to follow.\n\n\nSTANDARD RULES\n\n Bar ships with a module that defines a set of standard rules where other modules can add\n clauses to. Check 'Bar.d/std_rules' for details.\n\n 'SETUP', 'PREPROCESS', 'MAIN', 'POSTPROCESS' and 'CLEANUP' are special rule names called\n approbiately.\n\n The 'clause_local [var[=value]|=var..]' is for defining variables that are local to a clause.\n Only scalars can be clause local. '=' sets the variable to that value, '=' sets\n it to the empty string, and '=' keeps the value the outer scope had. The clause ends with\n the outer value back in place.\n\n\nMODULE API/RULES\n\n agent_rules - The agent output contract -- a run reduced 'up to the point'\n\n bar is written for humans: a run prints everything every tool produced. In a terminal that is\n right, in an agent's context window it is fatal -- a full 'bar tests' here is ~400 lines /\n 16 kB of which the actionable part is a handful of lines.\n\n This module turns a *run* into a small, decision shaped *answer*. Three levels of progressive\n disclosure, the caller picks the level:\n\n bar verdict .. one line per target (polling, gating)\n bar check .. verdict + chain + totals + bounded, line numbered evidence + log path\n bar log [range] the untruncated raw log, on demand\n\n The contract ('never lie') is:\n\n * the verdict line is printed always, for every target, at every verbosity -- never filtered,\n never truncated;\n * on failure the exact totals (lines and bytes) of the log are always printed, even when\n there is no evidence to show at all;\n * the raw log is written to disk before anything is printed and its absolute path is printed\n on failure. It is kept for successes too, so 'bar log' always works;\n * only bar's own machine emitted records ('OK:' 'FAIL:' 'CHECK:' 'RUN:' 'EVAL:') are pattern\n matched. Foreign tool text is *never* filtered by keyword -- doing exactly that is how the\n real shellcheck findings got lost once -- it is bounded *positionally* (a head and a tail\n window) and the elision is announced with the exact log line range that was left out;\n * every evidence line carries its line number in the log, so 'bar log ' (or\n 'sed -n p ') retrieves that line again, byte for byte;\n * a failure is never masked: the exit code is the rc of the first failing target;\n * bar's own options are never run as targets either. Everything after a rule name belongs to\n that rule, so 'bar check agent --quiet' hands the option to 'check' -- it is dropped (with a\n NOTE from verbosity 3 on) instead of being reported as the phantom result 'OK --quiet'. A\n target whose *name* begins with a dash stays reachable behind a bare '--': 'bar check --\n --weird' runs the target '--weird'.\n\n Measured on bar itself: 'bar tests' 16 kB / 409 lines -> 'bar check tests' 9 B / 1 line\n (success), and a 401 line failure of 14,6 kB -> ~1 kB carrying the verdict, the failing chain,\n the totals and the line that holds the signal.\n\n Exit codes: 0 when every target passed, 2 on a usage error, otherwise the rc of the first\n failing target propagated verbatim (3, 128+signal, ...). 'bar log' answers 3 when no log is on\n record for the target.\n\n The log is a *raw* capture: when the invoking stderr was a terminal, bar's own record lines in\n it carry that terminal's escape sequences. The printed evidence never does (it is normalized)\n and the totals always describe the file exactly as it is on disk.\n\n Variables:\n\n BAR_AGENT_DIR (gx)\n Directory for the run logs below $BAR_TOPLEVEL.\n Default: ${BAR_AGENT_DIR:-.bar.agent}\n\n BAR_AGENT_INNER (gx)\n Verbosity the measured run is forced to.\n Default: ${BAR_AGENT_INNER:-2}\n\n BAR_AGENT_HEAD (gx)\n Evidence lines taken from the head of the log.\n Default: ${BAR_AGENT_HEAD:-8}\n\n BAR_AGENT_TAIL (gx)\n Evidence lines taken from the tail of the log.\n Default: ${BAR_AGENT_TAIL:-4}\n\n BAR_AGENT_MAX_LINE (gx)\n Maximum bytes of a single evidence line.\n Default: ${BAR_AGENT_MAX_LINE:-384}\n\n BAR_AGENT_MAX_BYTES (gx)\n Maximum bytes of a printed failure block.\n Default: ${BAR_AGENT_MAX_BYTES:-4096}\n\n BAR_AGENT_KEEP (gx)\n Number of runs (log directories) to keep.\n Default: ${BAR_AGENT_KEEP:-5}\n\n BAR_AGENT_JSON (g)\n When set, print one JSON object per run.\n Default: ${BAR_AGENT_JSON:-}\n\n Functions:\n\n agent_run_dir - create this run's directory, prune old ones, update 'latest'\n The directory is named after the timestamp of this invocation and the tree it runs in, the\n same way memodb names its trees. 'latest' is a convenience symlink for humans, it is\n explicitly *not* a way to find a log (see agent_find_log).\n\n agent_tree_id - identifies the tree this run is made in\n\n agent_keep - BAR_AGENT_KEEP, clamped to at least one\n\n agent_gc - keep the newest BAR_AGENT_KEEP run directories, delete the rest\n Only directories that look like a run directory ('-') are candidates, and\n only below our own run directory, so 'latest' and anything else is never touched. A failure\n to prune is not a failure of the run that happens to trigger the prune.\n\n agent_find_log \n newest log for , newest run first\n\n agent_strip_ansi \n remove terminal control sequences from a single line\n For the few lines bar interprets itself; the bulk of the normalization happens in\n agent_evidence.\n\n agent_fail_chain \n the failing chain, target plus bar's own records\n bar print a ' FAIL: : ' record when a *dependency* fails, but a clause\n *body* that fails just returns -- a target failing on its own therefore leaves no record at\n all. The chain always starts at the target and is extended by the records found in the log,\n capped at four of them (the chain is part of the block budget).\n\n agent_evidence \n bounded excerpt as 'E'/'X' records\n Streams the log once and prints at most BAR_AGENT_HEAD + BAR_AGENT_TAIL evidence lines as\n 'E ' records, preceded by one 'X ' record when lines are\n elided ('X 0 0' means there is no evidence at all).\n Evidence is *selected positionally*: the first and the last lines of the log that are\n neither bar's own records nor empty. No keyword decides what an agent gets to see. Lines\n longer than BAR_AGENT_MAX_LINE are clipped at a word boundary with the number of bytes left\n out appended in '<+NB>', so nothing is hidden. The scan streams: memory and output stay\n bounded for arbitrarily large logs.\n\n agent_rc_text \n printable rc, '?' when it is not a number\n\n agent_run_target \n run one target, write its merged log, print its rc\n The target runs in a subshell with stdout and stderr merged into one log, so the log keeps\n the order in which the tool wrote it (memodb keeps the two streams in separate files and\n loses that order). The subshell also contains a target whose clause body calls 'exit' --\n that would otherwise take the whole report down with it -- and hands back its real rc.\n The verbosity of the inner run is pinned so the records bar writes into the log do not\n depend on how 'bar check' itself was called, and the output format of the outer invocation\n is dropped: a target that calls bar itself (a project checking its own checks) must not\n suddenly print JSON just because 'bar --json check ' was used.\n\n agent_max_block - bytes of BAR_AGENT_MAX_BYTES that may go into evidence\n The block carries a fixed part (verdict, chain, totals, log path) and the elision marker;\n both are reserved before the evidence budget is handed to agent_evidence.\n\n agent_excerpt_print \n render the excerpt of agent_evidence\n\n agent_report_failure \n print the bounded failure block\n\n agent_json_evidence \n the evidence and elision members\n\n agent_json_target \n one JSON object for a measured target\n The same fields the text block carries: rc, chain, the byte exact totals and the log path,\n plus the bounded evidence. Consumers that need a parser get one; the terse text stays the\n default because an agent reads lines, not braces.\n\n agent_json_success \n one JSON object for a target that passed\n\n agent_run_block ..\n body of the 'check' and 'verdict' rules\n is 'verdict' (one line per target, plus the log path on failure) or 'check' (the\n full bounded failure block). Nothing changes the verdict itself: that line is always\n printed, at every verbosity.\n Everything after the rule name belongs to the rule, so bar's own options land here when they\n are written *after* the target ('bar check agent --quiet'). Such an argument is not a\n target: running it would print a verdict line for it, and a consumer reads 'OK --quiet' as a\n measured result -- a lie shaped line in the one surface that must never lie. Dashed\n arguments are therefore dropped (a NOTE from verbosity 3 on names them), and a bare '--'\n turns the dropping off again, so a target whose name starts with a dash stays reachable:\n 'bar check -- --weird'.\n\n agent_log_body [,|tail:]\n print the raw log of a previous run\n\n Rules:\n\n check\n Run targets and print a bounded verdict block: one 'OK ' line when a target passed,\n otherwise its verdict, the failing chain, the exact totals of its raw output, a bounded and line\n numbered excerpt of it and the path of the untruncated log. Exits with the rc of the first\n failing target. Only targets are run: an argument that begins with a dash -- bar's own option\n written after the target, 'bar check agent --quiet' -- is not one and is dropped with a notice\n from verbosity 3 on. Write the option before the rule ('bar --quiet check agent') or a target\n whose name begins with a dash behind a '--' ('bar check -- --weird').\n\n verdict\n Run targets and print one line per target only ('OK ' / 'FAIL (rc=..)'). The\n cheapest form, meant for polling loops and gating conditions; a failure additionally gets the\n path of its log so it can be retrieved with 'bar log'. The same argument handling as for\n 'check': a dashed argument after the target is dropped, never reported as a target of its own,\n and a '--' makes everything after it a target again.\n\n log\n Print the raw log a previous 'bar check'/'bar verdict' produced for : everything, a line\n range ,, or 'tail:'. Byte identical to what 'sed -n'/'tail -n' print.\n\n --json\n Machinereadable output: emit one JSON object per run (targets, rc, totals, evidence) instead of\n the terse text. For wrapper scripts, not for reading.\n\n cargo - Rust/cargo support\n\n Variables:\n\n CARGO_TOOLCHAIN (xg)\n The rust toolchain that is used for most operations.\n Default: ${CARGO_TOOLCHAIN:-}\n\n Functions:\n\n is_cargo_tool_installed [+toolchain] [args..]\n Checks if 'cargo ' is installed\n When [args..] is not present then '--version' is used. Tools that do not handle\n '--version' need 'args..' to give some sensible result.\n\n is_cargo_toolchain_available <+toolchain>\n Check if a toolchain is available\n\n cargo_tool_complete List available cargo tools/subcommands for completion\n This function provides completion for cargo tool names (subcommands).\n It lists both built-in cargo commands and installed extensions.\n\n cargo_fix Run 'cargo fix'.\n Note that this will modify the source in place.\n\n cargo_build [buildargs..]\n Compile a local package and all of its dependencies\n\n cargo_test [testargs..]\n Execute all unit and integration tests\n\n cargo_check Run 'cargo check'. Testing whenever the source can be compiled.\n\n cargo_clippy_errors Tests with 'cargo clippy' for errors only\n\n cargo_clippy_strict Test with 'cargo clippy' for warnings and errors\n\n cargo_doc [docargs..]\n Build this package's and its dependencies' documentation\n\n cargo_update Run 'cargo update'\n\n cargo_has_unsafe_code Checks if the source use 'unsafe' code.\n This does only a coarse '-Funsafe-code' check, but does not depend on external tools.\n\n cargo_miri [miriargs..]\n Run tests under miri (memory sanitizer)\n\n cargo_bench Run 'cargo bench'\n\n cargo_publish Run 'cargo publish'\n\n Rules:\n\n cargo_lint\n Runs all linters\n\n cargo_toolchain <+toolchain>\n Clause local change of the toochain used by cargo.\n\n cargo_fmt_check\n Checks whenever the source code is well formatted.\n If available the '+nightly' toolchain is used.\n\n cargo_build_unit_tests\n Builds unit tests.\n\n cargo_test_units\n Runs unit tests.\n\n cargo_build_integration_tests\n Build integration tests\n\n cargo_test_integrations\n Run integration tests. This includes the doctests.\n\n cargo_fmt\n Run 'cargo fmt'. When available the '+nightly' toolchain is used.\n Note that this will modify the source in place.\n\n cargo_miri\n When there is unsafe code then run a test under miri supervision.\n Requires the '+nightly' toolchain.\n\n cargo_msrv_check\n Checks whenever the 'rust_version' in the manifest is sufficient.\n This check only happens when 'cargo-msrv' is installed, otherwise a warning is printed.\n\n cargo_mutants\n Run 'cargo mutants' when it is available.\n When 'cargo-mutants' is not installed a warning is printed.\n\n cargo_outdated\n Run 'cargo outedated' when it is available.\n When 'cargo-outdated' is not installed a warning is printed.\n\n cargo_audit\n Run 'cargo audit' when it is available.\n When 'cargo-audit' is not installed a warning is printed.\n\n cargo_semver_checks\n Run cargo semver-checks to test if a semver for a release is sufficient\n\n cargo_rules - General support rules for Rust/Cargo projects\n\n Checks whenever we are in a cargo project.\n Hooks cargo support into the 'std_rules'\n\n Functions:\n\n has_cargo_manifest Checks if 'Cargo.toml' exists.\n\n has_cargo_lock Checks if 'Cargo.lock' exists.\n\n Rules:\n\n is_cargo_installed\n Successful when 'cargo' is available.\n\n is_cargo_project\n Check whenever we are ready to use cargo here.\n\n release_publish\n Push a software release to crates.io (or whatever registry is configured).\n\n cliff - git cliff changelog generation\n\n Variables:\n\n GIT_CLIFF_OUTPUT (gx)\n Output where to write the changelog\n Default: ${GIT_CLIFF_OUTPUT:-CHANGELOG.md}\n\n Functions:\n The generated changelog and cliff.toml (when there where changes) are implicitly staged.\n This does not git-commit though.\n\n Rules:\n\n cliff_changelog [cliff_args..]\n use git cliff to generate a changelog.\n\n cliff_release_changelog\n Makes a changelog for a release, commits and tags it. Must be called from a release worktree\n with state 'tested'.\n\n cliff_changelog_amend\n Regenerates the changelog up to the previous commit and amends the current commit with the new changelog\n\n cliff_rules - Hooks git cliff into build_versioned_artifacts\n\n Rules:\n\n release_changelog\n Create a cliff changelog for releases when there is a 'cliff.toml' at the project root.\n\n entr - Support for the entr file watcher\n\n Functions:\n\n entr_watch_git_index\n Runs bar in a loop again whenever the git index gets changed. Takes a target rule and its parameters as argument. Defaults to 'MAIN'.\n\n Rules:\n\n is_entr_installed\n Succeeds when 'entr' is available.\n\n entr_watch\n Runs bar in a loop again whenever a file gets changed.\n Takes a target rule and its parameters as argument.\n Defaults to 'MAIN'.\n\n entr_rules - hooks entr into the watch/watch_git_index rules\n\n git - Git support rules\n\n Rules:\n\n is_git_repository\n Succeeds when we are in inside (at or below) a git repository.\n\n is_git_toplevel\n Succeeds when we are at the top level of a git repository.\n\n git_is_clean\n Checks if there are modified files, fails if there are any.\n\n git_branch_matches [branchpattern..]\n Checks that the current git branch matches any of the given patterns.\n\n is_git_pre_commit_hook\n Checks if called as githook.\n\n is_git_pre_merge_commit_hook\n Checks if called as githook.\n\n is_git_prepare_commit_msg_hook\n Checks if called as githook.\n\n is_git_commit_msg_hook\n Checks if called as githook.\n\n is_git_applypatch_msg_hook\n Checks if called as githook.\n\n is_git_pre_applypatch_hook\n Checks if called as githook.\n\n is_git_post_applypatch_hook\n Checks if called as githook.\n\n is_git_post_commit_hook\n Checks if called as githook.\n\n is_git_pre_rebase_hook\n Checks if called as githook.\n\n is_git_post_checkout_hook\n Checks if called as githook.\n\n is_git_post_merge_hook\n Checks if called as githook.\n\n is_git_pre_push_hook\n Checks if called as githook.\n\n is_git_pre_receive_hook\n Checks if called as githook.\n\n is_git_update_hook\n Checks if called as githook.\n\n is_git_proc_receive_hook\n Checks if called as githook.\n\n is_git_post_receive_hook\n Checks if called as githook.\n\n is_git_post_update_hook\n Checks if called as githook.\n\n is_git_reference_transaction_hook\n Checks if called as githook.\n\n is_git_push_to_checkout_hook\n Checks if called as githook.\n\n is_git_pre_auto_gc_hook\n Checks if called as githook.\n\n is_git_post_rewrite_hook\n Checks if called as githook.\n\n is_git_sendemail_validate_hook\n Checks if called as githook.\n\n is_git_fsmonitor_watchman_hook\n Checks if called as githook.\n\n is_git_post_index_change_hook\n Checks if called as githook.\n\n is_git_main_branch\n Checks if the current branch matches 'main master'.\n\n is_git_release_branch\n Checks if the current branch matches 'release-* release/*'.\n\n is_git_devel_branch\n Checks if the current branch matches 'devel-* devel/*'.\n\n is_git_feature_branch\n Checks if the current branch matches 'feature-* feature/*'.\n\n is_git_bugfix_branch\n Checks if the current branch matches 'bugfix-* bugfix/* fix-* fix/*'.\n\n is_git_hotfix_branch\n Checks if the current branch matches 'hotfix-* hotfix/*'.\n\n is_git_improvement_branch\n Checks if the current branch matches 'improvement-* improvement/*'.\n\n is_git_doc_branch\n Checks if the current branch matches 'doc-* doc/*'.\n\n is_git_wip_branch\n Checks if the current branch matches 'wip-* wip/*'.\n\n is_git_experimental_branch\n Checks if the current branch matches 'experiment-* experiment/*'.\n\n git_lib - Git support library\n\n Functions:\n\n git_toplevel\n Returns the path to the toplevel git repository.\n\n git_bar\n Returns the path to the bar that is initialized in the git toplevel. Fails when there is no bar initialized.\n\n git_dir Returns the absolute path to the 'GIT_DIR' (.git/).\n Note that this may be distinct from '$(git_toplevel)/.git/' when worktrees or other git\n features are used.\n\n git_ls_files [git-ls-files-opts]..\n Sorted list of files in the git repository.\n git-ls-files '--exclude-standard' is always implied. Use '-c' or '--cached' to list\n tracked files, '--others' to show untracked files, or both for all files.\n\n git_branch_name Returns the branch name that is checked out, dies when not in a git branch.\n\n git_branch_complete List all git branches for completion\n This function is called by bar_complete to provide completions for branch parameters.\n\n git_branch_find [patterns]..\n lists branches matching the given patterns\n\n git_branch_find_one [patterns]..\n lists the matching the given patterns, fails when there are more than one\n\n git_is_ancestor [patterns]..\n checks if the current branch is a ancestor of the one branch matching the patterns\n\n git_tree_hash [git-ls-files-opts]..\n Returns a sha1 hash over the current directory\n This hash is a identifier used by bar. It is not the same hash git using for storing trees.\n\n git_add_ignore [patterns..]\n Adds new ignore patterns to '.gitignore'.\n Patterns that are already present are skipped.\n\n git_parse_worktrees [main [dirs [branches [heads]]]]\n Parses git worktrees into variables provided by the caller\n - main: variable storing the main worktree (dir)\n - dirs: associative array storing 'branch:directory'\n - branches: associative array storing 'directory:branch'\n - heads: associative array storing 'directory:head'\n\n git_search [[directory] branch] [--options..]\n Lists the commits whose tree holds a file with the object id of .\n is hashed in the caller's directory, before any directory is entered. Its path -- the\n prefix of the project which contains it, plus its own name -- is the path the destination\n filters compare; a outside any project has no prefix and stands by its name alone.\n (default '.') is the project whose history is read, (default: the branch\n checked out there) the line which is walked, newest commit first.\n --exact|--name|--dir|--match - only commits holding the blob at that path, at any path\n of that name, in that directory, or at a path matching .\n --added - only the commits which start a run of presence.\n --last - only the commits which end one: the last commit in which it was still present.\n --removed - only the commits right after a run: where it disappeared.\n --absent - only the commits right before a run: the absent side of an add.\n --head |--tail - the first N, the last N of the walk; both: the last of the first .\n --filter - only commits whose message header matches the extended regex ; a malformed one is a usage error.\n --format - print git's own --format; '%H ' is prepended internally and cut off again.\n --json - a JSON array of commit, date, committer and subject; an empty selection is '[]'.\n --check - print nothing, succeed only while a commit is left.\n\n git_rules - Standard rules for git support\n\n Rules:\n\n pre-commit\n Entry rule when called as githook.\n\n pre-merge-commit\n Entry rule when called as githook.\n\n prepare-commit-msg\n Entry rule when called as githook.\n\n commit-msg\n Entry rule when called as githook.\n\n applypatch-msg\n Entry rule when called as githook.\n\n pre-applypatch\n Entry rule when called as githook.\n\n post-applypatch\n Entry rule when called as githook.\n\n post-commit\n Entry rule when called as githook.\n\n pre-rebase\n Entry rule when called as githook.\n\n post-checkout\n Entry rule when called as githook.\n\n post-merge\n Entry rule when called as githook.\n\n pre-push\n Entry rule when called as githook.\n\n pre-receive\n Entry rule when called as githook.\n\n update\n Entry rule when called as githook.\n\n proc-receive\n Entry rule when called as githook.\n\n post-receive\n Entry rule when called as githook.\n\n post-update\n Entry rule when called as githook.\n\n reference-transaction\n Entry rule when called as githook.\n\n push-to-checkout\n Entry rule when called as githook.\n\n pre-auto-gc\n Entry rule when called as githook.\n\n post-rewrite\n Entry rule when called as githook.\n\n sendemail-validate\n Entry rule when called as githook.\n\n fsmonitor-watchman\n Entry rule when called as githook.\n\n post-index-change\n Entry rule when called as githook.\n\n release_publish\n Push tags and branches to the default push remove when publishing a release.\n\n githook - Support library for managing githooks\n\n Rules:\n\n githook_enable\n Takes a list of githooks to enable as parameters. Must be called from the git_toplevel.\n Fails when a hook is not available.\n\n githook_disable\n Takes a list of githooks to disable as parameters. Must be called from the git_toplevel.\n Fails when a hook is not pointing to bar.\n\n help - Provides help, extracts documentation from modules\n\n Inline documentation uses two or three hash characters. Three '###' is used for file level\n documentation to describe a file entirely. Two '##' are used in different contexts:\n\n Variable definitions that use the 'declare' keyword can use '##' at the end of the same\n line to document the variable.\n\n Functions use formal parameter syntax: 'function name ## [--opt] [optional] - description'\n Parameters use: , [optional], param.., [param..], --flags, foo|bar alternatives.\n Multi-line documentation continues on following lines starting with optional whitespace\n followed by '##' and parameter explanations.\n\n Rules are documented by '##' lines before the rule definition, using the same formal\n parameter syntax when the rule accepts parameters.\n\n Only variables, functions and rules that have doc comments are included in the output.\n\n Documentation says what a thing does and how to use it. The reasoning behind it, why it is\n written that way, what was measured, belongs in single '#' source comments, which are not\n published.\n\n Functions:\n\n help_usage \n the builtin help of one rule, function or variable, without the whole documentation\n 'bar help ' renders every module before it picks the section asked for, which costs\n seconds on an installation of this size. This answers it from the one module the name can\n live in, resolved the way 'rule_autoload' resolves it: 'always_', 'is_', 'has_' and 'try_'\n are stripped, the word before the first '_' is the module, and '', '_lib'\n and '_rules' are the files read.\n A name the narrowed list does not carry falls back to the full documentation (a helper\n whose module the name does not derive, e.g. 'is_command_installed': 'command' is no\n module), so the answer stays right and only its cost is that of 'bar help'.\n\n help_usage_error [reason]\n a usage error on stderr: what was wrong, and the command which answers the help for name\n\n help_render_annotated \n print the render with the source of every block named above it\n The form 'help --debug' prints: each block is preceded by '#:', the line the text\n comes from. It is a wrapper so the annotation is a property of the print, never of the index.\n\n help_render_print \n print the rendered lines .., annotated when 'HELP_ANNOTATE' is set\n A line which carries an origin is preceded by '#:', the form 'help --debug'\n prints and 'help_lint --debug' reads.\n\n Rules:\n\n help [[-s|--short] topic|rule|function|variable|text]\n Show help topics\n - [-s|--short]: Show only the queried sections\n - topic|rule|function|variable: Navigate to or show only specified topics\n - text: Search the specified text in the documentation\n A name also arrives at the topic which documents it, the plural included: 'bar help\n helpers' starts at HELPER REPERTOIRE, not at the block of the function of that name.\n\n help_lint [-C ] [--rule ,..] [--debug] [--width ] [-v|--verbose] [file]\n report formatting violations in the help output\n Checks rendered documentation -- the text 'bar help' prints, or -- against the rules\n below, one violation per line as ':'. Nothing is hooked into 'lints'; a caller\n runs it. '--rule' keeps the named ids, '--debug' names the source (':', from the\n annotations 'help --debug' prints) instead of the rendered line, '-C ' prints n lines of\n context around each violation, and '--width ' also reports lines rendered wider than .\n '--verbose' is the human form: it appends the rule's own sentence, as the list below spells\n it, and uses '-C 1' unless a '-C' is given. Exit 0 when nothing is reported, 1 when something\n is.\n A list item is a line whose text starts with '*', a run of them, a single '-' or '+', or a\n dotted number ('1.'); its text column is what L3 and L4 measure.\n The rules:\n A1 the abstract, up to the first column-0 title, is freeform and not checked\n H1 a section title (column 0) is ALL CAPS\n H2 a section title does not end in '.' or ';' (an indented line which does is prose)\n H4 a title is followed by one empty line\n H5 a section title is preceded by two empty lines\n B1 blocks are separated by one empty line (two only before a section title)\n W1 with '--width': the rendered line is not wider\n W2 an empty line carries no spaces\n W3 a line carries no trailing spaces\n T1 no tab, the render is indentation\n I1 a line indented by an odd number of spaces starts a code block after an empty line\n C2 a code block is followed by an empty line\n L3 the text of a list item starts at an even column\n L4 a continuation line of a list item is indented to that column\n K1 a column of a term list starts at an even column\n K2 the columns of one term list align\n Not checked: markup ('*bold*', '/italic/', '_underline_', quoted code) is allowed and passes,\n and the abstract.\n\n helpers_rules - The helper repertoire: deterministic answers to recurring retrieval questions.\n\n A *helper* is a bar rule which answers one recurring, semi deterministic question -- a filter,\n a retrieval, a listing, a count, a state snapshot -- in a single invocation, with a bounded\n and stable output. Its consumer is an agent: with a helper the question costs one command and\n a few lines of context, without it several turns of ad hoc pipelines. Helpers filter, count\n and quote, they never summarise and never judge. Where a question is naturally a *check*\n (pass or fail), it is written as a check target and reported by 'bar check'\n (Bar.d/agent_rules) instead of being squeezed into a helper.\n\n bar helpers the repertoire: one line per helper, then the total count\n bar helpers --json the same repertoire as one JSON object (same count)\n bar helpers --check verify that every helper module is registered (see below)\n makeitso helpers as 'bar', plus the repertoire of the current directory\n\n The repertoire is read out of the module sources: nothing is loaded and no helper is executed\n to list it, and 'makeitso helpers' works from any directory. Which helpers are listed depends\n on the *personality* bar was called by -- 'bar' or 'makeitso' (see REGISTRATION below).\n\n HELPER MODULES AND RULE NAMES\n\n The helpers of one domain live together in one *helper module*, 'Bar.d/', which names\n itself in its file header:\n\n # helper-module: \n\n Every rule of a helper module is named '' or '_', because bar derives the\n module to autoload from the word before the first underscore of a rule name ('always_',\n 'is_', 'has_' and 'try_' are stripped first, see 'rule_autoload' in Bar.d/std_lib). A helper\n rule therefore loads exactly its own module: invoking one helper never loads another helper\n module, and listing the repertoire loads none at all. '' must be a word no other module\n claims -- bar ships 'git', 'rad', 'cargo', 'net', 'ssh', 'testdir', ... -- because a\n rule named 'rad_state' would autoload 'Bar.d/rad' and then fail to exist. Pick a free word.\n\n Everything in a helper module that is not an entry point is a *function*: functions are not\n rules, the autoloader never looks for them and the repertoire never lists them.\n\n REGISTRATION\n\n A helper registers itself with one declaration line at column 0, directly above its rule\n definition (only comments and blank lines in between, in the same file):\n\n # helper: | | | \n # helper-bar: | | | \n # helper-makeitso: | | | \n\n the rule name: '' or '_' of that module\n one line, the question it answers -- this is how an agent picks a helper\n how to call it, its options included ('hermeskanban [--json] ')\n one line, the shape of the answer\n\n The three forms share the four fields and the adjacency rule and differ only in *which\n personality* lists the helper. A plain '# helper:' is generic and is listed by both; a\n '# helper-bar:' is listed only when bar was called as 'bar', a '# helper-makeitso:' only when\n it was called as 'makeitso'. Every listed row carries the personality: the invocation field is\n prefixed with it, so 'bar helpers' prints 'bar hermeskanban [--json]' and 'makeitso helpers'\n prints the same 'makeitso hermeskanban [--json]', and each JSON object carries that name in a\n 'command' field. The kind never weakens the guard: an adjacency, naming, unusable-field or\n duplicate violation is reported for every declaration no matter which personality it addresses.\n\n 'makeitso helpers' also runs 'bar helpers' in the current working directory and appends those\n rows, each labelled with the 'bar' personality -- the vendored or project repertoire of the\n place it is run in. There is no dedup: a generic '# helper:' is then listed twice, once as\n the site's 'makeitso' helper and once as the directory's 'bar' helper, and the two may even run\n different code. The count line still counts every listed row. The child is invoked directly,\n not resolved through '$PATH', and can not recurse (a child is called as 'bar'); when it lists\n nothing -- no 'Bar.d' here and none installed -- the union is simply empty. '--check' is not\n affected: it validates the personality's own module directory (the site directory for 'makeitso').\n\n Neither field may contain a '|' and a declaration is one line. There is no index file: the\n repertoire is *generated* by scanning the modules, so a new helper is one rule plus one\n declaration and nothing else has to be kept in sync. 'bar helpers --check' (hooked into\n 'lints' of bar's own Barf) fails when a rule of a helper module is not declared, when a\n declaration does not resolve to the rule below it, when a helper is declared twice, when its\n name would autoload another module, when the module header names another file, when a\n declaration sits in a file that is no helper module, when a declaration is separated from its\n rule by other code or when it uses an unknown kind ('# helper-foo:' where one of the three\n forms above was expected).\n\n The index lists exactly the declarations the guard accepts and rejects nothing the index\n shows: both are views of the same single validation pass, so a helper which is not listed is\n always a reported violation and a listed helper always resolves. A rejected declaration is\n counted on stderr and named by 'bar helpers --check'.\n\n OUTPUT CONVENTIONS (requirements, not style)\n\n * print what the consumer needs for the next step: output << input;\n * the shape is the helper's choice (lines, table, JSON) but stable and documented, counts\n are an explicit line of their own and never implied;\n * print less than everything only together with the exact elision counts ('n of N') and the\n path of a file holding the complete, untruncated data, so nothing is lost;\n * exit codes: 0 answered, non-zero could not answer, and a distinct code where the caller\n has to tell 'no data' from 'error'; an empty result is an answer, not a failure;\n * stdout carries only the result -- no progress chatter and no ANSI sequences -- stderr may\n carry diagnostics, and a helper never pages interactively ('less' blocks an agent turn,\n see Bar.d/search for that anti-pattern);\n * read the data directly (file, CLI, sqlite, git) instead of going through an interface\n which refuses to run outside its own context;\n * '--json' stays opt-in: text for reading, one object for a wrapper.\n\n A helper module needs no edit anywhere else: it becomes reachable for 'makeitso' with\n 'bar init_install ' (which links every module that is not linked yet into\n '~/.config/makeitso', see Bar.d/init) and for a project with 'bar init --update' (which copies\n new modules into the project's 'Bar.d/').\n\n Functions:\n\n helpers_module_of \n the module 'rule_autoload' loads for \n Mirrors 'rule_autoload' in Bar.d/std_lib: the prefixes are stripped, then everything from\n the first underscore on. 'rad_state' -> 'rad', 'has_hermes_logs' -> 'hermes'.\n\n helpers_personality - 'bar' or 'makeitso', the personality this invocation lists for\n Bar has two personalities (see the module header and Bar.d/init): 'bar' is the project and\n installation one, 'makeitso' the private one of the single site directory '~/.config/makeitso'.\n The name bar was called by is in 'BAR_CALLED_AS' (set in the bar script from '$0'), anything\n but 'makeitso' is treated as 'bar' so a direct 'bar', './bar' or an odd symlink still lists\n the repertoire a project expects.\n\n helpers_union_child [args..]\n 'bar helpers' in the cwd for the 'makeitso' union\n 'makeitso helpers' lists the repertoire of the place it is run in as well: 'bar helpers' in\n the current working directory, which is the vendored or project repertoire there. The child\n is invoked directly through '$BAR_SELF' and never through a '$PATH' lookup, so a 'makeitso'\n can not pick a foreign 'bar'; it is called as 'bar', so it can not recurse into a union of\n its own. A 'bar' which can not list a repertoire here -- no 'Bar.d' in sight and none\n installed -- contributes nothing and its diagnostics are swallowed: an empty half is not an\n error of 'makeitso helpers'.\n\n helpers_union_rows - the 'bar' rows the 'makeitso' union appends, without their count\n\n helpers_records - scan '$BAR_DIR' for the repertoire, as US (0x1f) separated records\n One awk pass over the module files of '$BAR_DIR', nothing is loaded and no helper is run.\n The records feed the single validation pass below:\n M a '# helper-module:' header\n D a declaration\n U an unknown '# helper-:' line\n R a rule of a helper module\n S the code line separating a\n declaration from its rule\n 'D' and 'U' records are emitted for every file -- a declaration outside a helper module is a\n violation and has to be seen, and so is an unknown kind -- while 'R' and 'S' are only emitted\n for a file which names a helper module, so a module without helpers costs nothing. 'S' is\n the one code line that separates a declaration from its rule; it is decided here and not by\n the walk, so the walk costs one iteration per declaration and rule instead of one per line of\n a helper module. The kind of a 'D' record is 'generic' for a plain '# helper:', 'bar' for\n '# helper-bar:' and 'makeitso' for '# helper-makeitso:' and decides which personality lists it.\n A file which neither names a helper module nor declares a helper contributes no record at all\n and is dropped before the walk, with one 'grep -l' that stops at the first matching line: the\n index stays cheap while the module sources grow (a byte of a module nobody declares a helper\n in costs a 'grep' byte, not an 'awk' line), and the records are the ones the walk would have\n produced from the whole directory.\n Fields are separated by US (0x1f) and not by a tab: a declaration may have empty fields\n (that is one of the violations) and a tab is IFS whitespace, which 'read' would collapse.\n\n helpers_declaration_error \n why is a declaration unusable?\n Prints the reason, and nothing when the declaration is usable. One implementation for the\n whole module.\n\n helpers_walk - the one validation pass behind the index and the guard\n Walks the records of 'helpers_records' and prints, in file and line order:\n !:: every violation\n + a declaration which resolves\n A declaration is only accepted once the rule directly below it has been seen, so this\n single pass covers registration, resolution, adjacency and naming at once. The index shows\n the '+<...>' lines and the guard reports the '!<...>' lines, which is what keeps the two\n from drifting apart. A declaration is listed only when its kind addresses the personality\n of this invocation ('generic' always, 'bar' only for 'bar', 'makeitso' only for 'makeitso'),\n while every violation is reported no matter which kind it belongs to.\n leaving a file: an open declaration and a module without helpers are violations\n there. The sentinel record below leaves the last file through this same branch.\n\n helpers_declarations - the registered helpers as ' '\n Sorted by name; the file is the module file as it was found in '$BAR_DIR'. The violations\n 'helpers_walk' reports are counted on stderr, the guard names each one.\n\n helpers_index_text - the text index: one row per helper, then the count line\n The rows of this personality, then ('makeitso' only) the rows of the union, then a split line\n and the count line. The invocation of every row is prefixed with the personality it belongs\n to, and the count is the number of listed rows -- the same total the JSON form reports.\n\n helpers_index_json - the JSON index: one object per helper, count and both halves of a union\n One object: 'bar_helpers':1, the count and one object per listed helper. Every object\n carries the personality in 'command' and has it prefixed on 'invocation' (a wrapper can tell\n a 'makeitso' helper from a 'bar' one). For 'makeitso' the 'bar' repertoire of the current\n directory is merged in as well -- summed count, both halves' objects, again without dedup.\n\n helpers_check_body - the registration guard for every helper module\n Prints every violation 'helpers_walk' reports, one line each, and returns 1; prints nothing\n and returns 0 when the repertoire is complete.\n\n helpers [--json|--check]\n the repertoire, see the module header\n Body of the 'helpers' rule: the index (text or JSON) or the registration guard. The\n machine form is also entered with 'bar --json helpers' (BAR_AGENT_JSON, see\n Bar.d/agent_rules). An unknown argument is a usage error, exit 2.\n\n Rules:\n\n helpers\n The repertoire index: one line per registered helper (' | |\n ') sorted by name, then the total count as the last line. '--json' prints one\n object with the same count, '--check' verifies the registration of every helper module.\n\n helpers_check\n Verify that every helper module registers its rules ('bar helpers --check'): the guard is a\n check target, so 'bar check helpers_check' reports it with the agent contract (verdict, chain,\n totals, log path) and 'rule lints: helpers_check' can hook it into the lint target.\n\n hermes - Retrieval over the Hermes log corpus -- what the logs of this host say about , in one call\n\n Hermes writes a corpus of text on this host: the agent and gateway logs, one worker transcript\n per kanban task, one output document per cron run, and the session store. The corpus is large\n (megabytes, millions of lines) and reading it with ad hoc pipelines -- 'grep' here, 'sed' there,\n a 'sqlite3' query next -- costs several turns and floods an agent's context with raw\n transcripts. 'hermes_logs' is the one deterministic answer instead: it streams the corpus once,\n prints a bounded digest of the matching lines and keeps the complete match list on disk.\n\n makeitso hermes_logs --grep --since 1d # a bounded digest and the exact total\n makeitso hermes_logs --grep --count # only the number\n makeitso hermes_logs --grep --json | jq . # one object for a wrapper\n\n THE CORPUS (explicit, never guessed)\n\n One *corpus root* is a Hermes home directory; the default is '$HERMES_HOME' and falls back to\n '~/.hermes'. A root contributes the sources below, and only these -- nothing is searched\n implicitly, no directory is discovered by walking:\n\n logs /logs/*.log, *.log.gz the agent/gateway/gui logs\n workers /kanban/logs/*.log, *.log.gz one worker transcript per kanban task\n cron any file below /cron/output/ 'cron/output//.md' and the\n flat legacy 'cron/output/_*.txt'\n sessions /sessions/*.jsonl, *.jsonl.gz diverted (transcript) session records\n store /state.db the SQLite session store, read only\n\n The root is overridable with '--root ' (repeatable) or with the environment variable\n BAR_HERMES_LOGS_ROOT (':' separated); '--root' wins. Other Hermes profiles are addressed with\n '--root ~/.hermes/profiles/', never by guessing: a path that differs between the gateway,\n the TUI and a worker is exactly what an agent must not hardcode. With more than one root every\n locator carries the index of its root ('#2/logs/agent.log:88') and one 'corpus:' line names each.\n\n THE ANSWER (one record per matching line)\n\n \n\n locator ':' relative to its root ('logs/agent.log:1234'), so\n 'sed -n 1234p /logs/agent.log' retrieves the line byte for byte. A store\n record has no file line and reads 'state.db://', which\n 'sqlite3 -readonly /state.db' resolves with 'where id='.\n timestamp 'YYYY-MM-DD HH:MM:SS' local time -- the stamp on the line when it has one (at the\n line start for a log line, anywhere on a JSON record), otherwise the stamp of the\n newest line above it that had one, otherwise the file's modification time. A\n leading '~' marks those two derived cases, an exact stamp carries no marker. A\n store record carries the message's own timestamp.\n snippet the line with its control characters removed, clipped at\n BAR_HERMES_LOGS_SNIPPET characters (default 160) with the number of characters\n left out appended as '<+N>'. Tabs separate the fields; a snippet never holds one.\n\n Then the totals, as lines of their own and never implied:\n\n corpus: [] matches: shown: of (limit lines, chars)\n clipped: snippet(s) at chars unreadable: source(s) not scanned: ..\n max: \n\n 'matches' is the exact number of matching lines, a hard assertion: it is the count the scan\n produced over exactly the sources the 'corpus:' lines name, and it is qualified by 'unreadable'\n when a source could not be read. The digest prints at most '--limit' match lines (default 20,\n BAR_HERMES_LOGS_LIMIT) and at most BAR_HERMES_LOGS_BYTES characters of them (default 1200), so\n the answer stays around a kilobyte however busy the corpus is. Whenever anything stays unshown\n the complete match list is on disk before anything is printed and its absolute path is printed as\n 'max:'. That file holds every match (' the whole line'), up to\n BAR_HERMES_LOGS_MAX records (default 20000) -- beyond that the file is capped and 'max:' says so.\n It is written below BAR_HERMES_LOGS_DIR (default $TMPDIR) and named after the query, so the same\n question reuses one file and the answer stays retrievable.\n\n FILTERS\n\n --grep an extended regular expression, matched against every line of every scanned\n source with 'grep -E' semantics. Without it every line matches (the digest is\n still bounded, the count still exact). It is the only thing that decides what\n counts: no keyword prefilter, no sampling, no ranking.\n --since '[smhdw]' (ago) or anything GNU 'date -d' accepts ('2026-10-10',\n '2026-10-10 08:00:00'); records before the cutoff are dropped. In the store\n the range is pushed into SQL, which makes a bounded session query cheap.\n --source restrict to a source kind, repeatable.\n --task keep only the sources whose path contains : '--task t_deadbeef' keeps a\n worker transcript, '--run 2026-10-10' the cron run of that day. Applied to\n the source path, so the store never matches a task selector.\n --session keep only the records of that session: store rows whose session id contains it\n (in SQL), 'sessions/.jsonl' files by name, and the lines of every other\n source by their text (the agent logs carry '[]').\n --count the number alone -- it wins over '--json', because one number is already the\n machine form. Nothing is elided here, so no 'max:' line is printed.\n\n EXIT CODES: 0 answered, matches found. 3 answered, no match ('grep' semantics: an answer, not a\n failure -- the count is printed). 2 usage error. 1 could not answer: a root is not a directory,\n or a source could not be read -- the digest is still printed, marked with 'unreadable:' and with\n the reason on stderr, and the count then covers only what was readable.\n\n NON GOALS: no summarisation, no judgement, no LLM, no ranking -- it is a filter. It does not\n replace the 'session_search' tool for fuzzy recall, and it does not read what Hermes stores\n outside the paths above (the kanban board as a database, cron job definitions, the vault). It\n never pages, never colours, and prints no progress on stdout.\n\n HANDOFF BRIEFS ('hermes_handoff')\n\n A child session ('delegate_task') starts with no memory of the conversation that spawned it, so\n the caller hands it a brief. 'hermes_handoff' composes that brief, resolves its anchor phrases\n against the session store and checks that a child could retrieve the session -- one rule, three\n modes:\n\n hermes_handoff --goal [--context | --context-file ]\n [--anchor ].. [--gate ].. [--report-chars ]\n [--session ] [--db ] [--json]\n a brief in seven sections, in order, one heading each, plain text: GOAL, CONTEXT,\n RETRIEVAL, ANCHORS, MECHANICS, ACCEPTANCE GATES and REPORT FORMAT. GOAL, CONTEXT and\n every --gate line are printed verbatim; each --anchor phrase resolves to its messages.\n hermes_handoff --anchors .. [--limit ] [--session ] [--db ] [--json]\n one 'msg ' line per distinct matching message, then 'matches: '.\n hermes_handoff --verify [--session ] [--db ] [--json]\n whether a child could retrieve this session: 'session msgs= chars=\n retrieval=ok|missing', then the two retrieval recipes and the live delegation caps.\n\n THE SESSION STORE\n\n The store is a read only SQLite database, '${HERMES_HOME:-$HOME/.hermes}/state.db', overridden by\n '--db ' or '$HANDOFF_DB'. The session id comes from '--session ' or\n '$HERMES_SESSION_ID'; the profile -- the first segment of an '@session:/' link --\n from '$HERMES_SESSION_PROFILE', default 'default'. 'messages' and 'sessions' are read with the\n 'sqlite3' CLI: no LLM and no summariser. An anchor phrase resolves to the messages whose\n 'content' contains it, case insensitively; a phrase that resolves to nothing is reported as\n 'UNRESOLVED: ' and never guessed. Nothing host local is hardcoded: the caps are read\n live with 'hermes config get delegation.' and '$HERMES_MAX_ITERATIONS'.\n\n EXIT CODES\n\n 0 answered; 1 --anchors matched nothing; 2 usage error; 3 the session or the store is unknown\n or unreadable; 4 the brief has an unresolved anchor (the whole brief is still printed).\n\n The text and the '--json' forms carry the same numbers; '--json' is one object.\n\n\n Variables:\n\n BAR_HERMES_LOGS_ROOT (gx)\n ':' separated corpus roots, '--root' wins\n Default: ${BAR_HERMES_LOGS_ROOT:-}\n\n BAR_HERMES_LOGS_LIMIT (gx)\n match lines the digest prints\n Default: ${BAR_HERMES_LOGS_LIMIT:-20}\n\n BAR_HERMES_LOGS_SNIPPET (gx)\n characters kept of a matching line\n Default: ${BAR_HERMES_LOGS_SNIPPET:-160}\n\n BAR_HERMES_LOGS_MAX (gx)\n records kept in the full match list\n Default: ${BAR_HERMES_LOGS_MAX:-20000}\n\n BAR_HERMES_LOGS_BYTES (gx)\n characters of match records the digest prints\n Default: ${BAR_HERMES_LOGS_BYTES:-1200}\n\n BAR_HERMES_LOGS_DIR (gx)\n where the full match list is written\n Default: ${BAR_HERMES_LOGS_DIR:-}\n\n Functions:\n\n hermes_logs_selector