rubyfmt

You can control whether rubyfmt processes specific files by using header comments at the top of the file. This is useful for opting in or out of formatting on a per-file basis.

• Use the flag --header-opt-in to only format files that contain # rubyfmt: true at the top.
• Use the flag --header-opt-out to skip files that contain # rubyfmt: false at the top.

1. Install the rubyfmt plugin via Package Control.
2. Configure your settings:

{
  "ruby_executable": "ruby",
  "rubyfmt_executable": "rubyfmt",
  "format_on_save": true
}

Files can be formatted on save or via keyboard shortcuts: Cmd + ; (macOS) or Alt + ; (other platforms).

To use rubyfmt in RubyMine, you must use the File Watchers plugin:

1. Install the File Watchers plugin.
2. Navigate to File | Settings | Tools | File Watchers.
3. Import the provided watchers.xml file located in the repository at editor_plugins/rubymine/watchers.xml.
4. (Optional) Set the Level to Global to apply it to all projects.

If you use the null-ls plugin in Neovim, rubyfmt is supported as a built-in source.

null_ls.setup({
  sources = {
    null_ls.builtins.formatting.rubyfmt,
  },
})

There are several ways to use rubyfmt in VS Code:

Using ruby-lsp (Recommended)

1. Add the ruby-lsp-rubyfmt-formatter gem to your project or install it globally:

   bundle add ruby-lsp-rubyfmt-formatter --group development
   # OR
   gem install ruby-lsp-rubyfmt-formatter

2. Update .vscode/settings.json:

   {
     "[ruby]": {
       "editor.defaultFormatter": "Shopify.ruby-lsp",
       "editor.formatOnSave": true
     },
     "rubyLsp.formatter": "rubyfmt"
   }

Using Formatto for VS Code

1. Install the Formatto for VS Code extension.
2. Update .vscode/settings.json:

   {
     "[ruby]": {
       "editor.defaultFormatter": "damolinx.formatto"
     }
   }

You can install rubyfmt via Homebrew or by building it from source.

Homebrew

brew install rubyfmt

Build from Source

1. Ensure cargo is installed.
2. Run cargo build --release.
3. Copy target/release/rubyfmt-main to a directory in your PATH and rename it to rubyfmt.

Using vim-plug

Plug 'fables-tales/rubyfmt', { 'rtp': 'editor_plugins/vim' }

Native packages

git clone https://github.com/fables-tales/rubyfmt ~/.rubyfmt
ln -s ~/.rubyfmt/editor_plugins/vim ~/.vim/pack/rubyfmt/start/rubyfmt

Note: If rubyfmt is not in your $PATH, set the g:rubyfmt_path variable in your Vim configuration.

rubyfmt provides two ways to ignore files:

1. .rubyfmtignore: Create a .rubyfmtignore file in your project root. It uses the same syntax as .gitignore.
2. .gitignore: By default, rubyfmt respects your .gitignore. To format files that are normally ignored by git, use the --include-gitignored flag.

By default, rubyfmt respects .gitignore and .rubyfmtignore patterns to skip files.

• Default behavior: Files matched by .gitignore or .rubyfmtignore are ignored.
• Including gitignored files: Use the --include-gitignored flag to force rubyfmt to process files that would otherwise be ignored by git.
• Custom ignore file: rubyfmt specifically looks for a .rubyfmtignore file in the current working directory.

You can opt-in or opt-out of formatting for specific Ruby files using magic comments in the file header. This is useful when you want to preserve specific formatting in certain files.

To use these, you must run rubyfmt with the corresponding flags:

• Use --header-opt-in to only format files containing # rubyfmt: true.
• Use --header-opt-out to skip files containing # rubyfmt: false.

The magic comment must appear within the first 500 bytes of the file.

rubyfmt is a fast, opinionated Ruby formatter. You can format individual files, directories, or use stdin.

Common Commands

• Format and print to stdout: rubyfmt file.rb or cat file.rb | rubyfmt
• Format in place: rubyfmt -i file.rb (overwrites the file)
• Show diff: rubyfmt -c file.rb (shows changes without applying them)

You can pass directories to format multiple files at once.

# Format a file in place
rubyfmt -i myfile.rb

# Format and print to stdout
rubyfmt myfile.rb

# Read from stdin
cat file.rb | rubyfmt