2.9. The `.ghci` file
Prev | Chapter 2. Using GHCi | Next

## 2.9. The `.ghci` file

When it starts, unless the `-ignore-dot-ghci` flag is given, GHCi reads and executes commands from the following files, in this order, if they exist:

1. `./.ghci`

2. ``appdata`/ghc/ghci.conf`, where `appdata` depends on your system, but is usually something like `C:/Documents and Settings/`user`/Application Data`

3. On Unix: `$HOME/.ghc/ghci.conf`

4. `$HOME/.ghci`

The `ghci.conf` file is most useful for turning on favourite options (eg. `:set +s`), and defining useful macros. Note: when setting language options in this file it is usually desirable to use `:seti` rather than `:set` (see Section 2.8.3, “Setting options for interactive evaluation only”).

Placing a `.ghci` file in a directory with a Haskell project is a useful way to set certain project-wide options so you don't have to type them every time you start GHCi: eg. if your project uses multi-parameter type classes, scoped type variables, and CPP, and has source files in three subdirectories A, B and C, you might put the following lines in `.ghci`:

    :set -XMultiParamTypeClasses -XScopedTypeVariables -cpp
    :set -iA:B:C

(Note that strictly speaking the `-i` flag is a static one, but in fact it works to set it using `:set` like this. The changes won't take effect until the next `:load`, though.)

Once you have a library of GHCi macros, you may want to source them from separate files, or you may want to source your `.ghci` file into your running GHCi session while debugging it

    :def source readFile

With this macro defined in your `.ghci` file, you can use `:source file` to read GHCi commands from `file`. You can find (and contribute!-) other suggestions for `.ghci` files on this Haskell wiki page: GHC/GHCi

Additionally, any files specified with `-ghci-script` flags will be read after the standard files, allowing the use of custom .ghci files.

Two command-line options control whether the startup files files are read:

`-ignore-dot-ghci`

  Don't read either `./.ghci` or the other startup files when starting up.

`-ghci-script`

  Read a specific file after the usual startup files. Maybe be specified repeatedly for multiple inputs.

When defining GHCi macros, there is some important behavior you should be aware of when names may conflict with built-in commands, especially regarding tab completion.

For example, consider if you had a macro named `:time` and in the shell, typed `:t 3` - what should happen? The current algorithm we use for completing commands is:

1. First, look up an exact match on the name from the defined macros.

2. Look for the exact match on the name in the built-in command list.

3. Do a prefix lookup on the list of built-in commands - if a built-in command matches, but a macro is defined with the same name as the built-in defined, pick the macro.

4. Do a prefix lookup on the list of built-in commands.

5. Do a prefix lookup on the list of defined macros.

Here are some examples:

1. You have a macro `:time` and enter `:t 3`

   You get `:type 3`

2. You have a macro `:type` and enter `:t 3`

   You get `:type 3` with your defined macro, not the builtin.

3. You have a macro `:time` and a macro `:type`, and enter `:t 3`

   You get `:type 3` with your defined macro.

Prev | Up | Next
2.8. The `:set` and `:seti` commands | Home | 2.10. Compiling to object code inside GHCi