docs: add some notes on use_stdin and interactive options

docs/configuration.md

@@ -42,6 +42,7 @@
   - [`fail_text`](#fail_text)
   - [`stage_fixed`](#stage_fixed)
   - [`interactive`](#interactive)
+  - [`use_stdin`](#use_stdin)
 - [Script](#script)
   - [`runner`](#runner)
   - [`skip`](#skip)
@@ -51,6 +52,7 @@
   - [`fail_text`](#fail_text)
   - [`stage_fixed`](#stage_fixed)
   - [`interactive`](#interactive)
+  - [`use_stdin`](#use_stdin)
 - [Examples](#examples)
 - [More info](#more-info)
 
@@ -1045,7 +1047,14 @@ pre-commit:
 
 **Default: `false`**
 
-Whether to use interactive mode and provide a STDIN for a command or script.
+Whether to use interactive mode. This applies the certain behavior:
+- All `interactive` commands/scripts are executed after non-interactive.
+- When executing, lefthook tries to open /dev/tty (Linux/Unix only) and use it as stdin.
+- When [`no_tty`](#no_tty) option is set, `interactive` is ignored.
+
+**Note**
+
+If you want to pass stdin to your command or script but don't need to get the input from CLI, use [`use_stdin`](#use_stdin) option isntead.
 
 ## Script
 
@@ -1093,6 +1102,38 @@ commit-msg:
 
 When you try to commit `git commit -m "bad commit text"` script `template_checker` will be executed. Since commit text doesn't match the described pattern the commit process will be interrupted.
 
+### `use_stdin`
+
+Pass the stdin from the OS to the command/script.
+
+**Note**
+
+With many commands or scripts having `use_stdin: true`, only one will receive the data. The others will have nothing. If you need to pass the data from stdin to every command or script, please, submit a [feature request](https://github.com/evilmartians/lefthook/issues/new?assignees=&labels=feature+request&projects=&template=feature_request.md).
+
+**Example**
+
+Use this option for the `pre-push` hook when you have a script that does `while read ...`. Without this option lefthook will hang: lefthook uses [pseudo TTY](https://github.com/creack/pty) by default, and it doesn't close stdin when all data is read.
+
+```bash
+# .lefthook/pre-push/do-the-magic.sh
+
+remote="$1"
+url="$2"
+
+while read local_ref local_oid remote_ref remote_oid; do
+  # ...
+done
+```
+
+```yml
+# lefthook.yml
+pre-push:
+  scripts:
+    "do-the-magic.sh":
+      runner: bash
+      use_stdin: true
+```
+
 ### `runner`
 
 You should specify a runner for the script. This is a command that should execute a script file. It will be called the following way: `<runner> <path-to-script>` (e.g. `ruby .lefthook/pre-commit/lint.rb`).

docs/usage.md

@@ -19,6 +19,8 @@
   - [Concurrent files overrides](#concurrent-files-overrides)
   - [Capture ARGS from git in the script](#capture-args-from-git-in-the-script)
   - [Git LFS support](#git-lfs-support)
+  - [Pass stdin to a command or script](#pass-stdin-to-a-command-or-script)
+  - [Using an interactive command or script](#using-an-interactive-command-or-script)
 
 ----
 
@@ -304,3 +306,12 @@ Lefthook runs LFS hooks internally for the following hooks:
 - pre-push
 
 Errors are suppressed if git LFS is not required for the project. You can use [`LEFTHOOK_VERBOSE`](#lefthook_verbose) ENV to make lefthook show git LFS output.
+
+
+### Pass stdin to a command or script
+
+When you need to read the data from stdin – specify [`use_stdin: true`](./configuration.md#use_stdin). This option is good when you write a commands or scripts that receive data from git using stdin (for the `pre-push` hook, for example).
+
+### Using an interactive command or script
+
+When you need to interact with user – specify [`interactive: true`](./configuration.md#interactive). Lefthook will connect to the current TTY and forward it to your command's or script's stdin.