Skip to content

Commit

Permalink
Proper documentation
Browse files Browse the repository at this point in the history 
Also removes the --help section from readme. It's too much.
  • Loading branch information
@gustavohenke
gustavohenke committed Sep 3, 2024
1 parent 009981f commit 3c42827
Show file tree
Hide file tree
Showing 12 changed files with 438 additions and 237 deletions.
241 changes: 4 additions & 237 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ tired of opening terminals and made **concurrently**.
## Usage

> **Note**
> The `concurrently` command is now also available under the shorthand alias `conc`.
> The `concurrently` command is also available under the shorthand alias `conc`.
The tool is written in Node.js, but you can use it to run **any** commands.

Expand All @@ -73,243 +73,10 @@ In package.json, escape quotes:
"start": "concurrently \"command1 arg\" \"command2 arg\""
```

NPM run commands can be shortened:
You can always check concurrently's flag list by running `concurrently --help`.
For the version, run `concurrently --version`.

```bash
concurrently "npm:watch-js" "npm:watch-css" "npm:watch-node"

# Equivalent to:
concurrently -n watch-js,watch-css,watch-node "npm run watch-js" "npm run watch-css" "npm run watch-node"
```

NPM shortened commands also support wildcards. Given the following scripts in
package.json:

```jsonc
{
//...
"scripts": {
// ...
"watch-js": "...",
"watch-css": "...",
"watch-node": "..."
// ...
}
// ...
}
```

```bash
concurrently "npm:watch-*"

# Equivalent to:
concurrently -n js,css,node "npm run watch-js" "npm run watch-css" "npm run watch-node"

# Any name provided for the wildcard command will be used as a prefix to the wildcard
# part of the script name:
concurrently -n w: npm:watch-*

