Skip to content

Commit 45f9ef9

Browse files
reesereese
authored
Reorganize the README (#810)
* Update the README * Move pronunciation guide to the top
1 parent bbdf291 commit 45f9ef9

File tree

1 file changed

+114
-64
lines changed

1 file changed

+114
-64
lines changed

‎README.md‎

Lines changed: 114 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,162 @@
1-
# How do I pronounce `rubyfmt`
2-
* en: Ruby format
3-
* jp: ルビーフォーマット
1+
# rubyfmt
42

5-
## Maintenance policy
3+
A fast, opinionated Ruby formatter written in Rust.
64

7-
* I (fables-tales) am no longer working in spare time on open source
8-
* Folks who have commit bits are free to merge anything they'd like as long as it passes CI
9-
* I review important patches for my day job at request of a co-worker
5+
- Try it online → [rubyfmt.run](https://rubyfmt.run)
106

11-
## How do I use it
7+
Pronunciation: (en) "Ruby Format", (jp) ルビーフォーマット
128

9+
## Quick Start
1310

14-
### Install from `brew`
11+
```bash
12+
# Install
13+
brew install rubyfmt
14+
15+
# Format a file in place
16+
rubyfmt -i myfile.rb
17+
18+
# Format and print to stdout
19+
rubyfmt myfile.rb
20+
```
1521

16-
On Mac and Linux, `rubyfmt` can be installed with [Homebrew](https://brew.sh/):
22+
## Installation
23+
24+
### Homebrew
1725

1826
```bash
1927
brew install rubyfmt
2028
```
2129

22-
### Build from source
30+
### Build from Source
2331

24-
1. Make sure you've got cargo installed
25-
2. Run `make all`
26-
3. Copy target/release/rubyfmt-main to somewhere on your path as `rubyfmt`
32+
1. Make sure you have Cargo installed
33+
2. Run `cargo build --release`
34+
3. Copy `target/release/rubyfmt-main` to somewhere on your path as `rubyfmt`
2735

28-
Rubyfmt supports the following CLI invocations:
36+
## Usage
2937

30-
* `<whatever> | rubyfmt` pipe from standard in
31-
* `rubyfmt -i -- files or directories` to format files and directories in place
32-
* `rubyfmt -- files or directories` output rubyfmtted code to STDOUT.
33-
* `rubyfmt -c -- files or directories` output a diff of input and rubyformatted input.
34-
* `rubyfmt --header-opt-in -- files or directories` to format files only with a `# rubyfmt: true` comment at the top of the file
35-
* `rubyfmt --header-opt-out -- files or directories` to skip formatting files with a `# rubyfmt: false` comment at the top of the file
38+
### Command Line
3639

37-
`rubyfmt` also supports ignoring files with a `.rubyfmtignore` file when present in the root of the working directory.
38-
`.rubyfmtignore` uses the same syntax as `.gitignore`, so you can choose to ignore whole directories or use globs as needed.
39-
By default, `rubyfmt` also ignores files in `.gitignore` during file traversal, but you can force these files to be formatted by using the `--include-gitignored` flag.
40+
| Command | Description |
41+
| ------------------------ | ------------------------------- |
42+
| `rubyfmt file.rb` | Output formatted code to stdout |
43+
| `rubyfmt -i file.rb` | Format file in place |
44+
| `rubyfmt -c file.rb` | Show diff of changes |
45+
| `cat file.rb \| rubyfmt` | Read from stdin |
4046

41-
## Editor Support
47+
You can also pass directories to format multiple files at once.
4248

43-
### Vim
49+
For the full command line interface, see `rubyfmt --help`.
4450

45-
We aren't currently tested with any vim plugin managers, however, adding the
46-
plugin from a git clone is fairly easy:
51+
### Header Comments
4752

48-
* Run `cargo build --release`
49-
* Add `source /path/to/rubyfmt.vim` to your `~/.vimrc` (e.g. [my dotfiles](https://github.com/penelopezone/dotfiles/commit/2c0e9c1215de368e64e063021e9523aa349c5454#diff-2152fa38b4d8bb10c75d6339a959650dR253) please note, this line is commented)
50-
* Add `let g:rubyfmt_path = /path/to/target/release/rubyfmt-main` beneath the source line
53+
Control formatting on a per-file basis with header comments:
5154

52-
### Neovim + LSP + null-ls
55+
- `rubyfmt --header-opt-in` - Only format files with `# rubyfmt: true` at the top
56+
- `rubyfmt --header-opt-out` - Skip files with `# rubyfmt: false` at the top
5357

54-
If you use the popular [null-ls](https://github.com/jose-elias-alvarez/null-ls.nvim) LSP plugin to manage formatters, it supports `rubyfmt` out of the box. You can add the formatter to your existing `setup()` configuration:
58+
### Ignoring Files
5559

56-
```diff
57-
local null_ls = require("null-ls")
60+
Create a `.rubyfmtignore` file in your project root to exclude files from formatting. It uses the same syntax as `.gitignore`.
5861

59-
null_ls.setup({
60-
sources = {
61-
+ null_ls.builtins.formatting.rubyfmt,
62-
},
63-
})
64-
```
62+
By default, rubyfmt also respects your `.gitignore`. Use `--include-gitignored` to format those files anyway.
6563

66-
Read more in the [null-ls documentation](https://github.com/jose-elias-alvarez/null-ls.nvim/blob/main/doc/BUILTINS.md#rubyfmt).
64+
## Editor Integration
6765

6866
### Visual Studio Code
6967

70-
Rubyfmt is a supported formatter in the popular
71-
[vscode ruby extension](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby).
72-
You should copy `rubyfmt-main` to be called `rubyfmt` on your PATH .
73-
Once installed, add the following to vscode's `settings.json` file:
68+
The popular [`ruby-lsp` extension](https://marketplace.visualstudio.com/items?itemName=Shopify.ruby-lsp) has a [rubyfmt add-on](https://github.com/reese/ruby-lsp-rubyfmt-formatter). Install the extension:
69+
70+
```bash
71+
# Add to project
72+
bundle add ruby-lsp-rubyfmt-formatter --group development
73+
74+
# Install globally
75+
gem install ruby-lsp-rubyfmt-formatter
76+
```
77+
78+
And then add the following to your `.vscode/settings.json`:
79+
80+
```json
81+
{
82+
"[ruby]": {
83+
"editor.defaultFormatter": "Shopify.ruby-lsp",
84+
"editor.formatOnSave": true
85+
},
86+
"rubyLsp.formatter": "rubyfmt"
87+
}
88+
```
89+
90+
Rubyfmt is also supported by the (now-deprecated) [VSCode Ruby extension](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby). Add the following to your `settings.json`:
7491

75-
``` json
92+
```json
93+
{
7694
"ruby.useLanguageServer": true,
7795
"ruby.format": "rubyfmt",
7896
"[ruby]": {
79-
"editor.formatOnSave": true
97+
"editor.formatOnSave": true
98+
}
99+
}
100+
```
101+
102+
### Neovim + null-ls
103+
104+
The [null-ls](https://github.com/jose-elias-alvarez/null-ls.nvim) plugin supports rubyfmt out of the box:
105+
106+
```lua
107+
null_ls.setup({
108+
sources = {
109+
null_ls.builtins.formatting.rubyfmt,
80110
},
111+
})
81112
```
82113

83-
### RubyMine (and similar Jetbrains family IDE)
114+
See the [null-ls documentation](https://github.com/jose-elias-alvarez/null-ls.nvim/blob/main/doc/BUILTINS.md#rubyfmt) for more details.
84115

85-
[Install](https://www.jetbrains.com/help/ruby/settings-tools-file-watchers.html) the File Watchers plugin and go to `File | Settings | Tools | File Watchers`. Now import `watchers.xml` from `editor_plugins/rubymine/`. Optionally set `Level` to `Global` to have it available across all projects.
116+
### Vim
117+
118+
1. Run `cargo build --release`
119+
2. Add `source /path/to/rubyfmt.vim` to your `~/.vimrc`
120+
3. Add `let g:rubyfmt_path = /path/to/target/release/rubyfmt-main` beneath the source line
121+
122+
### RubyMine (and JetBrains IDEs)
86123

87-
See [this reference](https://www.jetbrains.com/help/ruby/using-file-watchers.html#ws_filewatcher_type_and_location_of_input_files) on using file watchers to learn more.
124+
1. Install the [File Watchers plugin](https://www.jetbrains.com/help/ruby/settings-tools-file-watchers.html)
125+
2. Go to File | Settings | Tools | File Watchers
126+
3. Import `watchers.xml` from `editor_plugins/rubymine/`
127+
4. Optionally set Level to Global for all projects
128+
129+
See the [File Watchers documentation](https://www.jetbrains.com/help/ruby/using-file-watchers.html#ws_filewatcher_type_and_location_of_input_files) for more details.
88130

89131
### Sublime Text
90132

91-
Install the [rubyfmt plugin](https://github.com/toreriklinnerud/sublime-rubyfmt/) from [Package Control](https://packagecontrol.io): Install Package -> rubyfmt.
133+
Install the [rubyfmt plugin](https://github.com/toreriklinnerud/sublime-rubyfmt/) via Package Control.
92134

93-
Ruby files are formatted on save or by pressing `Alt + ;` or on macOS: `Cmd + ;`. `rubyfmt` is assumed to be on path.
135+
Files format on save or with `Cmd + ;` (macOS) / `Alt + ;` (other). Settings:
94136

95-
Overridable default settings:
96-
``` json
97-
{
98-
"ruby_executable": "ruby",
99-
"rubyfmt_executable": "rubyfmt",
100-
"format_on_save": true,
101-
}
102-
```
137+
```json
138+
{
139+
"ruby_executable": "ruby",
140+
"rubyfmt_executable": "rubyfmt",
141+
"format_on_save": true
142+
}
143+
```
103144

104-
### Atom
145+
### Atom
105146

106147
Install the [rubyfmt package](https://github.com/toreriklinnerud/atom-rubyfmt/) from Settings > Packages.
107148

108-
Ruby files are formatted on save or by pressing `Alt + ;` or on macOS: `Cmd + ;` `rubyfmt` is assumed to be on path. See the package settings for more options.
149+
Files format on save or with `Cmd + ;` (macOS) / `Alt + ;` (other).
150+
151+
## Rubocop
152+
153+
For usage with Rubocop, see the [rubocop-rubyfmt](https://github.com/reese/rubocop-rubyfmt) gem.
109154

110155
## Contributing
111156

112-
Please checkout [our contributing guide](./CONTRIBUTING.md)
157+
Please check out our [contributing guide](./CONTRIBUTING.md).
158+
159+
## Maintenance Status
160+
161+
The original author (fables-tales) is no longer working on open source in their spare time.
162+
Other contributors work regularly on `rubyfmt`, and contributors with commit access are welcome to merge changes that pass CI.

0 commit comments

Comments
 (0)