ocamlformat-help.txt

NAME
       ocamlformat - A tool to format OCaml code.

SYNOPSIS
       ocamlformat [OPTION]... [SRC]...

DESCRIPTION
       ocamlformat automatically formats OCaml code.

OPTIONS (CODE FORMATTING STYLE)
       Unless otherwise noted, any option --option=VAL detailed in this
       section can be set in many ways, its value is determined in the
       following order (of increasing priority): the default value is used if
       no other value is specified. The value of a boolean option --foo or
       --no-foo can be modified in an .ocamlformat configuration file with
       'foo = {true,false}', it can be done for any other option with an
       'option = VAL' line (*), or using the OCAMLFORMAT environment
       variable: OCAMLFORMAT=option=VAL,...,option=VAL, or as an optional
       parameter on the command line, or with a global [@@@ocamlformat
       "option=VAL"] attribute in the processed file, or with an
       [@@ocamlformat "option=VAL"] attribute on expression in the processed
       file.

       (*) .ocamlformat files in current and all ancestor directories for
       each input file are used, as well as the global ocamlformat file
       defined in $XDG_CONFIG_HOME or in $HOME/.config if $XDG_CONFIG_HOME is
       undefined. The global ocamlformat file has the lowest priority, then
       the closer the directory is to the processed file, the higher the
       priority. The global ocamlformat file is only used when the option
       enable-outside-detected-project is set.

       If the disable option is not set, an .ocamlformat-ignore file
       specifies files that OCamlFormat should ignore. Each line in an
       .ocamlformat-ignore file specifies a filename relative to the
       directory containing the .ocamlformat-ignore file. Shell-style regular
       expressions are supported. Lines starting with # are ignored and can
       be used as comments.

       If the disable option is set, an .ocamlformat-enable file specifies
       files that OCamlFormat should format even when the disable option is
       set. Each line in an .ocamlformat-enable file specifies a filename
       relative to the directory containing the .ocamlformat-enable file.
       Shell-style regular expressions are supported. Lines starting with #
       are ignored and can be used as comments.

       --align-cases
           Align match/try cases horizontally.

       --align-constructors-decl
           Align type declarations horizontally.

       --align-variants-decl
           Align type variants declarations horizontally.

       --assignment-operator={end-line|begin-line}
           Position of the assignment operator. end-line positions assignment
           operators (`:=` and `<-`) at the end of the line and breaks after
           it if the whole assignment expression does not fit on a single
           line. begin-line positions assignment operators (`:=` and `<-`) at
           the beginning of the line and breaks before it if the whole
           assignment expression does not fit on a single line. The default
           value is end-line.

       --break-before-in={fit-or-vertical|auto}
           Whether the line should break before the in keyword of a let
           binding. fit-or-vertical will always break the line before the in
           keyword if the whole let binding does not fit on a single line.
           auto will only break the line if the in keyword does not fit on
           the previous line. The default value is fit-or-vertical.

       --break-cases={nested|fit|toplevel|fit-or-vertical|all}
           Break pattern match cases. nested forces a break after nested
           or-patterns to highlight the case body. Note that with nested, the
           indicate-nested-or-patterns option is not needed, and so ignored.
           Specifying fit lets pattern matches break at the margin naturally.
           toplevel forces top-level cases (i.e. not nested or-patterns) to
           break across lines, otherwise break naturally at the margin.
           fit-or-vertical tries to fit all or-patterns on the same line,
           otherwise breaks. all forces all pattern matches to break across
           lines. The default value is nested.

       --break-collection-expressions={fit-or-vertical|wrap}
           Break collection expressions (lists and arrays) elements by
           elements. fit-or-vertical vertically breaks expressions if they do
           not fit on a single line. wrap will group simple expressions and
           try to format them in a single line. The default value is
           fit-or-vertical.

       --break-fun-decl={wrap|fit-or-vertical|smart}
           Style for function declarations and types. wrap breaks only if
           necessary. fit-or-vertical vertically breaks arguments if they do
           not fit on a single line. smart is like fit-or-vertical but try to
           fit arguments on their line if they fit. The default value is
           wrap.

       --break-fun-sig={wrap|fit-or-vertical|smart}
           Style for function signatures. wrap breaks only if necessary.
           fit-or-vertical vertically breaks arguments if they do not fit on
           a single line. smart is like fit-or-vertical but try to fit
           arguments on their line if they fit. The default value is wrap.

       --break-infix={wrap|fit-or-vertical}
           Break sequence of infix operators. wrap will group simple
           expressions and try to format them in a single line.
           fit-or-vertical vertically breaks expressions if they do not fit
           on a single line. The default value is wrap.

       --break-separators={before|after|after-and-docked}
           Break before or after separators such as `;` in list or record
           expressions. before breaks the expressions before the separator.
           after breaks the expressions after the separator. after-and-docked
           breaks the expressions after the separator and docks the brackets
           for records. The default value is before.

       --break-sequences
           Force sequence expressions to break irrespective of margin.

       --break-string-literals={newlines-and-wrap|wrap|newlines|never}
           Break string literals. newlines-and-wrap mode breaks lines at
           newlines and wraps string literals at the margin. wrap mode wraps
           string literals at the margin. Quoted strings such as {id|...|id}
           are preserved. newlines mode breaks lines at newlines. never mode
           formats string literals as they are parsed, in particular, with
           escape sequences expanded. The default value is newlines-and-wrap.
           Warning: This option is deprecated.

       --break-struct={force|natural}
           Break struct-end module items. force will break struct-end phrases
           unconditionally. natural will break struct-end phrases naturally
           at the margin. The default value is force.

       --cases-exp-indent=COLS
           Indentation of cases expressions (COLS columns). See also the
           cases-matching-exp-indent and nested-match options. The default
           value is 4. Cannot be set in attributes.

       --cases-matching-exp-indent={compact|normal}
           Indentation of cases right-hand sides which are `match` or `try`
           expressions. compact forces an indentation of 2, unless
           nested-match is set to align and we're on the last case. normal
           indents as it would any other expression. The default value is
           compact.

       --disable
           Disable ocamlformat. This is used in attributes to locally disable
           automatic code formatting. One can also use [@@@ocamlformat
           "enable"] instead of [@@@ocamlformat "disable=false"]

       --disambiguate-non-breaking-match
           Add parentheses around matching constructs that fit on a single
           line.

       --doc-comments={after|before}
           Doc comments position. after puts doc comments after the
           corresponding code. before puts comments before the corresponding
           code. The default value is after.

       --doc-comments-padding=PADDING
           Add PADDING spaces before doc comments in type declarations. The
           default value is 2.

       --doc-comments-tag-only={default|fit}
           Position of doc comments with only tags. default means no special
           treatment. fit puts doc comments on the same line. The default
           value is default.

       --escape-chars={preserve|decimal|hexadecimal}
           Escape encoding for character literals. preserve escapes ASCII
           control codes but leaves the upper 128 characters unchanged.
           decimal produces ASCII printable characters using decimal escape
           sequences as needed. hexadecimal mode escapes every character. The
           default value is preserve.

       --escape-strings={preserve|decimal|hexadecimal}
           Escape encoding for string literals. See `--escape-chars` for the
           interpretation of the modes. The default value is preserve.

       --exp-grouping={parens|preserve}
           Style of expression grouping. parens groups expressions using
           parentheses. preserve preserves the original grouping syntax
           (parentheses or begin/end). The default value is parens.

       --extension-indent=COLS
           Indentation of items inside extension nodes (COLS columns). The
           default value is 2.

       --extension-sugar={preserve|always}
           Extension formatting. The default value is preserve.

       --field-space={tight|loose|tight-decl}
           Whether or not to use a space between a field name and the rhs.
           This option affects records and objects. tight does not use a
           space between a field name and the punctuation symbol (`:` or
           `=`). loose does. tight-decl is tight for declarations and loose
           for instantiations. The default value is tight.

       --function-indent=COLS
           Indentation of function cases (COLS columns). The default value is
           2.

       --function-indent-nested={never|always|auto}
           Whether the function-indent parameter should be applied even when
           in a sub-block. never only applies function-indent if the function
           block starts a line. always always apply function-indent. auto
           applies function-indent when seen fit. The default value is never.

       --if-then-else={compact|fit-or-vertical|keyword-first|k-r}
           If-then-else formatting. compact tries to format an if-then-else
           expression on a single line. fit-or-vertical vertically breaks
           branches if they do not fit on a single line. keyword-first
           formats if-then-else expressions such that the if-then-else
           keywords are the first on the line. k-r formats if-then-else
           expressions with parentheses that match the K&R style. The default
           value is compact.

       --indent-after-in=COLS
           Indentation (COLS columns) after `let ... in`, unless followed by
           another `let`. The default value is 0. Cannot be set in
           attributes.

       --indicate-multiline-delimiters={space|no|closing-on-separate-line}
           How to indicate that two matching delimiters live on different
           lines. space prints a space inside the delimiter to indicate the
           matching one is on a different line. no doesn't do anything
           special to indicate the closing delimiter.
           closing-on-separate-line makes sure that the closing delimiter is
           on its own line. The default value is space.

       --indicate-nested-or-patterns={space|unsafe-no}
           Control whether or not to indicate nested or-pattern using
           indentation. space starts lines of nested or-patterns with " |"
           rather than "| ". unsafe-no does not indicate nested or-patterns.
           Warning: this can produce confusing code where a short body of a
           match case is visually hidden by surrounding long patterns,
           leading to misassociation between patterns and body expressions.
           The default value is space.

       --infix-precedence={indent|parens}
           Use indentation or also discretionary parentheses to explicitly
           disambiguate precedences of infix operators. indent uses
           indentation to explicitly disambiguate precedences of infix
           operators. parens uses parentheses to explicitly disambiguate
           precedences of infix operators. The default value is indent.

       --leading-nested-match-parens
           Nested match parens formatting. Cannot be set in attributes.

       --let-and={compact|sparse}
           Style of let_and. compact will try to format `let p = e and p = e`
           in a single line. sparse will always break between them. The
           default value is compact.

       --let-binding-indent=COLS
           Indentation of let binding expressions (COLS columns) if they do
           not fit on a single line. The default value is 2. Cannot be set in
           attributes.

       --let-binding-spacing={compact|sparse|double-semicolon}
           Spacing between let binding. compact spacing separates adjacent
           let bindings in a module according to module-item-spacing. sparse
           places two open lines between a multi-line module-level let
           binding and the next. double-semicolon places double semicolons
           and an open line between a multi-line module-level let binding and
           the next. The default value is compact.

       --let-module={compact|sparse}
           Module binding formatting. compact does not break a line after the
           let module ... = and before the in if the module declaration does
           not fit on a single line. sparse breaks a line after let module
           ... = and before the in if the module declaration does not fit on
           a single line. The default value is compact.

       --let-open={preserve|short|long|auto}
           Module open formatting. preserve keeps the original style. short
           means the Module.(...) style is used. long means the let open
           Module in (...) style is used. auto means the one fitting best is
           used. The default value is preserve.

       -m COLS, --margin=COLS
           Format code to fit within COLS columns. The default value is 80.
           Cannot be set in attributes.

       --match-indent=COLS
           Indentation of match/try cases (COLS columns). The default value
           is 0.

       --match-indent-nested={never|always|auto}
           Whether the match-indent parameter should be applied even when in
           a sub-block. never only applies match-indent if the match block
           starts a line. always always apply match-indent. auto applies
           match-indent when seen fit. The default value is never.

       --max-indent=COLS
           Maximum offset (COLS columns) added to a new line in addition to
           the offset of the previous line. The default value is none. Cannot
           be set in attributes.

       --module-item-spacing={sparse|preserve|compact}
           Spacing between items of structures and signatures. sparse will
           always break a line between two items. preserve will not leave
           open lines between one-liners of similar sorts unless there is an
           open line in the input. compact will not leave open lines between
           one-liners of similar sorts. The default value is sparse.

       --nested-match={wrap|align}
           Style of a pattern-matching nested in the last case of another
           pattern-matching. wrap wraps the nested pattern-matching with
           parentheses and adds indentation. align vertically aligns the
           nested pattern-matching under the encompassing pattern-matching.
           The default value is wrap.

       --no-break-infix-before-func
           Break infix operators whose right arguments are anonymous
           functions specially: do not break after the operator so that the
           first line of the function appears docked at the end of line after
           the operator.

       --no-wrap-fun-args
           Style for function call.

       --ocp-indent-compat
           Attempt to generate output which does not change (much) when
           post-processing with ocp-indent.

       --parens-ite
           Uses parentheses around if-then-else branches that spread across
           multiple lines.

       --parens-tuple={always|multi-line-only}
           Parens tuple expressions. always always uses parentheses around
           tuples. multi-line-only mode will try to skip parens for
           single-line tuples. The default value is always.

       --parens-tuple-patterns={multi-line-only|always}
           Parens tuple patterns. multi-line-only mode will try to skip
           parens for single-line tuple patterns. always always uses
           parentheses around tuples patterns. The default value is
           multi-line-only.

       --parse-docstrings
           Parse and format docstrings.

       --sequence-blank-line={compact|preserve-one}
           Blank line between expressions of a sequence. compact will not
           keep any blank line between expressions of a sequence. preserve
           will keep a blank line between two expressions of a sequence if
           the input contains at least one. The default value is compact.

       --sequence-style={separator|terminator|before}
           Style of sequence. separator puts spaces before and after
           semicolons. terminator only puts spaces after semicolons. before
           breaks the sequence before semicolons. The default value is
           separator.

       --single-case={compact|sparse}
           Style of pattern matching expressions with only a single case.
           compact will try to format a single case on a single line. sparse
           will always break the line before a single case. The default value
           is compact.

       --space-around-arrays
           Add a space inside the delimiters of arrays.

       --space-around-lists
           Add a space inside the delimiters of lists.

       --space-around-records
           Add a space inside the delimiters of records.

       --space-around-variants
           Add a space inside the delimiters of variants.

       --stritem-extension-indent=COLS
           Indentation of structure items inside extension nodes (COLS
           columns). The default value is 0.

       --type-decl={compact|sparse}
           Style of type declaration. compact will try to format constructors
           and records definition in a single line. sparse will always break
           between constructors and record fields. The default value is
           compact.

       --type-decl-indent=COLS
           Indentation of type declarations (COLS columns) if they do not fit
           on a single line. The default value is 2. Cannot be set in
           attributes.

       --wrap-comments
           Wrap comments and docstrings. Comments and docstrings are divided
           into paragraphs by open lines (two or more consecutive newlines),
           and each paragraph is wrapped at the margin. Multi-line comments
           with vertically-aligned asterisks on the left margin are not
           wrapped. Consecutive comments with both left and right margin
           aligned are not wrapped either.

