Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shelljs/shx
Portable Shell Commands for Node
https://github.com/shelljs/shx
bash shelljs unix
Last synced: 5 days ago
JSON representation
Portable Shell Commands for Node
- Host: GitHub
- URL: https://github.com/shelljs/shx
- Owner: shelljs
- License: mit
- Created: 2016-02-14T19:53:03.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2024-12-20T22:59:01.000Z (22 days ago)
- Last Synced: 2024-12-31T01:15:25.996Z (12 days ago)
- Topics: bash, shelljs, unix
- Language: JavaScript
- Size: 211 KB
- Stars: 1,733
- Watchers: 19
- Forks: 47
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome - shelljs/shx - Portable Shell Commands for Node (JavaScript)
- stars - shelljs/shx
- my-awesome-list - shx
- awesome-nodejs - shx - Portable Shell Commands for Node.  (Repository / Shell)
README
# Shx
[](https://github.com/shelljs/shx/actions/workflows/main.yml)
[](https://codecov.io/gh/shelljs/shx)
[](https://www.npmjs.com/package/shx)
[](https://www.npmjs.com/package/shx)
`shx` is a wrapper around [ShellJS](https://github.com/shelljs/shelljs) Unix
commands, providing an easy solution for simple Unix-like, cross-platform
commands in npm package scripts.
`shx` is proudly tested on every node release since `v6`!
## Difference Between ShellJS and shx
- **ShellJS:** Good for writing long scripts, all in JS, running via NodeJS (e.g. `node myScript.js`).
- **shx:** Good for writing one-off commands in npm package scripts (e.g. `"clean": "shx rm -rf out/"`).
## Install
```shell
npm install shx --save-dev
```
This will allow using `shx` in your `package.json` scripts.
## Usage
### Command Line
If you'd like to use `shx` on the command line, install it globally with the `-g` flag.
The following code can be run *either a Unix or Windows* command line:
```Bash
$ shx pwd # ShellJS commands are supported automatically
/home/username/path/to/dir
$ shx ls # files are outputted one per line
file.txt
file2.txt
$ shx rm *.txt # a cross-platform way to delete files!
$ shx ls
$ shx echo "Hi there!"
Hi there!
$ shx touch helloworld.txt
$ shx cp helloworld.txt foobar.txt
$ shx mkdir sub
$ shx ls
foobar.txt
helloworld.txt
sub
$ shx rm -r sub # options work as well
$ shx --silent ls fakeFileName # silence error output
```
All commands internally call the ShellJS corresponding function, guaranteeing
cross-platform compatibility.
### package.json
ShellJS is good for writing long scripts. If you want to write bash-like,
platform-independent scripts, we recommend you go with that.
However, `shx` is ideal for one-liners inside `package.json`:
```json
{
"scripts": {
"clean": "shx rm -rf \"build/**/*.js\" \"build/output\" && shx echo \"Done cleaning\""
}
}
```
It's safe to use `&&` and `||` operators in npm package scripts. These will be
interpreted by the operating system's shell (`sh` on Unix, `cmd.exe` on
Windows). If you're using glob operators like `*` or `**`, then we recommend to
**put these in double quotes**, which ensures that `shx` will expand the glob
rather than the operating system shell.
> [!IMPORTANT]
> 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 **escaped double quotes** so that your code is
> compatible cross platform (ex. `"clean": "shx echo \"some string\""`).
## 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 `shx`. Due to the
differences in execution environments between ShellJS and `shx` (JS vs CLI) the
following commands are not supported:
| Unsupported command | Recommend workaround |
| ------------------- | -------------------- |
| `shx cd` | Just use plain old `cd` (it's the same on windows too) |
| `shx pushd` | Just use plain old `pushd`. Use forward slashes and double-quote the path. (e.g. `pushd "../docs"`. This would fail on Windows without the quotes) |
| `shx popd` | Just use plain old `popd` |
| `shx dirs` | No workaround |
| `shx set` | See below |
| `shx exit` | Just use plain old `exit` |
| `shx exec` | Instead of `shx exec cmd`, just use plain old `cmd` |
| `shx ShellString` | No workaround (but why would you want this?) |
### Shx options
Shx allows you to modify its behavior by passing arguments. Here's a list of
supported options:
| [`set`](https://github.com/shelljs/shelljs#setoptions) flag | [`shell.config`](https://github.com/shelljs/shelljs#configuration) setting | shx command | Effect |
|:---:| --- | --- | --- |
| `-e` | `config.fatal = true` | Not supported | Exit upon first error |
| `-v` | `config.verbose = true` | `shx --verbose cd foo` | Log the command as it's run |
| `-f` | `config.noglob = true` | `shx --noglob cat '*.txt'` | Don't expand wildcards |
| N/A | `config.silent = true` | `shx --silent cd noexist` | Don't show error output |
## Team
| [](https://github.com/nfischer) | [](http://github.com/ariporad) | [](https://github.com/levithomason) |
|:---:|:---:|:---:|
| [Nate Fischer](https://github.com/nfischer) | [Ari Porad](http://github.com/ariporad) | [Levi Thomason](https://github.com/levithomason) |