OCAMLFORMAT(1)

📦
version 0.29.0 · 5 versions
, in nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 ocamlformat(1) — from the Ocamlformat Manual 🎀

👑 NAME

ocamlformat — A tool to format OCaml code.

✨ SYNOPSIS

ocamlformat [OPTION]… [SRC]…

🌈 DESCRIPTION

okay bestie, ocamlformat automatically formats OCaml code. That's the whole vibe. ✨

💅 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, applied from top to bottom, overriding the settings each time a file is applied, stopping at the project root. If no project root and no ocamlformat file has been found, and if the option enable-outside-detected-project is set, the global ocamlformat file defined in $XDG_CONFIG_HOME (or in $HOME/.config if $XDG_CONFIG_HOME is undefined) is used.

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.

  • --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|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. vertical vertically breaks branches. 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-colon={after|before} — Break before or after colon in value binding declarations and type constraints. after breaks after the colon. before breaks before the colon. The default value is after.
  • --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|wrap-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. wrap-or-vertical behaves like wrap for high precedence operators and behaves like fit-or-vertical for low precedence operators. 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 and sig-end items. force will break items unconditionally. natural will break items 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.
  • --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={preserve|parens} — Style of expression grouping. preserve preserves the original grouping syntax (parentheses or begin/end). parens groups expressions using parentheses. The default value is preserve. Cannot be set in attributes.
  • --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 punctuation symbol (: or =) preceding the rhs. This option affects records and objects. loose uses a space. tight does not use a space. 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|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. vertical always vertically breaks branches. 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} ✨ — do we flag nested or-patterns with indentation or nah? unsafe-no literally does not indicate nested or-patterns at all. Warning incoming bestie: 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 "| ". Default? unsafe-no, iykyk.
  • --infix-precedence={indent|parens} 💅 — disambiguate precedences of infix operators, but how? indent uses indentation to explicitly disambiguate precedences of infix operators. parens uses parentheses to explicitly disambiguate precedences of infix operators. Default is indent.
  • --leading-nested-match-parens 🎀 — nested match parens formatting, periodt. 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. Default is compact.
  • --let-binding-deindent-fun 🦋 — deindent a line beginning with fun. Set by default (so yes babe, it's on).
  • --let-binding-indent=COLS — indentation of let binding expressions (COLS columns) if they don't fit on a single line. Default is 2. Cannot be set in attributes.
  • --let-binding-spacing={compact|sparse|double-semicolon} 🌸 — spacing between let bindings. 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. Default 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. Default is compact.
  • --letop-punning={preserve|always|never} 💜 — name punning in bindings using extended let operators and let%ext bindings. preserve uses let-punning only when it exists in the source; the code "let* foo and* z = z in ..." will be left unchanged. always uses let-punning whenever possible; the code "let* foo and* z = z in ..." will be rewritten to "let* foo and* z in ...". never never uses let-punning (yes, never means never bestie); the code "let* foo and* z = z in ..." will be rewritten to "let* foo = foo and* z = z in ...". Default is preserve.
  • --line-endings={lf|crlf} 🌈 — line endings used. lf uses Unix line endings. crlf uses Windows line endings. Default is lf. Cannot be set in attributes.
  • -m COLS, --margin=COLS — format code to fit within COLS columns. Default is 80. Cannot be set in attributes.
  • --match-indent=COLS — indentation of match/try cases (COLS columns). Default is 0.
  • --match-indent-nested={never|always|auto} ✨ — should the match-indent parameter be applied even when we're in a sub-block? never only applies match-indent if the match block starts a line. always always applies match-indent (shocking, I know). auto applies match-indent when seen fit. Default is never.
  • --max-indent=COLS — maximum offset (COLS columns) added to a new line in addition to the offset of the previous line. Default is 68. Cannot be set in attributes.
  • --module-indent=COLS — indentation of items within struct ... end and sig ... end (COLS columns). Default is 2.
  • --module-item-spacing={compact|sparse|preserve} 🫶 — spacing between items of structures and signatures. compact will not leave open lines between one-liners of similar sorts. 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. Default is compact.
  • --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. Default is wrap.
  • --no-break-infix-before-func — unset break-infix-before-func.
  • --no-break-sequences — unset break-sequences.
  • --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-let-binding-deindent-fun — unset let-binding-deindent-fun.
  • --no-ocp-indent-compat — unset ocp-indent-compat.
  • --no-parens-ite — unset parens-ite.
  • --no-parse-docstrings — unset parse-docstrings.
  • --no-parse-toplevel-phrases — unset parse-toplevel-phrases.
  • --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.
  • --ocp-indent-compat 🦋 — attempt to generate output which does not change (much) when post-processing with ocp-indent. The flag is unset by default.
  • -p {default|conventional|ocamlformat|janestreet}, --profile={default|conventional|ocamlformat|janestreet} 👑 — select a preset profile which sets all options, overriding lower priority configuration. default is an alias for the conventional profile. The conventional profile aims to be as familiar and "conventional" appearing as the available options allow. 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. Default value is 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. Default 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. Default is multi-line-only.
  • --parse-docstrings 🌸 — parse and format docstrings. The flag is set by default.
  • --parse-toplevel-phrases — parse and format toplevel phrases and their output. 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. Default 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. Default 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. Default 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). Default 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. Default is compact.
  • --type-decl-indent=COLS — indentation of type declarations (COLS columns) if they do not fit on a single line. Default is 2. Cannot be set in attributes.
  • --wrap-comments 🫶 — comments 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 — so this one's off unless you turn it on, bestie.
  • --wrap-fun-args — style for function call. The flag is set by default.

