Configuration

Some of the command line options can be set as defaults. The first time you run howzit, a YAML file is written to ~/.config/howzit/howzit.yaml. You can open it in your default editor automatically by running howzit --edit-config. It contains the available options:

---
:color: true
:config_editor: subl
:editor: subl
:header_format: block
:highlight: true
:highlighter: mdcat
:include_upstream: true
:log_level: 0
:matching: fuzzy
:multiple_matches: choose
:output_title: false
:pager: auto
:paginate: true
:show_all_code: false
:show_all_on_error: false
:wrap: 0

If :color: is false, output will not be colored, and markdown highlighting will be bypassed.

If :color: is true and :highlight: is true, the :highlighter: option will be used to add Markdown highlighting.

If :paginate: is true, the :pager: option will be used to determine the tool used for pagination. If it's false and you're using iTerm, "marks" will be added to topic titles allowing keyboard navigation.

:highlighter: and :pager: can be set to auto (default) or a command of your choice for markdown highlighting and pagination.

:matching: can be "partial", "beginswith", "fuzzy" or "exact" (see below).

If :include_upstream: is true, build note files in parent directories will be included in addition to the current directory. Priority goes from current directory to root in descending order, so the current directory is top priority, and a build notes file in / is the lowest. Higher priority topics will not be overwritten by a duplicate topic from a lower priority note.

Set :log_level: to 0 for debug messages, or 3 to suppress superfluous info messages.

:multiple_matches: determines how howzit will handle cases where a search results in multiple matches. It can be set to "first" (first match in notes), "best" (shortest topic match), "all" (display all results), or "choose" (displays a menu of results). Default is "choose." When grepping for results, only "all" or "choose" are valid, if the default is something else, "choose" will be used. Can be overridden with the --multiple TYPE flag.

:header_format: changes the way topic titles are displayed. Setting it to "border" will add a horizontal rule and brackets around the title. Setting it to "block" will mark topic titles with a Unicode block instead.

Matching

All matching is case insensitive. This setting can be overridden by the --matching TYPE flag on the command line.

• :matching: partial

  Partial is the default, search matches any part of the topic title.

  Example: howzit other matches 'Another Topic'.

• :matching: beginswith

  Matches from the start of the title.

  Example: howzit another matches 'Another Topic', but neither 'other' or 'topic' will.

• :matching: fuzzy

  Matches anything containing the search characters in order, no matter what comes between them.

  Example: howzit asct matches 'Another Section'

• :matching: exact

  Case insensitive but must match the entire title.

  Example: Only howzit another topic will match 'Another Topic'

Pager

If set to auto, howzit will look for pagers in this order, using the first one it finds available:

• $GIT_PAGER
• $PAGER
• bat
• less
• more
• cat
• pager

If you're defining your own, make sure to include any flags necessary to handle the output. If you're using howzit's coloring, for example, you need to specify any options needed to display ANSI escape sequences (e.g. less -r).

Highlighter

If set to auto howzit will look for markdown highlighters in this order, using the first it finds available:

• mdcat
• mdless

If you're combining a highlighter with howzit's pagination, include any flags needed to disable the highlighter's pagination (e.g. mdless --no-pager).

Configuring from the Command Line

You can get and set config options from the command line using --config-get and --config-set. If you run --config-get with no argument, it will display all config options. If you add a key (exact match required) you can get just the value for that key.

Using --config-set requires an argument in the format key=value. The type of the value (boolean, integer, string, symbol) will be automatically determined and converted. To change your highlighter, for example, use howzit --config-set highlighter=mdcat.