Command-line arguments for ghciwatch

Ghciwatch loads a GHCi session for a Haskell project and reloads it when source files change.

Usage: ghciwatch [--command SHELL_COMMAND] [--watch PATH] [OPTIONS ...]

Examples

Load cabal v2-repl and watch for changes in src:

ghciwatch

Load a custom GHCi session and watch for changes in multiple locations:

ghciwatch --command "cabal v2-repl lib:test-dev" \
          --watch src --watch test

Run tests after reloads:

ghciwatch --test-ghci TestMain.testMain \
          --after-startup-ghci ':set args "--match=/OnlyRunSomeTests/"'

Use hpack to regenerate .cabal files:

ghciwatch --before-startup-shell hpack \
          --restart-glob '**/package.yaml'

Also reload the session when .persistentmodels change:

ghciwatch --watch config/modelsFiles \
          --reload-glob '**/*.persistentmodels'

Don’t reload for README.md files:

ghciwatch --reload-glob '!src/**/README.md'

Arguments

<FILE>

A Haskell source file to load into a GHCi REPL.

Shortcut for --command 'ghci PATH'. Conflicts with --command.

Options

--command <SHELL_COMMAND>

A shell command which starts a GHCi REPL, e.g. ghci or cabal v2-repl or similar.

This is used to launch the underlying GHCi session that ghciwatch controls.

May contain quoted arguments which will be parsed in a sh-like manner.

--error-file <ERROR_FILE>

A file to write compilation errors to.

The output format is compatible with ghcid’s --outputfile option.

--enable-eval

Evaluate Haskell code in comments.

This parses line commands starting with -- $> or multiline commands delimited by {- $> and <$ -} and evaluates them after reloads.

--clear

Clear the screen before reloads and restarts

--no-interrupt-reloads

Don’t interrupt reloads when files change.

Depending on your workflow, ghciwatch may feel more responsive with this set.

--completions <COMPLETIONS>

Generate shell completions for the given shell

Possible values: bash, elvish, fish, powershell, zsh

Lifecycle hooks

--test-ghci <GHCI_CMD>

ghci commands to run tests

Tests are run after startup and after reloads.

Example: TestMain.testMain.

Can be given multiple times.

--test-shell <SHELL_CMD>

Shell commands to run tests

Tests are run after startup and after reloads.

Commands starting with async: will be run in the background.

Can be given multiple times.

--before-startup-shell <SHELL_CMD>

Shell commands to run before startup

Startup hooks run when GHCi is started (at ghciwatch startup and after GHCi restarts).

Commands starting with async: will be run in the background.

This can be used to regenerate .cabal files with hpack.

Can be given multiple times.

--after-startup-ghci <GHCI_CMD>

ghci commands to run after startup

Startup hooks run when GHCi is started (at ghciwatch startup and after GHCi restarts).

Use :set args ... to set command-line arguments for test hooks.

Can be given multiple times.

--after-startup-shell <SHELL_CMD>

Shell commands to run after startup

Startup hooks run when GHCi is started (at ghciwatch startup and after GHCi restarts).

Commands starting with async: will be run in the background.

Can be given multiple times.

--before-reload-ghci <GHCI_CMD>

ghci commands to run before reload

Reload hooks are run when modules are changed on disk.

Can be given multiple times.

--before-reload-shell <SHELL_CMD>

Shell commands to run before reload

Reload hooks are run when modules are changed on disk.

Commands starting with async: will be run in the background.

Can be given multiple times.

--after-reload-ghci <GHCI_CMD>

ghci commands to run after reload

Reload hooks are run when modules are changed on disk.

Can be given multiple times.

--after-reload-shell <SHELL_CMD>

Shell commands to run after reload

Reload hooks are run when modules are changed on disk.

Commands starting with async: will be run in the background.

Can be given multiple times.

--before-restart-ghci <GHCI_CMD>

ghci commands to run before restart

The GHCi session must be restarted when .cabal or .ghci files are modified.

Can be given multiple times.

--before-restart-shell <SHELL_CMD>

Shell commands to run before restart

The GHCi session must be restarted when .cabal or .ghci files are modified.

Commands starting with async: will be run in the background.

Can be given multiple times.

--after-restart-ghci <GHCI_CMD>

ghci commands to run after restart

The GHCi session must be restarted when .cabal or .ghci files are modified.

Can be given multiple times.

--after-restart-shell <SHELL_CMD>

Shell commands to run after restart

The GHCi session must be restarted when .cabal or .ghci files are modified.

Commands starting with async: will be run in the background.

Can be given multiple times.

File watching options

--poll <DURATION>

Use polling with the given interval rather than notification-based file watching.

Polling tends to be more reliable and less performant. In particular, notification-based watching often misses updates on macOS.

--debounce <DURATION>

Debounce file events; wait this duration after receiving an event before attempting to reload.

Defaults to 0.5 seconds.

Default value: 500ms

--watch <PATH>

A path to watch for changes.

Directories are watched recursively. Can be given multiple times.

--reload-glob <RELOAD_GLOBS>

Reload the GHCi session when paths matching this glob change.

By default, only changes to Haskell source files trigger reloads. If you’d like to exclude some files from that, you can add an ignore glob here, like !src/my-special-dir/**/*.hs.

Globs provided here have precisely the same semantics as a single line in a gitignore file (man gitignore), where the meaning of ! is inverted: namely, ! at the beginning of a glob will ignore a file.

The last matching glob will determine if a reload is triggered.

Can be given multiple times.

--restart-glob <RESTART_GLOBS>

Restart the GHCi session when paths matching this glob change.

By default, only changes to .cabal or .ghci files will trigger restarts.

See --reload-globs for more details.

Can be given multiple times.

Logging options

--log-filter <LOG_FILTER>

Log message filter.

Can be any of “error”, “warn”, “info”, “debug”, or “trace”. Supports more granular filtering, as well.

The grammar is: target[span{field=value}]=level, where target is a module path, span is a span name, and level is one of the levels listed above.

See documentation in tracing-subscriber.

A nice value is ghciwatch=debug.

Default value: ghciwatch=info

--backtrace <BACKTRACE>

How to display backtraces in error messages

Default value: 0

Possible values:

  • 0: Hide backtraces in errors
  • 1: Display backtraces in errors
  • full: Display backtraces with all stack frames in errors
--trace-spans <TRACE_SPANS>

When to log span events, which loosely correspond to tasks being run in the async runtime.

Allows multiple values, comma-separated.

Default value: new,close

Possible values:

  • new: Log when spans are created
  • enter: Log when spans are entered
  • exit: Log when spans are exited
  • close: Log when spans are dropped
  • none: Do not log span events
  • active: Log when spans are entered/exited
  • full: Log all span events
--log-json <PATH>

Path to write JSON logs to.

JSON logs are not yet stable and the format may change on any release.