💀 OPTIONS (REMOVED) 💀

okay bestie, buckle up, because this is the graveyard section 🪦✨ these options literally do not exist anymore. if you're copying a config from 2019 off some blog, this is why it's screaming at you.

  • --align-cases=VALUE — this option has been removed in version 0.22. gone. bye. 🫶
  • --align-constructors-decl=VALUE — this option has been removed in version 0.22. no cap.
  • --align-variants-decl=VALUE — this option has been removed in version 0.22. it's giving deleted.
  • --doc-comments-val=VALUE — this option has been removed in version 0.16. and here's the migration lore, bestie, because it's a whole flowchart 😭:
    • if you were using doc-comments-val=before together with doc-comments=before, then now you only need doc-comments=before to achieve the same behavior.
    • if you were using doc-comments-val=before together with doc-comments=after, that behavior is not available anymore. periodt.
    • if you were using doc-comments-val=after together with doc-comments=before, please now use doc-comments=before-except-val.
    • if you were using doc-comments-val=after together with doc-comments=after, then now you only need doc-comments=after-when-possible to achieve the same behavior.
    • if you were using doc-comments-val=unset, the same behavior can now be achieved by setting doc-comments only.
  • --escape-chars=VALUE — this option has been removed in version 0.16. concrete syntax will now always be preserved. so you literally never have to think about it again 💅
  • --escape-strings=VALUE — this option has been removed in version 0.16. concrete syntax will now always be preserved.
  • --extension-sugar=VALUE — this option has been removed in version 0.17. concrete syntax will now always be preserved.
  • --let-open=VALUE — this option has been removed in version 0.17. concrete syntax will now always be preserved.

✨ OPTIONS ✨

