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 vertically. The flag is unset by default.

       --align-constructors-decl
           Align type declarations vertically. The flag is unset by default.

       --align-variants-decl
           Align type variants declarations vertically. The flag is unset by
           default.

       --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={fit|nested|toplevel|fit-or-vertical|all}
           Break pattern match cases. Specifying fit lets pattern matches
           break at the margin naturally. 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.
           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 fit.

       --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-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. The flag is unset by default.

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

       --break-sequences
           Force sequence expressions to break irrespective of margin. The
           flag is set by default.

       --break-string-literals={auto|never}
           Break string literals. auto mode breaks lines at newlines and
           wraps string literals at the margin. never mode formats string
           literals as they are parsed, in particular, with escape sequences
           expanded. The default value is auto.

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

       --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"]. The flag is
           unset by default.

       --disambiguate-non-breaking-match
           Add parentheses around matching constructs that fit on a single
           line. The flag is unset by default.

       --doc-comments={after-when-possible|before-except-val|before}
           Doc comments position. after-when-possible puts doc comments after
           the corresponding code. This option has no effect on variant
           declarations because that would change their meaning and on
           structures, signatures and objects for readability.
           before-except-val puts doc comments before the corresponding code,
           but puts doc comments of val and external declarations after the
           corresponding declarations. before puts comments before the
           corresponding code. The default value is after-when-possible.

       --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.

       --dock-collection-brackets
           Dock the brackets of lists, arrays and records, so that when the
           collection does not fit on a single line the brackets are opened
           on the preceding line and closed on the following line. The flag
           is set by default.

       --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.

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

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

       --indicate-nested-or-patterns={unsafe-no|space}
           Control whether or not to indicate nested or-pattern using
           indentation. 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.
           space starts lines of nested or-patterns with " |" rather than "|
           ". The default value is unsafe-no.

       --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. The flag is unset by default.
           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.

       --line-endings={lf|crlf}
           Line endings used. lf uses Unix line endings. crlf uses Windows
           line endings. The default value is lf. Cannot be set in
           attributes.

       -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 68. 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-align-cases
           Unset align-cases.

       --no-align-constructors-decl
           Unset align-constructors-decl.

       --no-align-variants-decl
           Unset align-variants-decl.

       --no-break-infix-before-func
           Unset break-infix-before-func.

       --no-break-sequences
           Unset break-sequences.

       --no-disable
           Unset disable.

       --no-disambiguate-non-breaking-match
           Unset disambiguate-non-breaking-match.

       --no-dock-collection-brackets
           Unset dock-collection-brackets.

       --no-leading-nested-match-parens
           Unset leading-nested-match-parens.

       --no-ocp-indent-compat
           Unset ocp-indent-compat.

       --no-parens-ite
           Unset parens-ite.

       --no-parse-docstrings
           Unset parse-docstrings.

       --no-space-around-arrays
           Unset space-around-arrays.

       --no-space-around-lists
           Unset space-around-lists.

       --no-space-around-records
           Unset space-around-records.

       --no-space-around-variants
           Unset space-around-variants.

       --no-wrap-comments
           Unset wrap-comments.

       --no-wrap-fun-args
           Unset wrap-fun-args.

       --ocaml-version=V
           Version of OCaml syntax of the output. The default value is the
           version of OCaml used to build OCamlFormat.

       --ocp-indent-compat
           Attempt to generate output which does not change (much) when
           post-processing with ocp-indent. The flag is unset by default.

       --parens-ite
           Uses parentheses around if-then-else branches that spread across
           multiple lines. The flag is unset by default.

       --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. The flag is unset by default.

       --sequence-blank-line={preserve-one|compact}
           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. compact will not keep any blank line
           between expressions of a sequence. The default value is
           preserve-one.

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

       --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. The flag is set by
           default.

       --space-around-lists
           Add a space inside the delimiters of lists. The flag is set by
           default.

       --space-around-records
           Add a space inside the delimiters of records. The flag is set by
           default.

       --space-around-variants
           Add a space inside the delimiters of variants. The flag is set by
           default.

       --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. The flag is unset by default.

       --wrap-fun-args
           Style for function call. The flag is set by default.

OPTIONS (REMOVED OPTIONS)
       --doc-comments-val=VAL
           This option has been removed in version 0.16.0. If you are using
           `doc-comments-val=before` in combination with
           `doc-comments=before` then only `doc-comments=before` is now
           required to achive the same behavior. If you are using
           `doc-comments-val=before` in combination with `doc-comments=after`
           this behavior is not available anymore. If you are using
           `doc-comments-val=after` in combination with `doc-comments=before`
           please now use `doc-comments=before-except-val`. If you are using
           `doc-comments-val=after` in combination with `doc-comments=after`
           then only `doc-comments=after-when-possible` is now required to
           achieve the same behavior. If you are using
           `doc-comments-val=unset` the same behavior can now be achieved by
           setting `doc-comments` only.

       --escape-chars=VAL
           This option has been removed in version 0.16.0. Concrete syntax
           will now always be preserved.

       --escape-strings=VAL
           This option has been removed in version 0.16.0. Concrete syntax
           will now always be preserved.

       --extension-sugar=VAL
           This option has been removed in version 0.17.0. Concrete syntax
           will now always be preserved.

       --let-open=VAL
           This option has been removed in version 0.17.0. Concrete syntax
           will now always be preserved.

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.

       --comment-check
           Control whether to check comments and documentation comments.
           Unsafe to turn off. May be set in .ocamlformat. The flag is set by
           default.

       --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).

       --ignore-invalid-option
           Ignore invalid options (e.g. in .ocamlformat).

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

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

       --margin-check
           Emit a warning if the formatted output exceeds the margin.

       -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 and starting point
           when searching for '.ocamlformat' files. 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
           Unset comment-check.

       --no-quiet
           Unset quiet.

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

       --numeric=X-Y
           Instead of re-formatting the file, output one integer per line
           corresponding to the indentation value, printing as many values as
           lines in the range between lines X and Y (included).

       -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 {conventional|default|compact|sparse|ocamlformat|janestreet},
       --profile={conventional|default|compact|sparse|ocamlformat|janestreet}
           Select a preset profile which sets all options, overriding lower
           priority configuration. The conventional profile aims to be as
           familiar and "conventional" appearing as the available options
           allow. default is an alias for the conventional profile. 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
           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 janestreet
           profile is used at Jane Street. The default value is default.

       --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. The flag is unset by default.

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

       --use-file
           Deprecated. Same as impl.

       --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.