Overview

Sublime Text plugin for auto-formatting arbitrary code by calling arbitrary executables. Works for gofmt, rustfmt, any similar tool that's an executable and uses standard input/output.

Features:

• Format on demand. Optionally auto-format on save.
• Configure executables and other settings per scope (syntax type: source.go, source.rust and so on).
• Optionally preserve cursor and scroll position when formatting, via "merge_type": "diff".
• Show errors in an output panel (configurable).
• Format either an entire file, or only selection.
  • Selection formatting works for embedded syntaxes, such as JS inside HTML.

Limitations:

• Invokes a subprocess every time. Good enough for formatters written in compiled languages, such as gofmt and rustfmt. If a given formatter is written in JS and takes a second to start up, this tool might not be suitable.

Based on https://github.com/mitranim/sublime-gofmt and fully replaces it. Also replaces RustFmt and countless others.

Why

Why this exists?

Package Control has special-case formatter plugins for different languages, and the monstrous Formatter with too many batteries included. This makes it hard to add formatters: someone has to make and publish a new plugin every time, or fork a repo and make a PR, etc.

Many formatters just call a subprocess and use stdio. One plugin can handle them all, while letting the user specify any new formatter for any new syntax! This works for gofmt, rustfmt, clang-format, and endless others.

Installation

Package Control

1. Get Package Control.
2. Open the command palette: ⇪⌘P or ⇪^P.
3. Package Control: Install Package.
4. Fmt.

Manual

Clone the repo and symlink it to your Sublime packages directory. Example for MacOS:

git clone https://github.com/mitranim/sublime-fmt.git
cd sublime-fmt
ln -sf "$(pwd)" "$HOME/Library/Application Support/Sublime Text 3/Packages/Fmt"

To find the packages directory on your system, use Sublime Text menu → Preferences → Browse Packages.

Usage

The plugin has no default formatters. It invokes CLI programs installed globally on your system. You must specify them in the plugin settings. Example for Go:

{
  "rules": [
    {
      "selector": "source.go",
      "cmd": ["goimports"],
      "format_on_save": true,
      "merge_type": "diff",
    },
  ],
}

To understand Sublime scopes and selector matching, read this short official doc: https://www.sublimetext.com/docs/selectors.html.

How to get scope name. Option 1: menu → Tools → Developer → Show Scope Name. Option 2: run the command Fmt: Format Buffer, and if not configured for the current scope, it will tell you!

To format on demand, run the Fmt: Format Buffer command from the command palette. See below how to configure hotkeys.

To auto-format on save, set "format_on_save": true in the settings. Can be global or per rule.

Settings

See Fmt.sublime-settings for all available settings. To override them, open:

menu → Preferences → Package Settings → Fmt → Settings

The plugin looks for settings in the following places, with the following priority:

• "Fmt" dict in general Sublime settings, project-specific or global.
• Fmt.sublime-settings, user-created or default.

For overrides, open project or global settings and make a "Fmt" entry:

{
  "Fmt": {
    "rules": [
      {
        "selector": "source.some_lang",
        "cmd": ["some_lang_fmt", "--some_arg"],
      },
    ],
  },
}

A rule may contain any of the root-level settings, such as format_on_save. This allows fine-tuning.

Commands

In Sublime's command palette:

• Fmt: Format Buffer
• Fmt: Format Selection

Hotkeys

Hotkeys? More like notkeys!

To avoid potential conflicts, this plugin does not come with hotkeys. To hotkey the format commands, add something like this to your .sublime-keymap:

{"keys": ["primary+k", "primary+j"], "command": "fmt_format_buffer"},
{"keys": ["primary+k", "primary+k"], "command": "fmt_format_selection"},

Sublime automatically resolves "primary" to "super" on MacOS and to "ctrl" on other systems.

Changelog

2022-07-18. Ignore informational output over stderr when the subprocess exits with 0 and stdout is non-empty.

2022-07-11. Use "merge_type": "replace" by default. Diff is now opt-in due to extreme performance degradation for large amounts of diffs.

2020-12-28. Support env variable substitution. Format-on-save is no longer enabled by default.

2020-11-26. Support variable substitution in cmd.

2020-11-25. Use scope selectors instead of exactly matching the scope name.

2020-10-25. Support subprocess timeout, always kill the subprocess.

2020-10-23. Support several ways of printing errors. By default, errors are shown in a transient output panel at the bottom.

License

https://unlicense.org

difflib.py is based on code which is published under Apache license, see the hyperlink in the file. It underwent significant edits, and its licensing status is unknown to me. Everything else is original and under Unlicense.