Skip to content
loadout

Diagnosing problems

Terminal window
loadout doctor        # everything unmet on this machine
loadout doctor -v     # passing checks too
loadout describe pw   # one command, in detail

What doctor reports

Section titled “What doctor reports”
loadout 0.2.1
config   config.yaml         ok
shell    zsh 5.9             ok
output   init.zsh            stale
         run `loadout apply`
paths    2 configured, 1 missing
         ~/src/archive       not found

Four kinds of finding:

  • Missing tools. An alias or function requires a binary that is not on PATH.
  • Dead paths. A configured path does not exist.
  • Unmet configuration. A command needs a section your configuration leaves empty.
  • Stale output. config.yaml is newer than the generated file, so what your shell is sourcing is not what your configuration says.

A finding is not a failure. Most are informational: you may not want gatsby installed on this machine, and the alias existing costs nothing.

Stale output is the one to act on

Section titled “Stale output is the one to act on”
output   init.zsh            stale
         run `loadout apply`

This means you changed the configuration and did not re-render. Everything else in doctor describes the machine; this one describes work you have not finished.

describe

Section titled “describe”
Terminal window
loadout describe msh

Prints the summary, the usage, the requirements resolved against this machine, and the configuration sections that shape it. Working backwards from a command that misbehaves to the section it reads is what this is for.

Terminal window
loadout describe      # everything describable

Failures that are not what they look like

Section titled “Failures that are not what they look like”

An alias exists but the command is not found

Section titled “An alias exists but the command is not found”

The alias is generated even when its tool is missing, on purpose — dropping it would give you “command not found” with no explanation of which alias was involved. doctor names the tool; install it.

A change did nothing

Section titled “A change did nothing”

Editing config.yaml does not change your shell. Run loadout apply, then open a new shell or re-source your configuration.

An upgrade did nothing

Section titled “An upgrade did nothing”

Upgrading the binary does not rewrite the generated file. Run loadout apply after upgrading. Release notes say so whenever the shipped catalog changed.

echo $NPM_TOKEN is empty although the credential is set

Section titled “echo $NPM_TOKEN is empty although the credential is set”

loadout env prints export lines and cannot set them. You need eval "$(loadout env)", and a line in your shell configuration if you want it in every shell. See Credentials.

A function ignores its flags on the second call

Section titled “A function ignores its flags on the second call”

If you are writing your own shell and hit this: zsh localises OPTIND per function and bash does not, so getopts needs an explicit local OPTIND=1. Every shipped function has it. See Shell portability.

A function works in zsh and misbehaves in bash

Section titled “A function works in zsh and misbehaves in bash”

Almost always one of three constructs. ${=var} is zsh-only and bash rejects it outright; ${var:t} is zsh-only and bash silently returns the whole path rather than the basename; local -A needs bash 4 and macOS ships 3.2. The first fails loudly. The other two are the dangerous ones.

Reporting something

Section titled “Reporting something”

If a finding looks wrong, loadout doctor -v shows the passing checks alongside, which usually makes clear what was actually tested. Include that output in an issue, along with loadout version and your shell and platform.