Skip to content

Commit

Permalink
docs(sed): document sed syntax, quoting, and escaping slash (#170)
Browse files Browse the repository at this point in the history
No change to logic, only docs.

This documents the special sed syntax (ex. `shx sed s/foo/bar/g
filename.txt`). With that, this mentions that `/` is a special
character, so the user must escape that if it's present in either the
regex or replacement string.

This also documents how Windows handles single quotes differently, so
it's desirable to avoid single quotes in package.json scripts. This part
isn't specific to sed, but since it's popular to quote sed expressions,
I'm adding this to the docs at the same time.

Fixes #165
Fixes #169
  • Loading branch information
nfischer authored Dec 9, 2019
1 parent e5c1513 commit 7e7bf7f
Showing 1 changed file with 37 additions and 2 deletions.
39 changes: 37 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,9 +80,44 @@ However, `shx` is ideal for one-liners inside `package.json`:
}
```

## Unsupported Commands
**Tip:** because Windows treats single quotes (ex. `'some string'`) differently
than double quotes, [we
recommend](https://github.com/shelljs/shx/issues/165#issuecomment-563127983)
wrapping your arguments in double quotes for cross platform compatibility (ex.
`"some string"`).

Due to the differences in execution environments between ShellJS and `shx` (JS vs CLI) some commands are not supported:
## Command reference

Shx exposes [most ShellJS
commands](https://github.com/shelljs/shelljs#command-reference). If a command is
not listed here, assume it's supported!

### sed

Shx provides unix-like syntax on top of `shell.sed()`. So ShellJS code like:

```js
shell.sed('-i', /original string/g, 'replacement', 'filename.txt');
```

would turn into the following Shx command:

```sh
shx sed -i "s/original string/replacement/g" filename.txt
```

**Note:** like unix `sed`, `shx sed` treats `/` as a special character, and
[this must be
escaped](https://github.com/shelljs/shx/issues/169#issuecomment-563013849) (as
`\/` in the shell, or `\\/` in `package.json`) if you intend to use this
character in either the regex or replacement string. Do **not** escape `/`
characters in the file path.

### Unsupported Commands

As mentioned above, most ShellJS commands are supported in ShellJS. Due to the
differences in execution environments between ShellJS and `shx` (JS vs CLI) the
following commands are not supported:

| Unsupported command | Recommend workaround |
| ------------------- | -------------------- |
Expand Down

0 comments on commit 7e7bf7f

Please sign in to comment.