Fmt

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).
• Preserve cursor and scroll position when formatting.
• Show errors in an output panel (configurable).

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. You must specify them in the plugin settings. Example for Go:

{
  "rules": [
    {"selector": "source.go", "cmd": ["goimports"]},
  },
}

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

Hotkeys

Hotkeys? More like notkeys!

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

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

This will trigger on a quick ⌘kj or ^kj depending on your OS.

Changelog

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