heads up bestie: unless the docs say otherwise, non-formatting options cannot be set in attributes or in .ocamlformat files. iykyk.
  • -c =[,…], --config==[,…] (absent OCAMLFORMAT env) — the aggregate option, the group-chat of options 🫶. you pass a comma-separated list of pairs like this: option=VAL,...,option=VAL.
  • --check — checks whether the input files are already formatted. mutually exclusive with --inplace and --output (pick a lane, bestie 😤).
  • --comment-check — controls whether comments and documentation comments get checked. unsafe to turn off. may be set in .ocamlformat. the flag is set by default.
  • --disable — disables ocamlformat. this is the one you drop into attributes to locally turn off automatic code formatting. you can also use [@@@ocamlformat "enable"] instead of [@@@ocamlformat "disable=false"]. the flag is unset by default.
  • --disable-conf-attrs — disables configuration in attributes. the flag is unset by default.
  • --disable-conf-files — disables .ocamlformat configuration files. no config files, no notes 💅
  • --disable-outside-detected-project — if no .ocamlformat config files have been detected, disable the formatting. OCamlFormat is disabled outside of a detected project by default, so if you want the opposite behavior, use --enable-outside-detected-project.
  • --doc — parse input as an odoc documentation.
  • --enable-outside-detected-project — read .ocamlformat config files outside the current project when no project root has been detected for the input file. so like, 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. if .ocamlformat config files are located in the same directory or in parents, they get applied; and if no .ocamlformat file is found, then the global configuration defined in $XDG_CONFIG_HOME/.ocamlformat (or in $HOME/.config/.ocamlformat if $XDG_CONFIG_HOME is undefined) is applied. the whole ancestry chain, iconic 🌈
  • -g, --debug — generate debugging output. the flag is unset by default.
  • -i, --inplace — format in-place, overwriting your input file(s). yes it really does just write over them, bestie 🙈
  • --ignore-invalid-option — ignore invalid options (e.g. in .ocamlformat). forgiveness era 🕊️
  • --impl — parse input as an implementation.
  • --intf — parse input as an interface.
  • --margin-check — emit a warning if the formatted output exceeds the margin. the flag is unset by default.
  • -n N, --max-iters=N — fail if the output of formatting does not stabilize within N iterations. may be set in .ocamlformat. the default value is 10.
  • --name=NAME — the name of the input file, used for error reporting and as the 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 the documentation of the other options for details.
  • --no-comment-check — unset comment-check.
  • --no-debug — unset debug.
  • --no-disable — unset disable.
  • --no-disable-conf-attrs — unset disable-conf-attrs.
  • --no-margin-check — unset margin-check.
  • --no-quiet — unset quiet.
  • --no-version-check — unset version-check.
  • -o DST, --output=DST — output file. mutually exclusive with --inplace. writes to stdout if omitted (the default girlie behavior ✨).
  • --ocaml-version=V — the version of OCaml syntax of the output. the default value is 5.4.0.
  • --ocp-indent-config — read .ocp-indent configuration files. here's the translation table, study it bestie, there's a quiz later 😌:
    • 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.
  • --print-config — print the configuration determined by the environment variable, the configuration files, preset profiles and the command line. attributes are not considered. if many input files are specified, it only prints the configuration for the first file. and if no input file is specified, it prints 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.
  • --repl-file — parse input as toplevel phrases with their output.
  • --root=DIR — the root of the project. if specified, only .ocamlformat configuration files inside DIR and its subdirectories are taken into account.
  • --use-file — deprecated. same as impl.
  • --version-check — check that the version matches the one specified in .ocamlformat. the flag is set by default.
  • SRC — the input files. at least one is required, and exactly one is required without --inplace. if - is passed, it will read from stdin 🫶

🌸 COMMON OPTIONS 🌸

  • --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.
  • --version — show version information.

🎀 EXIT STATUS 🎀

ocamlformat exits with:

  • 0 — on success. we love a win ✨
  • 123 — on indiscriminate errors reported on standard error.
  • 124 — on command line parsing errors.
  • 125 — on unexpected internal errors (bugs).

🦋 ENVIRONMENT 🦋

these environment variables affect the execution of ocamlformat:

  • OCAMLFORMAT — see option --config.

and that's a wrap on the whole page, bestie!! you now know ocamlformat better than it knows itself 💖 this was Ocamlformat 0.29.0, and you just read the OCAMLFORMAT(1) manual page. go forth and format, you absolute icon 👑💅🫶

📦 where this page comes from