# Equivalent to:
concurrently -n w:js,w:css,w:node "npm run watch-js" "npm run watch-css" "npm run watch-node"
```

Exclusion is also supported. Given the following scripts in package.json:

```jsonc
{
// ...
"scripts": {
"lint:js": "...",
"lint:ts": "...",
"lint:fix:js": "...",
"lint:fix:ts": "..."
// ...
}
// ...
}
```

```bash
# Running only lint:js and lint:ts
# with lint:fix:js and lint:fix:ts excluded
concurrently "npm:lint:*(!fix)"
```

Good frontend one-liner example [here](https://github.com/kimmobrunfeldt/dont-copy-paste-this-frontend-template/blob/5cd2bde719654941bdfc0a42c6f1b8e69ae79980/package.json#L9).

Help:

```
concurrently [options] <command ...>
General
-m, --max-processes How many processes should run at once.
Exact number or a percent of CPUs available (for example "50%").
New processes only spawn after all restart tries
of a process. [string]
-n, --names List of custom names to be used in prefix
template.
Example names: "main,browser,server" [string]
--name-separator The character to split <names> on. Example usage:
-n "styles|scripts|server" --name-separator "|"
[default: ","]
-s, --success Which command(s) must exit with code 0 in order
for concurrently exit with code 0 too. Options
are:
- "first" for the first command to exit;
- "last" for the last command to exit;
- "all" for all commands;
- "command-{name}"/"command-{index}" for the
commands with that name or index;
- "!command-{name}"/"!command-{index}" for all
commands but the ones with that name or index.
[default: "all"]
-r, --raw Output only raw output of processes, disables
prettifying and concurrently coloring. [boolean]
--no-color Disables colors from logging [boolean]
--hide Comma-separated list of processes to hide the
output.
The processes can be identified by their name or
index. [string] [default: ""]
-g, --group Order the output as if the commands were run
sequentially. [boolean]
--timings Show timing information for all processes.
[boolean] [default: false]
-P, --passthrough-arguments Passthrough additional arguments to commands
(accessible via placeholders) instead of treating
them as commands. [boolean] [default: false]
Prefix styling
-p, --prefix Prefix used in logging for each process.
Possible values: index, pid, time, command, name,
none, or a template. Example template: "{time}-{pid}"
[string] [default: index or name (when --names is set)]
-c, --prefix-colors Comma-separated list of chalk colors to use on
prefixes. If there are more commands than colors, the
last color will be repeated.
- Available modifiers: reset, bold, dim, italic,
underline, inverse, hidden, strikethrough
- Available colors: black, red, green, yellow, blue,
magenta, cyan, white, gray,
any hex values for colors (e.g. #23de43) or auto for
an automatically picked color
- Available background colors: bgBlack, bgRed,
bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite
See https://www.npmjs.com/package/chalk for more
information. [string] [default: "reset"]
-l, --prefix-length Limit how many characters of the command is displayed
in prefix. The option can be used to shorten the
prefix when it is set to "command"
[number] [default: 10]
-t, --timestamp-format Specify the timestamp in moment/date-fns format.
[string] [default: "yyyy-MM-dd HH:mm:ss.SSS"]
Input handling
-i, --handle-input Whether input should be forwarded to the child
processes. See examples for more information.
[boolean]
--default-input-target Identifier for child process to which input on
stdin should be sent if not specified at start of
input.
Can be either the index or the name of the
process. [default: 0]
Killing other processes
-k, --kill-others Kill other processes if one exits or dies.[boolean]
--kill-others-on-fail Kill other processes if one exits with non zero
status code. [boolean]
--kill-signal Signal to send to other processes if one exits or dies.
(SIGTERM/SIGKILL, defaults to SIGTERM) [string]
Restarting
--restart-tries How many times a process that died should restart.
Negative numbers will make the process restart forever.
[number] [default: 0]
--restart-after Delay time to respawn the process, in milliseconds.
[number] [default: 0]
Options:
-h, --help Show help [boolean]
-v, -V, --version Show version number [boolean]
Examples:
- Output nothing more than stdout+stderr of child processes
$ concurrently --raw "npm run watch-less" "npm run watch-js"
- Normal output but without colors e.g. when logging to file
$ concurrently --no-color "grunt watch" "http-server" > log
- Custom prefix
$ concurrently --prefix "{time}-{pid}" "npm run watch" "http-server"
- Custom names and colored prefixes
$ concurrently --names "HTTP,WATCH" -c "bgBlue.bold,bgMagenta.bold"
"http-server" "npm run watch"
- Auto varying colored prefixes
$ concurrently -c "auto" "npm run watch" "http-server"
- Mixing auto and manual colored prefixes
$ concurrently -c "red,auto" "npm run watch" "http-server" "echo hello"
- Configuring via environment variables with CONCURRENTLY_ prefix
$ CONCURRENTLY_RAW=true CONCURRENTLY_KILL_OTHERS=true concurrently "echo
hello" "echo world"
- Send input to default
$ concurrently --handle-input "nodemon" "npm run watch-js"
rs # Sends rs command to nodemon process
- Send input to specific child identified by index
$ concurrently --handle-input "npm run watch-js" nodemon
1:rs
- Send input to specific child identified by name
$ concurrently --handle-input -n js,srv "npm run watch-js" nodemon
srv:rs
- Shortened NPM run commands
$ concurrently npm:watch-node npm:watch-js npm:watch-css
- Shortened NPM run command with wildcard (make sure to wrap it in quotes!)
$ concurrently "npm:watch-*"
- Exclude patterns so that between "lint:js" and "lint:fix:js", only "lint:js"
is ran
$ concurrently "npm:*(!fix)"
- Passthrough some additional arguments via '{<number>}' placeholder
$ concurrently -P "echo {1}" -- foo
# Results in: echo foo
- Passthrough all additional arguments via '{@}' placeholder
$ concurrently -P "npm:dev-* -- {@}" -- --watch --noEmit
# Results in something like: npm run dev-example -- --watch --noEmit
- Passthrough all additional arguments combined into one argument via '{*}' placeholder
$ concurrently -P "echo {*}" -- foo bar
# Results in: echo 'foo bar'
For more details, visit https://github.com/open-cli-tools/concurrently
```
Check out documentation and other usage examples in the [`docs` directory](./docs/README.md).

## API

Expand Down
13 changes: 13 additions & 0 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Concurrently Documentation

## CLI

These articles cover using concurrently through CLI:

- [Prefixing](./cli/prefixing.md)
- [Output Control](./cli/output-control.md)
- [Shortcuts](./cli/shortcuts.md)
- [Restarting Commands](./cli/restarting.md)
- [Input Handling](./cli/input-handling.md)
- [Passthrough Arguments](./cli/passthrough-arguments.md)
- [Configuration](./cli/configuration.md)
11 changes: 11 additions & 0 deletions docs/cli/configuration.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Configuration

You might want to configure concurrently to always have certain flags on.
Any of concurrently's flags can be set via environment variables that are prefixed with `CONCURRENTLY_`.

```bash
$ export CONCURRENTLY_KILL_OTHERS=true
$ export CONCURRENTLY_HANDLE_INPUT=true
# Equivalent to passing --kill-others and --handle-input
$ concurrently nodemon "echo 'hey nodemon, you won't last long'"
```
40 changes: 40 additions & 0 deletions docs/cli/input-handling.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Input Handling

By default, concurrently doesn't send input to any commands it spawns.<br/>
In the below example, typing `rs` to manually restart [nodemon](https://nodemon.io/) does nothing:

```bash
$ concurrently "nodemon" "npm run watch-js"
rs
```

To turn on input handling, it's necessary to set the `--handle-input`/`-i` flag.<br/>
This will send `rs` to the first command:

```bash
$ concurrently --handle-input "nodemon" "npm run watch-js"
rs
```

To send input to a different command instead, it's possible to prefix the input with the command index, followed by a `:`.<br/>
For example, the below sends `rs` to the second command:

```bash
$ concurrently --handle-input "npm run watch-js" "nodemon"
1:rs
```

If the command has a name, it's also possible to target it using that command's name:

```bash
$ concurrently --handle-input --names js,server "npm run watch-js" "nodemon"
server:rs
```

It's also possible to change the default command that receives input.<br/>
To do this, set the `--default-input-target` flag to a command's index or name.

```bash
$ concurrently --handle-input --default-input-target 1 "npm run watch-js" "nodemon"
rs
```
35 changes: 35 additions & 0 deletions docs/cli/output-control.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Output Control

concurrently offers a few ways to control a command's output.

## Hiding

A command's outputs (and all its events) can be hidden by using the `--hide` flag.

```bash
$ concurrently --hide 0 "echo Hello there" "echo 'General Kenobi!'"
[1] General Kenobi!
[1] echo 'General Kenobi!' exited with code 0
```

## Grouping

It might be useful at times to make sure that the commands outputs are grouped together, while running them in parallel.<br/>
This can be done with the `--group` flag.

```bash
$ concurrently --group "echo Hello there && sleep 2 && echo 'General Kenobi!'" "echo hi Star Wars fans"
[0] Hello there
[0] General Kenobi!
[0] echo Hello there && sleep 2 && echo 'General Kenobi!' exited with code 0
[1] hi Star Wars fans
[1] echo hi Star Wars fans exited with code 0
```

## No Colors

When piping concurrently's outputs to another command or file, you might want to force it to not use colors, as these can break the other command's parsing, or reduce the legibility of the output in non-terminal environments.

```bash
$ concurrently -c red,blue --no-color "echo Hello there" "echo 'General Kenobi!'"
```
Loading

0 comments on commit 3c42827

Please sign in to comment.