Skip to content

Commit

Permalink
doc: update doc for stdin
Browse files Browse the repository at this point in the history
fix #305
  • Loading branch information
HerringtonDarkholme committed Dec 18, 2023
1 parent f8c5b92 commit 25d9d51
Show file tree
Hide file tree
Showing 3 changed files with 6 additions and 8 deletions.
10 changes: 4 additions & 6 deletions website/guide/tooling-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,20 +149,18 @@ You can invoke sg, the command-line interface for ast-grep, as a subprocess to s
**All the following conditions** must be met to enable StdIn mode:

1. The command line argument flag `--stdin` is passed.
2. The environment variable `AST_GREP_NO_STDIN` is **NOT** set. Otherwise it will disable StdIn mode.
3. ast-grep is not running inside a [tty](https://github.com/softprops/atty). If you are using a terminal emulator, ast-grep will usually run in a tty if invoked directly from CLI.
2. ast-grep is **NOT** running inside a [tty](https://github.com/softprops/atty). If you are using a terminal emulator, ast-grep will usually run in a tty if invoked directly from CLI.

The first two conditions are quite self explanatory. However, it should be noted that many cases are not tty, for example:
The first condition is quite self explanatory. However, it should be noted that many cases are not tty, for example:

* ast-grep is invoked by other program as subprocess.
* ast-grep is running inside [GitHub Action](https://github.com/actions/runner/issues/241).
* ast-grep is used as the second program of a bash pipe `|`.

So you have to use `--stdin` to avoid unintentional StdIn mode and unexpected error.

:::danger Breaking Change
Older ast-grep will detect tty and automatically enable StdIn mode. It turns out to be too easy to break. So parsing code from StdIn becomes an opt-in mode.
See related [discussion](https://github.com/ast-grep/ast-grep/discussions/500).
:::danger Running ast-grep in tty with --stdin
ast-grep will hang there if you run it in a tty terminal session with `--stdin` flag, until you type in some text and send EOF signal (usually `Ctrl-D`).
:::

#### Bonus Example
Expand Down
2 changes: 1 addition & 1 deletion website/reference/cli/run.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ Possible values:

Enable search code from StdIn.

Use this if you need to take code stream from standard input. If the environment variable `AST_GREP_NO_STDIN` exist, ast-grep will disable StdIn mode.
Use this if you need to take code stream from standard input.

## Output Options

Expand Down
2 changes: 1 addition & 1 deletion website/reference/cli/scan.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Possible values:

Enable search code from StdIn.

Use this if you need to take code stream from standard input. If the environment variable `AST_GREP_NO_STDIN` exist, ast-grep will disable StdIn mode.
Use this if you need to take code stream from standard input.

## Output Options

Expand Down

0 comments on commit 25d9d51

Please sign in to comment.