Skip to main content

Opt-out comments

Two comments tell dfmt to leave a region of a file exactly as written. They are not an option: they live in the file, next to the SQL they protect.

  • -- fmt:off ... -- fmt:on: everything between the two is reproduced byte for byte. Without a matching fmt:on, the rest of the file is.
  • -- fmt:ignore: the next statement only.

The block-comment spellings /* fmt:off */ and /* fmt:on */ work the same way.

Use them for SQL whose layout carries information the formatter cannot see: a values table laid out as a grid, a hand-aligned CASE that documents a mapping, generated SQL that will be regenerated. Prefer fmt:ignore for a single statement; it cannot be left open by mistake.

A region​

The statements on either side are deliberately untidy, so you can see them being reformatted while the marked region is left exactly as written.

select   a ,  b   from t where x=1;
-- fmt:off
select    b    from   t2;
-- fmt:on
select   c ,  d   from   t3 where y   =  2
select a, b from t where x = 1;

-- fmt:off
select    b    from   t2;
-- fmt:on

select c, d from t3 where y = 2

One statement​

select   a ,  b   from t where x=1;
-- fmt:ignore
select    b    from   t2;
select   c ,  d   from   t3 where y   =  2
select a, b from t where x = 1;

-- fmt:ignore
select    b    from   t2;

select c, d from t3 where y = 2