Editor setup

Enable formatting outside project

OCamlFormat detects your current project if there is a .git, a .hg or a dune-project file in one of the ancestry directories. For more details, read about how OCamlFormat finds its root project and computes its configuration.

By default, when the option --enable-outside-detected-project is not set, .ocamlformat files outside of the current project (including the one in XDG_CONFIG_HOME) are not read. If no configuration file is found, then the formatting is disabled.

This feature is often the behavior you can expect from OCamlFormat when it is directly run from your text editor.

If however you wish to format files that stand clear of any project you will need to pass the option --enable-outside-detected-project.

Emacs setup

• add $(opam config var share)/emacs/site-lisp to load-path (as done by opam user-setup install)

• add (require 'ocamlformat) to .emacs

• optionally add the following to .emacs to bind C-M-<tab> to the ocamlformat command and install a hook to run OCamlFormat when saving:

  (add-hook 'tuareg-mode-hook (lambda ()
    (define-key tuareg-mode-map (kbd "C-M-<tab>") #'ocamlformat)
    (add-hook 'before-save-hook #'ocamlformat-before-save)))

To pass the option --enable-outside-detected-project (or --disable) to OCamlFormat:

• run emacs
• run M-x customize-group⏎ then enter ocamlformat⏎
• select the Ocamlformat Enable item
• select the OCamlformat mode in the Value Menu: Enable (by default), Disable or Enable outside detected project
• save the buffer (C-x C-s) then enter yes⏎ and exit

Other OCamlFormat options can be set in .ocamlformat configuration files.

With use-package

A basic configuration with use-package:

(use-package ocamlformat
  :custom (ocamlformat-enable 'enable-outside-detected-project)
  :hook (before-save . ocamlformat-before-save)
  )

Sometimes you need to have a switch for OCamlFormat (because of version conflicts or because you don't want to install it in every switch, for example). Considering your OCamlFormat switch is named ocamlformat:

(use-package ocamlformat
  :load-path
  (lambda ()
    (concat
         ;; Never use "/" or "\" since this is not portable (opam-user-setup does this though)
         ;; Always use file-name-as-directory since this will append the correct separator if needed
         ;; (or use a package that does it well like https://github.com/rejeep/f.el)
         ;; This is the verbose and not package depending version:
         (file-name-as-directory
          ;; Couldn't find an option to remove the newline so a substring is needed
          (substring (shell-command-to-string "opam config var share --switch=ocamlformat --safe") 0 -1))
         (file-name-as-directory "emacs")
         (file-name-as-directory "site-lisp")))
  :custom
  (ocamlformat-enable 'enable-outside-detected-project)
  (ocamlformat-command
   (concat
    (file-name-as-directory
     (substring (shell-command-to-string "opam config var bin --switch=ocamlformat --safe") 0 -1))
    "ocamlformat"))
  :hook (before-save . ocamlformat-before-save)
  )

(Notice the :custom to customize the OCamlFormat binary)

This could be made simpler (by defining an elisp variable corresponding to the switch prefix when loading tuareg, for example) but it allows to have a full configuration in one place only which is often less error prone.

Vim setup

• be sure the ocamlformat binary can be found in PATH

• install the Neoformat plugin

Optional: You can change the options passed to OCamlFormat (to use the option --enable-outside-detected-project for example), you can customize NeoFormat with:

let g:opambin = substitute(system('opam config var bin'),'\n$','','''')
let g:neoformat_ocaml_ocamlformat = {
            \ 'exe': g:opambin . '/ocamlformat',
            \ 'no_append': 1,
            \ 'stdin': 1,
            \ 'args': ['--enable-outside-detected-project', '--name', '"%:p"', '-']
            \ }

let g:neoformat_enabled_ocaml = ['ocamlformat']

Format on save using entr

Alternatively, you may want to see your files reformatted on save. If you are running on Linux or macOS, you may enable this workflow easily regardless of your editor by using entr:

# `apt install entr` or `brew install entr`
find ./bin ./test -name "*.ml*" | entr -p ocamlformat --inplace /_