ghcid

Start ghcid and monitor a Haskell file for changes

$ ghcid [path/to/Main.hs]

$ ghcid --command "[stack ghci Main.hs]"

$ ghcid --run=[action] [path/to/Main.hs]

$ ghcid --height=[height] --width=[width] [path/to/Main.hs]

$ ghcid --outputfile=[path/to/output_file.txt] [path/to/Main.hs]

$ ghcid --allow-eval [path/to/Main.hs]

ghcid [options] [ghci arguments]

-c
    Specifies the command to run GHCi (e.g., `ghci`, `cabal repl`, `stack ghci`). Defaults to an intelligent guess based on project type.

--test
    Runs this command upon successful compilation. Commonly used for continuous testing (e.g., `MyModule.runTests`).

-r, --reload
    Runs the test command on every reload, not just on successful compilation (e.g., to run tests on warnings).

--no-test
    Prevents the test command from running automatically.

-T
    Throttles the output to only show updates every N seconds, reducing flickering.

-W, --warnings
    Shows compilation warnings (this is the default behavior).

-w, --no-warnings
    Hides compilation warnings.

-O, --output
    Redirects all output to the specified file instead of stdout.

--lint
    Runs a linter command (e.g., `hlint`) after successful compilation.

--no-lint
    Disables running a linter.

--top
    Shows only the first N lines of output from GHCi. Useful for concise error summaries.

--height
    Shows a total of N lines of output, trimming if necessary, to control terminal height.

--errors
    Controls how errors are displayed. Common modes include `brief` or `full`.

--ignore
    Ignores files or directories matching the given glob pattern from being watched.

--ignore-dir
    Specifically ignores directories matching the pattern.

--dir
    Changes the working directory before running GHCi. Useful when ghcid is run from a different location.

--debounce
    Waits for a period of inactivity after file changes before reloading, preventing rapid reloads during multi-file saves.

--restart
    Restarts GHCi completely on every file change. Slower, but can resolve persistent issues for complex changes.

--shutdown
    Runs a specified command when GHCi exits, useful for cleanup.

--ghci-options
    Passes additional options directly to the underlying GHCi process.

--project
    Specifies a custom project configuration file (default is `.ghcid`).

The ghcid command is a popular tool for Haskell developers that provides instant feedback on compilation errors and warnings. It operates by continuously running GHCi (or `cabal repl`, `stack ghci`) in the background, watching for changes in your project files. As soon as a file is saved, ghcid reloads the project in GHCi and displays any resulting errors or warnings directly in your terminal. This significantly shortens the development cycle by eliminating the need for manual compilation and allowing developers to catch issues immediately. Beyond just compilation, it can also be configured to run tests or other commands upon successful compilation, making it an invaluable tool for continuous testing and an efficient, lightweight alternative to full-fledged IDEs for Haskell development.

As ghcid relies on GHCi for its core functionality, its performance is highly dependent on GHCi's startup and reload times, which can be significant for very large Haskell projects. Occasionally, it might become confused by major project restructuring, file renames, or dependency changes, requiring a manual restart of the ghcid process. Its output can also be quite verbose without careful use of options like `--height` or `--top` to limit the displayed lines.

ghcid can be configured using a `.ghcid` file in the project root directory. This file can contain command-line options, one per line, simplifying invocation and ensuring consistent settings across a project. For example, to always run tests, you could place `--test='cabal test'` in your `.ghcid` file instead of typing it every time.

ghcid exits with code `0` on success (meaning no compilation errors or test failures if `--test` is used) and `1` if there are compilation errors or the `--test` command fails.

Developed by Neil Mitchell (ndmitchell), ghcid emerged as a lightweight and efficient solution for providing rapid feedback in Haskell development workflows. It gained significant popularity due to its simplicity, speed, and effectiveness in shortening the edit-compile-test cycle, offering an `npm watch`-like experience tailored for Haskell projects.

ghc(1), ghci(1), cabal(1), stack(1)