152 lines
5.1 KiB
Markdown
152 lines
5.1 KiB
Markdown
would-reformat - automatic reformatting for emacs without being annoying
|
|
|
|
# Motivation
|
|
|
|
I've never liked it when a text editor formats code for me without my asking.
|
|
I don't like it when the editor uses cheap heuristics (indent a new line to
|
|
match the previous one? blah!) and I don't like it when the editor shells out
|
|
to one of the new generation of automatic code formatters.
|
|
|
|
But I don't enjoy formatting code by hand either. Who does?
|
|
|
|
This is my solution: some shell scripts and some emacs lisp code.
|
|
|
|
The shell script `would-reformat.sh` takes a file's full path as
|
|
its argument. It tells you if that file would be reformatted.
|
|
|
|
The shell script `do-reformat.sh` takes a file's full path as its argument. It
|
|
reformats the file.
|
|
|
|
Finally, there is some rudimentary machinery to run `would-reformat.sh` when
|
|
saving a file and to run `do-reformat.sh` when you hit `<F1>`.
|
|
|
|
## Supported programming languages and file formats
|
|
|
|
<!-- please keep this list sorted alphabetically -->
|
|
|
|
- css
|
|
- dart
|
|
- go
|
|
- html
|
|
- javascript
|
|
- jsx
|
|
- php
|
|
- python
|
|
- scss
|
|
- sh
|
|
- tsx
|
|
- typescript
|
|
- vue
|
|
|
|
Out of the box, python uses `isort` and `black`, go uses `gofmt`, and dart
|
|
uses `dart format`. The rest use `prettier`. Adding new programming
|
|
languages is easy, assuming they have a formatter with a dry run mode.
|
|
|
|
# Installation
|
|
|
|
- Change to the directory where you want to use `would-reformat`:
|
|
`you@host:~ $ cd ~/devel/my-project`
|
|
- From that directory, call the script `install.sh` in the directory where
|
|
you have `would-reformat` checked out:
|
|
`you@host:~/devel/my-project $ ~/src/would-reformat/install.sh`
|
|
|
|
Be sure to run the installation script from the root of your project's
|
|
directory, not a subdirectory.
|
|
|
|
This will do the following:
|
|
|
|
- create the directory `~/devel/my-project/bin` if it does not exist
|
|
- create `~/devel/my-project/bin/_reformat-common.sh`,
|
|
`~/devel/my-project/bin/do-reformat.sh`, and
|
|
`~/devel/my-project/bin/would-reformat.sh` as symlinks to files with
|
|
the same names in `~/src/would-reformat`.
|
|
- create `~/devel/my-project/.dir-locals.el` as a symlink to the file
|
|
with the same name in `~/src/would-reformat`.
|
|
|
|
This should work from a checkout wherever you happen to have it. It doesn't
|
|
need to be in `~/src`. However, if you remove the checkout, then the symlinks
|
|
will break, so don't do that. If you rename the checkout, the symlinks will
|
|
break.
|
|
|
|
The directory `bin` with respect to `my-project` however is hardcoded
|
|
(enhancements here are welcome).
|
|
|
|
The script `install.sh` favors conservatism over cleverness: for example,
|
|
if it finds the file `~/devel/my-project/bin/do-reformat.sh` then it
|
|
checks whether it is a symlink to `~/src/would-reformat/do-reformat.sh`.
|
|
If it is not, then it just prints a warning rather than attempting to correct
|
|
the situation.
|
|
|
|
FIXME: Document how to reinstall if the checkout was moved, incompatible
|
|
changes were made, etc.
|
|
|
|
# Customization
|
|
|
|
For information on changing how `would-format` handles different files, see
|
|
[CUSTOMIZATION.md](CUSTOMIZATION.md).
|
|
|
|
|
|
# Development
|
|
|
|
If you want to hack on `would-format`, see [DEVELOPMENT.md](DEVELOPMENT.md)
|
|
for more info.
|
|
|
|
# Troubleshooting
|
|
|
|
## nothing works from emacs
|
|
|
|
Be sure to run the install script from your project's root as determined by
|
|
`(projectile-project-root)`.
|
|
|
|
## problems with nvm, pyenv, goenv, etc
|
|
|
|
The problem might be that their shims aren't in your `PATH`. To work around
|
|
this sort of problem I run emacs from a wrapper script that ensures the shims
|
|
are loaded in my `PATH`.
|
|
|
|
## Running prettier is slow
|
|
|
|
The scripts by default call `npx prettier` with some arguments. If you call
|
|
these scripts from a directory where there's a `node_modules/` directory with
|
|
prettier and plugins, if necessary, installed, then `npx` should be fast
|
|
enough.
|
|
|
|
The solution, therefore, seems to be to say `yarn add --dev prettier` (or
|
|
`npm install --dev prettier`) in the right place.
|
|
|
|
(This seems to work for me, but it is admittedly still uncomfortably
|
|
cargoculty. There should be a more solid basis for this answer.)
|
|
|
|
## problems running black
|
|
|
|
The solution seems to be to run `pip install black pipx` somewhere.
|
|
|
|
## I need to use one version of `would-reformat` with one of my projects and another with another
|
|
|
|
With the per-project configuration [see below] this should rarely be
|
|
necessary, but in case it is, one thing you can try is creating different
|
|
`would-reformat` checkouts for different projects. For example, something
|
|
like this might work:
|
|
|
|
```
|
|
$ ls ~/devel
|
|
new-project1 new-project2 old-and-weird-project1
|
|
$ git clone https://github.com/maw/would-reformat
|
|
$ cd new-project1; ../would-reformat/install.sh
|
|
$ cd ../new-project2; ../would-reformat/install.sh
|
|
$ cd ..
|
|
$ git clone https://github.com/maw/would-reformat would-reformat-for-old-and-weird-project1
|
|
$ cd would-reformat-for-old-and-weird-project1; git checkout vSome-old-tag
|
|
$ cd ../old-and-weird-project1; ../would-reformat-for-old-and-weird-project1/install.sh
|
|
```
|
|
|
|
|
|
# Similar projects
|
|
|
|
If you don't like `would-reformat`'s approach, maybe one or more of these
|
|
would be more suitable.
|
|
|
|
- https://github.com/purcell/emacs-shfmt/
|
|
- https://github.com/pythonic-emacs/blacken
|
|
- https://github.com/dominikh/go-mode.el
|