BSD-3-Clause licensed by Neil Mitchell, jpmoresmau
Maintained by Neil Mitchell
This version can be pinned in stack with:ghcid-0.6.6@sha256:64decb5a31685b3a0ce2f35e9c364b3e49d99e96dc3b6c725fe0a9eda03085e8,3161

Module documentation for 0.6.6

ghcid Hackage version Stackage version Linux Build Status Windows Build Status

Either “GHCi as a daemon” or “GHC + a bit of an IDE”. To a first approximation, it opens ghci and runs :reload whenever your source code changes, formatting the output to fit a fixed height console. Unlike other Haskell development tools, ghcid is intended to be incredibly simple. In particular, it doesn’t integrate with any editors, doesn’t depend on GHC the library and doesn’t start web servers.

Acknowledgements: This project incorporates significant work from JPMoresmau, who is listed as a co-author.

Using it

Run cabal update && cabal install ghcid to install it as normal. Then run ghcid --height=8 --topmost "--command=ghci Main.hs". The height is the number of lines you are going to resize your console window to (defaults to height of the console). The topmost is to make the window sit above all others, which only works on Windows. The command is how you start your project in ghci. If you omit --command then it will default to stack ghci if you have the stack.yaml file and .stack-work directory, default to ghci if you have a .ghci file in the current directory, and otherwise default to cabal repl.

Personally, I always create a .ghci file at the root of all my projects, which usually reads something like:

:set -fwarn-unused-binds -fwarn-unused-imports
:set -isrc
:load Main

After that, resize your console and make it so you can see it while working in your editor. On Windows the console will automatically sit on top of all other windows. On Linux, you probably want to use your window manager to make it topmost or use a tiling window manager.

What you get

On every save you’ll see a list of the errors and warnings in your project. It uses ghci under the hood, so even relatively large projects should update their status pretty quickly. As an example:

Main.hs:23:10:
    Not in scope: `verbosit'
    Perhaps you meant `verbosity' (imported from System.Console.CmdArgs)
Util.hs:18:1: Warning: Defined but not used: `foo'

Or, if everything is good, you see:

All good

Please report any bugs you find.

Ghcid Integration

There are a few tools that integrate Ghcid into editors, see the plugins folder for currently supported integrations.

FAQ

  • This isn’t as good as full IDE. I’ve gone for simplicity over features. It’s a point in the design space, but not necessarily the best point in the design space for you. For “real” IDEs see the Haskell wiki.
  • If I delete a file and put it back it gets stuck. Yes, that’s a bug in GHCi. If you see GHCi getting confused just kill ghcid and start it again.
  • I want to run my tests when files change. You can pass any ghci expression with the --test flag, e.g. --test=:main, which will be run whenever the code is warning free (or pass --warnings for when the code is merely error free).
  • I want to run arbitrary commands when arbitrary files change. This project reloads ghci when files loaded by ghci change. If you want a more general mechanism something like Steel Overseer will probably work better.
  • I want syntax highlighting in the error messages. One option is to use Neovim or Emacs and run the terminal in a buffer whose file type is set to Haskell.
  • I’m not seeing pattern matching warnings. Ghcid automatically appends -fno-code to the command line, which makes the reload cycle about twice as fast. Unfortunately GHC 8.0 suffers from bug 10600 which means -fno-code also disables pattern matching warnings. Until that GHC bug is fixed either accept no pattern match warnings or use -c to specify a command line to start ghci that doesn’t include -fno-code.

Changes

Changelog for ghcid

0.6.6
#89, exit sooner when the child process exits unexpectedly
Add Eq instance for Ghci
#88, add a --project flag
Rename --notitle flag to --no-title
0.6.5
#82, properly deal with warning messages including spans
#78, support boot files better
Better support for dealing with GHC 8.0 call stack messages
#79, support multiple --test flags
#71, improve multi-project stack support
#74, make sure Cygwin terminals flush output properly
If the test exits then exit ghcid
0.6.4
#69, fix up for stack project with file arguments
0.6.3
#68, add --no-status to avoid printing the reloading message
0.6.2
#63, detect test failures and update the titlebar/icon
#66, add --warnings to run tests even in there are warnings
#62, find stack.yaml in the parent directory
Make --verbose echo all things sent to stdin
#57, support wrappers that access stdin first (e.g. stack)
#67, make --reload/--restart recurse through directories
#61, deal with drive letters in files (for stack on Windows)
#58, improve the --help message
0.6.1
Add --reload to add files that reload, but do not restart
#56, allow --restart to take directories
0.6
#38, implement loading with stack
Add process, quit and execStream to the API
#29, add interrupt function
Add Data instances for the types
Make stopGhci more effective, now kills the underlying process
Make startGhci take a function to write the buffer to
0.5.1
#17, deal with recursive modules errors properly
#50, use -fno-code when not running tests (about twice as fast)
#44, abbreviate the redundant module import error
#45, add an extra space before the ... message
#42, always show the first error in full
#43, work even if people use break-on-exception flags
#42, make the first error a minimum of 5 lines
0.5
Add an extra boolean argument to startGhci
Add the number of modules loaded after All good
Print out messages until the prompt comes up
#23, add arguments and change what commands get invoked
#35, change the titlebar icon on Windows
0.4.2
Fix a GHC 7.6 warning
0.4.1
#37, add a --notitle flag
Require extra-1.2
0.4
#33, make Ctrl-C more robust
#31, add an outputfile feature
#32, make newer warnings first (save a file, view its warnings)
#28, fix issues on VIM file saves
#29, support running a quick test on each save
Add a --directory flag to change directory first
#26, use fs-notify to avoid excessive wakeups
#25, detect console size just before using it
0.3.6
#24, don't error out if error/putStrLn are not imported
0.3.5
#19, put errors in bold
#9, display interesting information in the title bar
#7, reload if the .ghci or .cabal file changes
Use nubOrd
Require extra-1.1
0.3.4
#21, if you aren't waiting for any files, exit
0.3.3
#21, if the root file is missing, report an error
#20, avoid an O(n^2) nub
0.3.2
#18, reformat excessively long lines, add a --width flag
0.3.1
Ensure if there are lots of warnings, the first error gets shown
0.3
#11, ignore certain GHCi-only warnings
#13, fix version printing
#8, display Loading... when starting
Require the extra library
#14, figure out the terminal height automatically
0.2
#6, rewrite as a library
Remove duplicate error messages from cabal repl
0.1.3
#2, handle files that get deleted while loaded
#3, flesh out the test suite
#4, give a polite error if ghci does not start
#5, add --topmost flag to make the window topmost
0.1.2
Add a very simple test suite
Default to cabal repl if there is no .ghci file
#1, if there is an IOError just :reload
Say why you are reloading
0.1.1
Support arguments to --command
0.1
Initial version