diff --git a/README.md b/README.md
index 9c01380..9ddb190 100644
--- a/README.md
+++ b/README.md
@@ -480,6 +480,34 @@ fake-newlines are removed on entering copy-mode and re-inserted
 on leaving copy mode. Also truncate-lines is set to t on entering
 copy-mode and set to nil on leaving.
 
+## `vterm-tramp-shells`
+
+The shell that gets run in the vterm for tramp.
+
+This has to be a list of pairs of the format:
+`(TRAMP-METHOD SHELL)`
+
+The `TRAMP-METHOD` is a method string as used by tramp (e.g., `"ssh"`).
+Use t as `TRAMP-METHOD` to specify a default shell for all methods.
+Specific methods always take precedence over `t`.
+
+Set SHELL to `'login-shell` to use the user's login shell on the remote host.
+The login-shell detection currently works for POSIX-compliant remote hosts that
+have the `getent` command (regular GNU/Linux distros, *BSDs, but not MacOS X
+unfortunately).
+You can specify an additional second `SHELL` command as a fallback
+that is used when the login-shell detection fails, e.g.,
+`'(("ssh" login-shell "/bin/bash") ...)`
+If no second `SHELL` command is specified with `'login-shell`, vterm will
+fall back to tramp's shell.
+
+Examples:
+- Usee the default login shell for all methods, except for docker.
+  `'((t login-shell) ("docker" "/bin/sh"))`
+- Use the default login shell for ssh and scp, fall back to "/bin/bash".
+  Use tramp's default shell for all other methods.
+  `'(("ssh" login-shell "/bin/bash") ("scp" login-shell "/bin/bash"))`
+
 ## Keybindings
 
 If you want a key to be sent to the terminal, bind it to `vterm--self-insert`,