First draft of a diff-friendly profile

CHANGES.md

@@ -25,6 +25,7 @@
 
 - Add a `break-colon` option to decide whether to break before or after the `:` symbol in value binding declarations and type constraints. This behavior is no longer ensured by `ocp-indent-compat`. (#2149, @gpetiot)
 - Format `.mld` files as odoc documentation files (#2008, @gpetiot)
+- New profile: `diff-friendly`. This profile aims to minimize the vertical diff. The code is formatted in a "unfolded" style such that locally modifying parts of the code has a minimal impact on the surrounding lines. (#2020, @gpetiot)
 
 ## 0.24.1 (2022-07-18)
 

lib/Conf.ml

@@ -17,7 +17,8 @@ type fmt_opts =
   { align_pattern_matching_bar: [`Paren | `Keyword]
   ; assignment_operator: [`Begin_line | `End_line]
   ; break_before_in: [`Fit_or_vertical | `Auto]
-  ; break_cases: [`Fit | `Nested | `Toplevel | `Fit_or_vertical | `All]
+  ; break_cases:
+      [`Fit | `Nested | `Toplevel | `Fit_or_vertical | `Unfold | `All]
   ; break_collection_expressions: [`Wrap | `Fit_or_vertical]
   ; break_colon: [`Before | `After]
   ; break_infix: [`Wrap | `Fit_or_vertical]
@@ -40,7 +41,8 @@ type fmt_opts =
   ; field_space: [`Tight | `Loose | `Tight_decl]
   ; function_indent: int
   ; function_indent_nested: [`Always | `Auto | `Never]
-  ; if_then_else: [`Compact | `Fit_or_vertical | `Keyword_first | `K_R]
+  ; if_then_else:
+      [`Compact | `Fit_or_vertical | `Unfold | `Keyword_first | `K_R]
   ; indent_after_in: int
   ; indicate_multiline_delimiters: [`No | `Space | `Closing_on_separate_line]
   ; indicate_nested_or_patterns: [`Space | `Unsafe_no]
@@ -272,6 +274,8 @@ module Formatting = struct
       ; C.Value.make ~name:"fit-or-vertical" `Fit_or_vertical
           "$(b,fit-or-vertical) tries to fit all or-patterns on the same \
            line, otherwise breaks."
+      ; C.Value.make ~name:"unfold" `Unfold
+          "$(b,unfold) unfolds each branch."
       ; C.Value.make ~name:"all" `All
           "$(b,all) forces all pattern matches to break across lines." ]
     in
@@ -662,6 +666,8 @@ module Formatting = struct
       ; C.Value.make ~name:"fit-or-vertical" `Fit_or_vertical
           "$(b,fit-or-vertical) vertically breaks branches if they do not \
            fit on a single line."
+      ; C.Value.make ~name:"unfold" `Unfold
+          "$(b,unfold) always vertically breaks branches."
       ; C.Value.make ~name:"keyword-first" `Keyword_first
           "$(b,keyword-first) formats if-then-else expressions such that \
            the if-then-else keywords are the first on the line."
@@ -1559,6 +1565,69 @@ let conventional_profile =
 
 let default_profile = conventional_profile
 
+let diff_friendly_profile =
+  { align_pattern_matching_bar= `Keyword
+  ; assignment_operator= `End_line
+  ; break_before_in= `Fit_or_vertical
+  ; break_cases= `Unfold
+  ; break_collection_expressions= `Fit_or_vertical
+  ; break_colon= `After
+  ; break_infix= `Fit_or_vertical
+  ; break_infix_before_func= true
+  ; break_fun_decl= `Fit_or_vertical
+  ; break_fun_sig= `Fit_or_vertical
+  ; break_separators= `After
+  ; break_sequences= true
+  ; break_string_literals= `Auto
+  ; break_struct= true
+  ; cases_exp_indent= 4
+  ; cases_matching_exp_indent= `Compact
+  ; disambiguate_non_breaking_match= false
+  ; doc_comments= `Before_except_val
+  ; doc_comments_padding= 2
+  ; doc_comments_tag_only= `Default
+  ; dock_collection_brackets= true
+  ; exp_grouping= `Parens
+  ; extension_indent= 2
+  ; field_space= `Tight
+  ; function_indent= 2
+  ; function_indent_nested= `Never
+  ; if_then_else= `Unfold
+  ; indent_after_in= 0
+  ; indicate_multiline_delimiters= `Closing_on_separate_line
+  ; indicate_nested_or_patterns= `Unsafe_no
+  ; infix_precedence= `Indent
+  ; leading_nested_match_parens= false
+  ; let_and= `Sparse
+  ; let_binding_indent= 2
+  ; let_binding_spacing= `Compact
+  ; let_module= `Sparse
+  ; line_endings= `Lf
+  ; margin= 80
+  ; match_indent= 0
+  ; match_indent_nested= `Never
+  ; max_indent= None
+  ; module_item_spacing= `Sparse
+  ; nested_match= `Wrap
+  ; ocp_indent_compat= false
+  ; parens_ite= false
+  ; parens_tuple= `Always
+  ; parens_tuple_patterns= `Multi_line_only
+  ; parse_docstrings= false
+  ; parse_toplevel_phrases= false
+  ; sequence_blank_line= `Compact
+  ; sequence_style= `Separator
+  ; single_case= `Sparse
+  ; space_around_arrays= false
+  ; space_around_lists= false
+  ; space_around_records= false
+  ; space_around_variants= false
+  ; stritem_extension_indent= 0
+  ; type_decl= `Sparse
+  ; type_decl_indent= 2
+  ; wrap_comments= false
+  ; wrap_fun_args= false }
+
 let janestreet_profile =
   { align_pattern_matching_bar= `Keyword
   ; assignment_operator= `Begin_line
@@ -1637,6 +1706,11 @@ let profile =
          \"conventional\" appearing as the available options allow."
     ; C.Value.make ~name:"default" (Some default_profile)
         "$(b,default) is an alias for the $(b,conventional) profile."
+    ; C.Value.make ~name:"diff-friendly" (Some diff_friendly_profile)
+        "The $(b,diff_friendly) profile aims to minimize the vertical diff. \
+         The code is formatted in a \"unfolded\" style such that locally \
+         modifying parts of the code has a minimal impact on the \
+         surrounding lines."
     ; C.Value.make ~name:"ocamlformat" (Some ocamlformat_profile)
         "The $(b,ocamlformat) profile aims to take advantage of the \
          strengths of a parsetree-based auto-formatter, and to limit the \

lib/Conf.mli

@@ -16,7 +16,8 @@ type fmt_opts =
   { align_pattern_matching_bar: [`Paren | `Keyword]
   ; assignment_operator: [`Begin_line | `End_line]
   ; break_before_in: [`Fit_or_vertical | `Auto]
-  ; break_cases: [`Fit | `Nested | `Toplevel | `Fit_or_vertical | `All]
+  ; break_cases:
+      [`Fit | `Nested | `Toplevel | `Fit_or_vertical | `Unfold | `All]
   ; break_collection_expressions: [`Wrap | `Fit_or_vertical]
   ; break_colon: [`Before | `After]
   ; break_infix: [`Wrap | `Fit_or_vertical]
@@ -40,7 +41,8 @@ type fmt_opts =
   ; field_space: [`Tight | `Loose | `Tight_decl]
   ; function_indent: int
   ; function_indent_nested: [`Always | `Auto | `Never]
-  ; if_then_else: [`Compact | `Fit_or_vertical | `Keyword_first | `K_R]
+  ; if_then_else:
+      [`Compact | `Fit_or_vertical | `Unfold | `Keyword_first | `K_R]
   ; indent_after_in: int
   ; indicate_multiline_delimiters: [`No | `Space | `Closing_on_separate_line]
   ; indicate_nested_or_patterns: [`Space | `Unsafe_no]

lib/Fmt_ast.ml

@@ -1128,6 +1128,7 @@ and fmt_pattern ?ext c ?pro ?parens ?(box = false)
         match c.conf.fmt_opts.break_cases with
         | `Fit_or_vertical -> open_hvbox
         | `Fit | `Nested | `Toplevel | `All -> open_hovbox
+        | `Unfold -> open_vbox
       in
       hvbox 0
         ( list_fl (List.group xpats ~break)

lib/Params.ml

@@ -71,7 +71,9 @@ let get_or_pattern_sep ?(cmts_before = false) ?(space = false) (c : Conf.t)
     | `Nested -> break nspaces 0 $ str "| "
     | _ -> (
         let nspaces =
-          match c.fmt_opts.break_cases with `All -> 1000 | _ -> nspaces
+          match c.fmt_opts.break_cases with
+          | `All | `Unfold -> 1000
+          | _ -> nspaces
         in
         match c.fmt_opts.indicate_nested_or_patterns with
         | `Space ->
@@ -154,6 +156,16 @@ let get_cases (c : Conf.t) ~first ~indent ~parens_branch ~xbch =
       ; open_paren_branch
       ; break_after_opening_paren= fmt "@ "
       ; close_paren_branch }
+  | `Unfold ->
+      { leading_space= break_unless_newline 1000 0
+      ; bar= str "| "
+      ; box_all= hvbox indent
+      ; box_pattern_arrow= hovbox 0
+      ; break_before_arrow= fmt "@;<1 2>"
+      ; break_after_arrow= fmt_if (not parens_branch) "@;<0 3>"
+      ; open_paren_branch
+      ; break_after_opening_paren= break 1000 0
+      ; close_paren_branch }
 
 let wrap_collec c ~space_around opn cls =
   if space_around then wrap_k (str opn $ char ' ') (break 1 0 $ str cls)
@@ -427,6 +439,29 @@ let get_if_then_else (c : Conf.t) ~first ~last ~parens ~parens_bch
             ( match imd with
             | `Closing_on_separate_line when beginend || parens_bch -> " "
             | _ -> "@ " ) }
+  | `Unfold ->
+      { box_branch=
+          hovbox
+            ( match imd with
+            | `Closing_on_separate_line when parens_prev_bch -> -2
+            | _ -> 0 )
+      ; cond= cond ()
+      ; box_keyword_and_expr= Fn.id
+      ; branch_pro
+      ; wrap_parens=
+          wrap_parens
+            ~wrap_breaks:
+              (get_parens_breaks
+                 ~opn_hint:((1, 2), (0, 2))
+                 ~cls_hint:((1, 0), (1000, 0)) )
+      ; expr_pro= Some (break_unless_newline 1000 2)
+      ; expr_eol= Some (fmt "@;<1 2>")
+      ; break_end_branch= noop
+      ; space_between_branches=
+          fmt
+            ( match imd with
+            | `Closing_on_separate_line when parens_bch -> " "
+            | _ -> "@ " ) }
   | `Keyword_first ->
       { box_branch= Fn.id
       ; cond=

ocamlformat-help.txt

@@ -59,16 +59,16 @@ OPTIONS (CODE FORMATTING STYLE)
            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-cases={fit|nested|toplevel|fit-or-vertical|unfold|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.
+           otherwise breaks. unfold unfolds each branch. 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
@@ -195,14 +195,14 @@ OPTIONS (CODE FORMATTING STYLE)
            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={compact|fit-or-vertical|unfold|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.
+           branches if they do not fit on a single line. unfold 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
@@ -349,14 +349,17 @@ OPTIONS (CODE FORMATTING STYLE)
            Attempt to generate output which does not change (much) when
            post-processing with ocp-indent. The flag is unset by default.
 
-       -p {conventional|default|ocamlformat|janestreet},
-       --profile={conventional|default|ocamlformat|janestreet}
+       -p {conventional|default|diff-friendly|ocamlformat|janestreet},
+       --profile={conventional|default|diff-friendly|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
-           ocamlformat profile aims to take advantage of the strengths of a
-           parsetree-based auto-formatter, and to limit the consequences of
+           diff_friendly profile aims to minimize the vertical diff. The code
+           is formatted in a "unfolded" style such that locally modifying
+           parts of the code has a minimal impact on the surrounding lines.
+           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

test/passing/dune.inc

@@ -4711,6 +4711,24 @@
  (package ocamlformat)
  (action (diff tests/skip.ml.err skip.ml.stderr)))
 
+(rule
+ (deps tests/.ocamlformat )
+ (package ocamlformat)
+ (action
+  (with-stdout-to source-diff-friendly.ml.stdout
+   (with-stderr-to source-diff-friendly.ml.stderr
+     (run %{bin:ocamlformat} --margin-check --profile=diff-friendly --max-iters=3 %{dep:tests/source.ml})))))
+
+(rule
+ (alias runtest)
+ (package ocamlformat)
+ (action (diff tests/source-diff-friendly.ml.ref source-diff-friendly.ml.stdout)))
+
+(rule
+ (alias runtest)
+ (package ocamlformat)
+ (action (diff tests/source-diff-friendly.ml.err source-diff-friendly.ml.stderr)))
+
 (rule
  (deps tests/.ocamlformat )
  (package ocamlformat)

test/passing/tests/option.ml.err

@@ -17,12 +17,12 @@ File "tests/option.ml", line 28, characters 3-14:
 28 | [@@ocamlformat "if-then-else=bad"]
         ^^^^^^^^^^^
 Warning 47 [attribute-payload]: illegal payload for attribute 'ocamlformat'.
-For option "if-then-else": invalid value 'bad', expected one of 'compact', 'fit-or-vertical', 'keyword-first' or 'k-r'
+For option "if-then-else": invalid value 'bad', expected one of 'compact', 'fit-or-vertical', 'unfold', 'keyword-first' or 'k-r'
 File "tests/option.ml", line 39, characters 14-25:
 39 |            [@@ocamlformat "if-then-else=bad"]
                    ^^^^^^^^^^^
 Warning 47 [attribute-payload]: illegal payload for attribute 'ocamlformat'.
-For option "if-then-else": invalid value 'bad', expected one of 'compact', 'fit-or-vertical', 'keyword-first' or 'k-r'
+For option "if-then-else": invalid value 'bad', expected one of 'compact', 'fit-or-vertical', 'unfold', 'keyword-first' or 'k-r'
 Warning: tests/option.ml:36 exceeds the margin
 Warning: tests/option.ml:44 exceeds the margin
 Warning: tests/option.ml:51 exceeds the margin

test/passing/tests/source-diff-friendly.ml.err

@@ -0,0 +1,3 @@
+Warning: tests/source.ml:5411 exceeds the margin
+Warning: tests/source.ml:7199 exceeds the margin
+Warning: tests/source.ml:8124 exceeds the margin

test/passing/tests/source-diff-friendly.ml.opts

@@ -0,0 +1,2 @@
+--profile=diff-friendly
+--max-iters=3