OPTIONS
       -c VAL, --config=VAL (absent OCAMLFORMAT env)
           Aggregate options. Options are specified as a comma-separated list
           of pairs: option=VAL,...,option=VAL.

       --check
           Check whether the input files already are formatted. Mutually
           exclusive with --inplace and --output.

       --disable-conf-attrs
           Disable configuration in attributes.

       --disable-conf-files
           Disable .ocamlformat configuration files.

       --disable-outside-detected-project
           Warning: this option is deprecated and will be removed in
           OCamlFormat v1.0.

       --enable-outside-detected-project
           Read .ocamlformat config files outside the current project. The
           project root of an input file is taken to be the nearest ancestor
           directory that contains a .git or .hg or dune-project file.
           Formatting is enabled even if no .ocamlformat configuration file
           is found.

       -g, --debug
           Generate debugging output.

       --help[=FMT] (default=auto)
           Show this help in format FMT. The value FMT must be one of `auto',
           `pager', `groff' or `plain'. With `auto', the format is `pager` or
           `plain' whenever the TERM env var is `dumb' or undefined.

       -i, --inplace
           Format in-place, overwriting input file(s).

       --impl
           Parse file with unrecognized extension as an implementation.

       --intf
           Parse file with unrecognized extension as an interface.

       -n N, --max-iters=N
           Fail if output of formatting does not stabilize within N
           iterations. May be set in .ocamlformat. The default value is 10.

       --name=NAME
           Name of input file for use in error reporting. Defaults to the
           input file name. Some options can be specified in configuration
           files named '.ocamlformat' in the same or a parent directory of
           NAME, see documentation of other options for details.

       --no-comment-check
           UNSAFE: Control whether to check comments and documentation
           comments. May be set in .ocamlformat.

       --no-version-check
           Do no check version matches the one specified in .ocamlformat.

       -o DST, --output=DST
           Output file. Mutually exclusive with --inplace. Write to stdout if
           omitted.

       --ocp-indent-config
           Read .ocp-indent configuration files. base is an alias for
           let-binding-indent. type is an alias for type-decl-indent. in is
           an alias for indent-after-in. with sets function-indent and
           match-indent. match_clause is an alias for cases-exp-indent.
           ppx_stritem_ext is an alias for stritem-extension-indent.
           max_indent is an alias for max-indent. strict_with sets
           function-indent-nested and match-indent-nested.

       -p {ocamlformat|compact|sparse|conventional|janestreet},
       --profile={ocamlformat|compact|sparse|conventional|janestreet}
           Select a preset profile which sets all options, overriding lower
           priority configuration. The ocamlformat profile aims to take
           advantage of the strengths of a parsetree-based auto-formatter,
           and to limit the consequences of the weaknesses imposed by the
           current implementation. This is a style which optimizes for what
           the formatter can do best, rather than to match the style of any
           existing code. General guidelines that have directed the design
           include: Legibility, in the sense of making it as hard as possible
           for quick visual parsing to give the wrong interpretation, is of
           highest priority; Whenever possible the high-level structure of
           the code should be obvious by looking only at the left margin, in
           particular, it should not be necessary to visually jump from left
           to right hunting for critical keywords, tokens, etc; All else
           equal compact code is preferred as reading without scrolling is
           easier, so indentation or white space is avoided unless it helps
           legibility; Attention has been given to making some syntactic
           gotchas visually obvious. The compact profile is similar to
           ocamlformat but opts for a generally more compact code style. The
           sparse profile is similar to ocamlformat but opts for a generally
           more sparse code style. The conventional profile aims to be as
           familiar and "conventional" appearing as the available options
           allow. The janestreet profile is used at Jane Street. The default
           value is ocamlformat.

       --print-config
           Print the configuration determined by the environment variable,
           the configuration files, preset profiles and command line.
           Attributes are not considered. If many input files are specified,
           only print the configuration for the first file. If no input file
           is specified, print the configuration for the root directory if
           specified, or for the current working directory otherwise.

       -q, --quiet
           Quiet. May be set in .ocamlformat.

       --root=DIR
           Root of the project. If specified, only take into account
           .ocamlformat configuration files inside DIR and its
           subdirectories.

       --use-file
           Parse file with unrecognized extension as a use_file.

       --version
           Show version information.

       SRC Input files. At least one is required, and exactly one without
           --inplace. If - is passed, will read from stdin.

ENVIRONMENT
       These environment variables affect the execution of ocamlformat:

       OCAMLFORMAT
           See option --config.