zdharma-continuum.zinit/doc/HACKING.md

HACKING.md

Documentation

README: Update the table of contents

1. Install doctoc
2. To update the TOC, run the following command:

doctoc --github README.md

Update asciidoc and/or zshelldoc

Important

Make sure you have docker or podman installed.

1. From the root of the repo, run:

make doc-container

If, for some reason, you want to build the zshelldocs or the PDF manually, you'll need:

1. Patience, zsd is very finicky about locales. You have been warned.
2. zshelldoc (zsd)
3. asciidoc
4. make doc

Generate the manpage (doc/zinit.1)

1. Install pandoc
2. From the root of the repo run:

pandoc --standalone --to man README.md -o doc/zinit.1

Updating the gh-pages (zdharma-continuum.github.io)

1. Check out the documentation branch

git fetch origin documentation
git checkout documentation

2. Do your modifications and push your changes
3. Keep an eye on the CI logs
4. If all went well, head to https://zdharma-continuum.github.io/ to see your changes live.

Note

If you really need to push directly, without CI, please refer to the README in the documentation

Testing

We run our tests with zunit.

To add a new test case:

1. Install zunit and revolver:

zinit for \
    as"program" \
    atclone"ln -sfv revolver.zsh-completion _revolver" \
    atpull"%atclone" \
    pick"revolver" \
  @molovo/revolver \
    as"completion" \
    atclone"./build.zsh; ln -sfv zunit.zsh-completion _zunit" \
    atpull"%atclone" \
    sbin"zunit" \
  @zunit-zsh/zunit

2. Create a new .zunit file in the tests/ dir. Here's a template:

#!/usr/bin/env zunit

@setup {
  load setup
  setup
}

@teardown {
  load teardown
  teardown
}

@test 'zinit-annex-bin-gem-node installation' {
  # This spawns the official zinit container and executes a single zinit command
  # inside it
  run ./scripts/docker-run.sh --wrap --debug --zunit \
    zinit light as"null" for zdharma-continuum/null

  # Verify the exit code of the command above
  assert $state equals 0
  assert "$output" contains "Downloading"

  local artifact="${PLUGINS_DIR}/zdharma-continuum---null/readme.md"
  # Check if we downloaded the file correctly and if it is readable
  assert "$artifact" is_file
  assert "$artifact" is_readable
}

You should, of course, also check out the existing tests ;)

3. To run your new test:

zunit --verbose tests/your_test.zunit

Debugging tests

If you ever need to inspect the ZINIT[HOME_DIR] dir, where zinit's internal data is stored, you can do so by commenting out the @teardown section in your test. Then you can re-run said test and head over to ${TMPDIR:-/tmp}/zunit-zinit. Good luck!

Misc

Get the list of supported ices

To get the list in a quick-and-dirty fashion, you issue:

zinit --help | tail -1

See zinit-autoload.zsh for implementation details.