cabal-gild: Formats package descriptions.

[ development, library, mit, program ] [ Propose Tags ]

Gild formats package descriptions.

[Skip to Readme]


Manual Flags


Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


  • No Candidates
Versions [RSS],,,,,,,,,,,,,,,,,,,,,
Change log
Dependencies base (>= && <4.18 || >= && <4.19 || >= && <4.20), bytestring (>= && <0.12 || >= && <0.13), cabal-gild, Cabal-syntax (>= && <3.9 || >= && <3.11), containers (>=0.6.6 && <0.7), directory (>= && <1.4), exceptions (>=0.10.5 && <0.11), filepath (>= && <1.5), parsec (>= && <3.2), pretty (>= && <1.2), text (>=2.0.1 && <2.2), transformers (>= && <0.6 || >= && <0.7) [details]
License MIT
Author Taylor Fausak
Maintainer Taylor Fausak
Category Development
Source repo head: git clone
Uploaded by fozworth at 2024-02-23T20:41:55Z
Distributions NixOS:, Stackage:
Executables cabal-gild
Downloads 471 total (121 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-02-23 [all 1 reports]

Readme for cabal-gild-

[back to package description]


Workflow Hackage Stackage

Gild is an opinionated command line utility that formats Haskell package descriptions, which are also known as *.cabal files. Gild can also be used to automatically discover exposed-modules; see the pragmas section for more about that.

Gild started as a fork of phadej/cabal-fmt, but is now totally separate. For a brief summary of the differences between Gild and cabal-fmt, read the announcement post.


Given a package description like this:

name          : example
version       :

  build-depends: mtl>=2.3, base
  if impl(ghc>=9.8)
    ghc-options: -Wmissing-role-annotations

Gild will produce output like this:

cabal-version: 3.0
name: example

    mtl >=2.3,

  ghc-options: -Wall

  if impl(ghc >= 9.8)
    ghc-options: -Wmissing-role-annotations

See the installation section for how to get Gild and the usage section for how to use it.


  • There should be no configuration options. As long as the output format is reasonable, the specifics should not matter too much. This means the amount of indentation cannot be changed, for example.

  • The output should be diff friendly. This means things generally go on their own line, trailing commas are used when possible, and elements are sorted where it makes sense.

  • The output should be semantically the same as the input. This means no normalization or canonicalization. For example, separate build-depends fields are not merged together.

  • It should be possible to format other files that use the same format as package descriptions. This means cabal.project files can be formatted as well.

  • The focus should be mostly on formatting. There should be no effort made to validate input or provide any checks or lints. However some quality of life features, like automatic module discovery, are desireable.

  • Formatting should be as regular as possible. Special cases for particular fields or sections should be avoided unless it improves quality of life. For example, interpreting the build-depends field to pretty print it is okay.

  • The command line utility should be fast enough to run on every save. It should not need network access.


Go to the latest release page and download the binary for your platform.

To run Gild in a GitHub Actions workflow, consider using cabal-gild-setup-action.

From Source

In general you should prefer downloading the appropriate binary for you platform. However it is possible to build Gild from source. It supports Linux, macOS, and Windows along with the three most recent versions of GHC. Any other configurations are unsupported.

With Cabal:

$ cabal install cabal-gild

With Stack:

$ stack install cabal-gild


Gild is a command line utility named cabal-gild. By default it reads from standard input (STDIN) and writes to standard output (STDOUT). Its behavior can be modified with command line options, which are described below.


Run cabal-gild --help to see the options that Gild supports. They are:

  • --help: Prints the help message to STDOUT then exits successfully.

  • --version: Prints the version number to STDOUT then exits successfully.

  • --input=FILE: Uses FILE as the input. If this is - (which is the default), then the input will be read from STDIN.

  • --mode=MODE: Sets the mode to MODE, which must be either format (the default) or check. When the mode is format, Gild will output the formatted package description. When the mode is check, Gild will exit successfully if the input is already formatted, otherwise it will exit unsuccessfully.

  • --output=FILE: Uses FILE as the output. If this is - (which is the default), then the output will be written to STDOUT. To modify a file in place, use the same file as both input and output. For example:

    $ cabal-gild --input p.cabal --output p.cabal

    This option is ignored when the mode is check.

  • --stdin=FILE: When reading input from STDIN, use FILE as the effective input file. This is useful when a file's contents are already available, like in an editor. For example:

    $ cabal-gild --stdin p.cabal < p.cabal

    This option is ignored when the input is not -.


Gild supports special comments in package descriptions that act as pragmas. Each pragma starts with -- cabal-gild:. Pragmas must be the last comment before a field.

  • -- cabal-gild: discover DIRECTORY [DIRECTORY ...]: This pragma will discover any Haskell files in any of the given directories and use those to populate the list of modules or signatures. For example, given this input:

      -- cabal-gild: discover source/library
      exposed-modules: ...

    Assuming there is a single Haskell file at source/library/M.hs, Gild will produce this output:

      -- cabal-gild: discover source/library
      exposed-modules: M

    This pragma only works with the exposed-modules, other-modules, and signatures fields. It will be ignored on all other fields.

    Any existing modules or signatures in the list will be ignored. The entire field (including comments) will be replaced. This means adding, removing, and renaming modules or signatures should be handled automatically.

    This pragma searches for files with any of the following extensions: *.chs, *.cpphs, *.gc, *.hs, *.hsc, *.hsig, *.lhs, *.lhsig, *.ly, *.x, or *.y,